uclean.h File Reference

C API: Initialize and clean up ICU. More...

#include "unicode/utypes.h"

Go to the source code of this file.

Typedefs
typedef void *	UMemAllocFn(const void *context, size_t size)
	Pointer type for a user supplied memory allocation function. More...
typedef void *	UMemReallocFn(const void *context, void *mem, size_t size)
	Pointer type for a user supplied memory re-allocation function. More...
typedef void	UMemFreeFn(const void *context, void *mem)
	Pointer type for a user supplied memory free function. More...
typedef void *	UMTX
	An opaque pointer type that represents an ICU mutex. More...
typedef void	UMtxInitFn(const void *context, UMTX *mutex, UErrorCode *status)
	Function Pointer type for a user supplied mutex initialization function. More...
typedef void	UMtxFn(const void *context, UMTX *mutex)
	Function Pointer type for a user supplied mutex functions. More...
typedef int32_t	UMtxAtomicFn(const void *context, int32_t *p)
	Pointer type for a user supplied atomic increment or decrement function. More...

Functions
void	u_init (UErrorCode *status)
	Initialize ICU. More...
void	u_cleanup (void)
	Clean up the system resources, such as allocated memory or open files, used in all ICU libraries. More...
void	u_setMemoryFunctions (const void *context, UMemAllocFn *a, UMemReallocFn *r, UMemFreeFn *f, UErrorCode *status)
	Set the functions that ICU will use for memory allocation. More...
void	u_setMutexFunctions (const void *context, UMtxInitFn *init, UMtxFn *destroy, UMtxFn *lock, UMtxFn *unlock, UErrorCode *status)
	Set the functions that ICU will use for mutex operations Use of this function is optional; by default (without this function), ICU will directly access system functions for mutex operations This function can only be used when ICU is in an initial, unused state, before u_init() has been called. More...
void	u_setAtomicIncDecFunctions (const void *context, UMtxAtomicFn *inc, UMtxAtomicFn *dec, UErrorCode *status)
	Set the functions that ICU will use for atomic increment and decrement of int32_t values. More...

Detailed Description

C API: Initialize and clean up ICU.

Definition in file uclean.h.

Typedef Documentation

UMemAllocFn

typedef void* UMemAllocFn(const void *context, size_t size)

Pointer type for a user supplied memory allocation function.

Parameters

context	user supplied value, obtained from u_setMemoryFunctions().
size	The number of bytes to be allocated

Returns

Pointer to the newly allocated memory, or NULL if the allocation failed.

Stable:

ICU 2.8

System:

Do not use unless you know what you are doing.

Definition at line 113 of file uclean.h.

UMemFreeFn

typedef void UMemFreeFn(const void *context, void *mem)

Pointer type for a user supplied memory free function.

Behavior should be similar the standard C library free().

Parameters

context	user supplied value, obtained from u_setMemoryFunctions().
mem	Pointer to the memory block to be resized
size	The new size for the block

Returns

Pointer to the resized memory block, or NULL if the resizing failed.

Stable:

ICU 2.8

System:

Do not use unless you know what you are doing.

Definition at line 133 of file uclean.h.

UMemReallocFn

typedef void* UMemReallocFn(const void *context, void *mem, size_t size)

Pointer type for a user supplied memory re-allocation function.

Parameters

context	user supplied value, obtained from u_setMemoryFunctions().
size	The number of bytes to be allocated

Returns

Pointer to the newly allocated memory, or NULL if the allocation failed.

Stable:

ICU 2.8

System:

Do not use unless you know what you are doing.

Definition at line 122 of file uclean.h.

UMTX

typedef void* UMTX

An opaque pointer type that represents an ICU mutex.

For user-implemented mutexes, the value will typically point to a struct or object that implements the mutex.

Deprecated:

ICU 52. This type is no longer supported.

System:

Do not use unless you know what you are doing.

Definition at line 174 of file uclean.h.

UMtxAtomicFn

typedef int32_t UMtxAtomicFn(const void *context, int32_t *p)

Pointer type for a user supplied atomic increment or decrement function.

Parameters

context	user supplied value, obtained from u_setAtomicIncDecFunctions().
p	Pointer to a 32 bit int to be incremented or decremented

Returns

The value of the variable after the inc or dec operation.

Deprecated:

ICU 52. This function is no longer supported.

System:

Do not use unless you know what you are doing.

Definition at line 238 of file uclean.h.

UMtxFn

typedef void UMtxFn(const void *context, UMTX *mutex)

Function Pointer type for a user supplied mutex functions.

One of the user-supplied functions with this signature will be called by ICU whenever ICU needs to lock, unlock, or destroy a mutex.

Parameters

context	user supplied value, obtained from u_setMutexFunctions().
mutex	specify the mutex on which to operate.

Deprecated:

ICU 52. This function is no longer supported.

System:

Do not use unless you know what you are doing.

Definition at line 205 of file uclean.h.

UMtxInitFn

typedef void UMtxInitFn(const void *context, UMTX *mutex, UErrorCode *status)

Function Pointer type for a user supplied mutex initialization function.

The user-supplied function will be called by ICU whenever ICU needs to create a new mutex. The function implementation should create a mutex, and store a pointer to something that uniquely identifies the mutex into the UMTX that is supplied as a parameter.

Parameters

context	user supplied value, obtained from u_setMutexFunctions().
mutex	Receives a pointer that identifies the new mutex. The mutex init function must set the UMTX to a non-null value. Subsequent calls by ICU to lock, unlock, or destroy a mutex will identify the mutex by the UMTX value.
status	Error status. Report errors back to ICU by setting this variable with an error code.

Deprecated:

ICU 52. This function is no longer supported.

System:

Do not use unless you know what you are doing.

Definition at line 193 of file uclean.h.

Function Documentation

u_cleanup()

void u_cleanup

(

void

)

Clean up the system resources, such as allocated memory or open files, used in all ICU libraries.

This will free/delete all memory owned by the ICU libraries, and return them to their original load state. All open ICU items (collators, resource bundles, converters, etc.) must be closed before calling this function, otherwise ICU may not free its allocated memory (e.g. close your converters and resource bundles before calling this function). Generally, this function should be called once just before an application exits. For applications that dynamically load and unload the ICU libraries (relatively uncommon), u_cleanup() should be called just before the library unload.

u_cleanup() also clears any ICU heap functions, mutex functions or trace functions that may have been set for the process. This has the effect of restoring ICU to its initial condition, before any of these override functions were installed. Refer to u_setMemoryFunctions(), u_setMutexFunctions and utrace_setFunctions(). If ICU is to be reinitialized after calling u_cleanup(), these runtime override functions will need to be set up again if they are still required.

u_cleanup() is not thread safe. All other threads should stop using ICU before calling this function.

Any open ICU items will be left in an undefined state by u_cleanup(), and any subsequent attempt to use such an item will give unpredictable results.

After calling u_cleanup(), an application may continue to use ICU by calling u_init(). An application must invoke u_init() first from one single thread before allowing other threads call u_init(). All threads existing at the time of the first thread's call to u_init() must also call u_init() themselves before continuing with other ICU operations.

The use of u_cleanup() just before an application terminates is optional, but it should be called only once for performance reasons. The primary benefit is to eliminate reports of memory or resource leaks originating in ICU code from the results generated by heap analysis tools.

Use this function with great care!

Stable:

ICU 2.0

System:

Do not use unless you know what you are doing.

u_init()

void u_init

(

UErrorCode *

status

)

Initialize ICU.

Use of this function is optional. It is OK to simply use ICU services and functions without first having initialized ICU by calling u_init().

u_init() will attempt to load some part of ICU's data, and is useful as a test for configuration or installation problems that leave the ICU data inaccessible. A successful invocation of u_init() does not, however, guarantee that all ICU data is accessible.

Multiple calls to u_init() cause no harm, aside from the small amount of time required.

In old versions of ICU, u_init() was required in multi-threaded applications to ensure the thread safety of ICU. u_init() is no longer needed for this purpose.

Parameters

status

An ICU UErrorCode parameter. It must not be NULL. An Error will be returned if some required part of ICU data can not be loaded or initialized. The function returns immediately if the input error code indicates a failure, as usual.

Stable:

ICU 2.6

u_setAtomicIncDecFunctions()

void u_setAtomicIncDecFunctions	(	const void *	context,
		UMtxAtomicFn *	inc,
		UMtxAtomicFn *	dec,
		UErrorCode *	status
	)

Set the functions that ICU will use for atomic increment and decrement of int32_t values.

Use of this function is optional; by default (without this function), ICU will use its own internal implementation of atomic increment/decrement. This function can only be used when ICU is in an initial, unused state, before u_init() has been called.

Parameters

context	This pointer value will be saved, and then (later) passed as a parameter to the increment and decrement functions each time they are called. This function can only be called
inc	Pointer to a function to do an atomic increment operation. Must be non-null.
dec	Pointer to a function to do an atomic decrement operation. Must be non-null.
status	Receives error values.

Deprecated:

ICU 52. This function is no longer supported.

System:

Do not use unless you know what you are doing.

u_setMemoryFunctions()

void u_setMemoryFunctions	(	const void *	context,
		UMemAllocFn *	a,
		UMemReallocFn *	r,
		UMemFreeFn *	f,
		UErrorCode *	status
	)

Set the functions that ICU will use for memory allocation.

Use of this function is optional; by default (without this function), ICU will use the standard C library malloc() and free() functions. This function can only be used when ICU is in an initial, unused state, before u_init() has been called.

Parameters

context	This pointer value will be saved, and then (later) passed as a parameter to the memory functions each time they are called.
a	Pointer to a user-supplied malloc function.
r	Pointer to a user-supplied realloc function.
f	Pointer to a user-supplied free function.
status	Receives error values.

Stable:

ICU 2.8

System:

Do not use unless you know what you are doing.

u_setMutexFunctions()

void u_setMutexFunctions	(	const void *	context,
		UMtxInitFn *	init,
		UMtxFn *	destroy,
		UMtxFn *	lock,
		UMtxFn *	unlock,
		UErrorCode *	status
	)

Set the functions that ICU will use for mutex operations Use of this function is optional; by default (without this function), ICU will directly access system functions for mutex operations This function can only be used when ICU is in an initial, unused state, before u_init() has been called.

Parameters

context	This pointer value will be saved, and then (later) passed as a parameter to the user-supplied mutex functions each time they are called.
init	Pointer to a mutex initialization function. Must be non-null.
destroy	Pointer to the mutex destroy function. Must be non-null.
lock	pointer to the mutex lock function. Must be non-null.
unlock	Pointer to the mutex unlock function. Must be non-null.
status	Receives error values.

Deprecated:

ICU 52. This function is no longer supported.

System:

Do not use unless you know what you are doing.