[apple/icu.git] / icuSources / common / unicode / uclean.h

// © 2016 and later: Unicode, Inc. and others.
// License & terms of use: http://www.unicode.org/copyright.html
/*
******************************************************************************
* Copyright (C) 2001-2014, International Business Machines
*                Corporation and others. All Rights Reserved.
******************************************************************************
*   file name:  uclean.h
*   encoding:   UTF-8
*   tab size:   8 (not used)
*   indentation:4
*
*   created on: 2001July05
*   created by: George Rhoten
*/

#ifndef __UCLEAN_H__
#define __UCLEAN_H__

#include "unicode/utypes.h"
/**
 * \file
 * \brief C API: Initialize and clean up ICU
 */
 
/**
 *  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.
 *
 * @param status An ICU UErrorCode parameter. It must not be <code>NULL</code>.
 *    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_STABLE void U_EXPORT2 
u_init(UErrorCode *status);

#ifndef U_HIDE_SYSTEM_API
/**
 * 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.
 * <p>
 * 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.
 * <p>
 * u_cleanup() is not thread safe.  All other threads should stop using ICU
 * before calling this function.
 * <p>
 * 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.
 * <p>
 * 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.  
 * <p>
 * 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.
 * <p>
 * <strong>Use this function with great care!</strong>
 * </p>
 *
 * @stable ICU 2.0
 * @system
 */
U_STABLE void U_EXPORT2 
u_cleanup(void);

U_CDECL_BEGIN
/**
  *  Pointer type for a user supplied memory allocation function.
  *  @param context user supplied value, obtained from u_setMemoryFunctions().
  *  @param size    The number of bytes to be allocated
  *  @return        Pointer to the newly allocated memory, or NULL if the allocation failed.
  *  @stable ICU 2.8
  *  @system
  */
typedef void *U_CALLCONV UMemAllocFn(const void *context, size_t size);
/**
  *  Pointer type for a user supplied memory re-allocation function.
  *  @param context user supplied value, obtained from u_setMemoryFunctions().
  *  @param size    The number of bytes to be allocated
  *  @return        Pointer to the newly allocated memory, or NULL if the allocation failed.
  *  @stable ICU 2.8
  *  @system
  */
typedef void *U_CALLCONV UMemReallocFn(const void *context, void *mem, size_t size);
/**
  *  Pointer type for a user supplied memory free  function.  Behavior should be
  *  similar the standard C library free().
  *  @param context user supplied value, obtained from u_setMemoryFunctions().
  *  @param mem     Pointer to the memory block to be resized
  *  @param size    The new size for the block
  *  @return        Pointer to the resized memory block, or NULL if the resizing failed.
  *  @stable ICU 2.8
  *  @system
  */
typedef void  U_CALLCONV UMemFreeFn (const void *context, void *mem);

/**
 *  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.
 *  @param context This pointer value will be saved, and then (later) passed as
 *                 a parameter to the memory functions each time they
 *                 are called.
 *  @param a       Pointer to a user-supplied malloc function.
 *  @param r       Pointer to a user-supplied realloc function.
 *  @param f       Pointer to a user-supplied free function.
 *  @param status  Receives error values.
 *  @stable ICU 2.8
 *  @system
 */  
U_STABLE void U_EXPORT2 
u_setMemoryFunctions(const void *context, UMemAllocFn * U_CALLCONV_FPTR a, UMemReallocFn * U_CALLCONV_FPTR r, UMemFreeFn * U_CALLCONV_FPTR f, 
                    UErrorCode *status);

U_CDECL_END

#ifndef U_HIDE_DEPRECATED_API
/*********************************************************************************
 *
 * Deprecated Functions
 *
 *    The following functions for user supplied mutexes are no longer supported.
 *    Any attempt to use them will return a U_UNSUPPORTED_ERROR.
 *
 **********************************************************************************/

/**
  * 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
  */
typedef void *UMTX;

U_CDECL_BEGIN
/**
  *  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.
  *  @param context user supplied value, obtained from u_setMutexFunctions().
  *  @param 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.
  *  @param 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
  */
typedef void U_CALLCONV UMtxInitFn (const void *context, UMTX  *mutex, UErrorCode* status);


/**
  *  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.
  *  @param context user supplied value, obtained from u_setMutexFunctions().
  *  @param mutex   specify the mutex on which to operate.
  *  @deprecated ICU 52. This function is no longer supported.
  *  @system
  */
typedef void U_CALLCONV UMtxFn   (const void *context, UMTX  *mutex);
U_CDECL_END

/**
  *  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.
  *  @param 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. 
  *  @param init    Pointer to a mutex initialization function.  Must be non-null.
  *  @param destroy Pointer to the mutex destroy function.  Must be non-null.
  *  @param lock    pointer to the mutex lock function.  Must be non-null.
  *  @param unlock  Pointer to the mutex unlock function.  Must be non-null.
  *  @param status  Receives error values.
  *  @deprecated ICU 52. This function is no longer supported.
  *  @system
  */  
U_DEPRECATED void U_EXPORT2 
u_setMutexFunctions(const void *context, UMtxInitFn *init, UMtxFn *destroy, UMtxFn *lock, UMtxFn *unlock,
                    UErrorCode *status);


/**
  *  Pointer type for a user supplied atomic increment or decrement function.
  *  @param context user supplied value, obtained from u_setAtomicIncDecFunctions().
  *  @param p   Pointer to a 32 bit int to be incremented or decremented
  *  @return    The value of the variable after the inc or dec operation.
  *  @deprecated ICU 52. This function is no longer supported.
  *  @system
  */
typedef int32_t U_CALLCONV UMtxAtomicFn(const void *context, int32_t *p);

/**
 *  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.
 *  @param 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 
 *  @param inc     Pointer to a function to do an atomic increment operation.  Must be non-null.
 *  @param dec     Pointer to a function to do an atomic decrement operation.  Must be non-null.
 *  @param status  Receives error values.
 *  @deprecated ICU 52. This function is no longer supported.
 *  @system
 */  
U_DEPRECATED void U_EXPORT2 
u_setAtomicIncDecFunctions(const void *context, UMtxAtomicFn *inc, UMtxAtomicFn *dec,
                    UErrorCode *status);

#endif  /* U_HIDE_DEPRECATED_API */
#endif  /* U_HIDE_SYSTEM_API */

#endif
Commit	Line	Data
f3c0d7a5 A	1	// © 2016 and later: Unicode, Inc. and others.
f3c0d7a5 A	2	// License & terms of use: http://www.unicode.org/copyright.html
b75a7d8f A	3	/*
b75a7d8f A	4	******************************************************************************
b331163b	5	* Copyright (C) 2001-2014, International Business Machines
4388f060	6	* Corporation and others. All Rights Reserved.
b75a7d8f A	7	******************************************************************************
b75a7d8f A	8	* file name: uclean.h
f3c0d7a5	9	* encoding: UTF-8
b75a7d8f A	10	* tab size: 8 (not used)
	11	* indentation:4
	12	*
	13	* created on: 2001July05
	14	* created by: George Rhoten
	15	*/
	16
	17	#ifndef __UCLEAN_H__
	18	#define __UCLEAN_H__
	19
	20	#include "unicode/utypes.h"
b75a7d8f	21	/**
73c04bcf A	22	* \file
	23	* \brief C API: Initialize and clean up ICU
	24	*/
	25
	26	/**
729e4ab9 A	27	* Initialize ICU.
	28	*
	29	* Use of this function is optional. It is OK to simply use ICU
	30	* services and functions without first having initialized
	31	* ICU by calling u_init().
	32	*
	33	* u_init() will attempt to load some part of ICU's data, and is
	34	* useful as a test for configuration or installation problems that
	35	* leave the ICU data inaccessible. A successful invocation of u_init()
	36	* does not, however, guarantee that all ICU data is accessible.
	37	*
	38	* Multiple calls to u_init() cause no harm, aside from the small amount
	39	* of time required.
	40	*
	41	* In old versions of ICU, u_init() was required in multi-threaded applications
	42	* to ensure the thread safety of ICU. u_init() is no longer needed for this purpose.
b75a7d8f	43	*
374ca955	44	* @param status An ICU UErrorCode parameter. It must not be <code>NULL</code>.
b75a7d8f A	45	* An Error will be returned if some required part of ICU data can not
	46	* be loaded or initialized.
	47	* The function returns immediately if the input error code indicates a
	48	* failure, as usual.
	49	*
374ca955	50	* @stable ICU 2.6
b75a7d8f	51	*/
374ca955	52	U_STABLE void U_EXPORT2
b75a7d8f A	53	u_init(UErrorCode *status);
b75a7d8f A	54
4388f060	55	#ifndef U_HIDE_SYSTEM_API
b75a7d8f A	56	/**
	57	* Clean up the system resources, such as allocated memory or open files,
	58	* used in all ICU libraries. This will free/delete all memory owned by the
	59	* ICU libraries, and return them to their original load state. All open ICU
	60	* items (collators, resource bundles, converters, etc.) must be closed before
	61	* calling this function, otherwise ICU may not free its allocated memory
	62	* (e.g. close your converters and resource bundles before calling this
	63	* function). Generally, this function should be called once just before
	64	* an application exits. For applications that dynamically load and unload
	65	* the ICU libraries (relatively uncommon), u_cleanup() should be called
	66	* just before the library unload.
	67	* <p>
374ca955 A	68	* u_cleanup() also clears any ICU heap functions, mutex functions or
	69	* trace functions that may have been set for the process.
	70	* This has the effect of restoring ICU to its initial condition, before
	71	* any of these override functions were installed. Refer to
	72	* u_setMemoryFunctions(), u_setMutexFunctions and
0f5d89e8	73	* utrace_setFunctions(). If ICU is to be reinitialized after
374ca955 A	74	* calling u_cleanup(), these runtime override functions will need to
	75	* be set up again if they are still required.
	76	* <p>
b75a7d8f A	77	* u_cleanup() is not thread safe. All other threads should stop using ICU
	78	* before calling this function.
	79	* <p>
	80	* Any open ICU items will be left in an undefined state by u_cleanup(),
	81	* and any subsequent attempt to use such an item will give unpredictable
	82	* results.
	83	* <p>
	84	* After calling u_cleanup(), an application may continue to use ICU by
	85	* calling u_init(). An application must invoke u_init() first from one single
	86	* thread before allowing other threads call u_init(). All threads existing
	87	* at the time of the first thread's call to u_init() must also call
	88	* u_init() themselves before continuing with other ICU operations.
	89	* <p>
	90	* The use of u_cleanup() just before an application terminates is optional,
	91	* but it should be called only once for performance reasons. The primary
	92	* benefit is to eliminate reports of memory or resource leaks originating
	93	* in ICU code from the results generated by heap analysis tools.
	94	* <p>
	95	* <strong>Use this function with great care!</strong>
	96	* </p>
	97	*
	98	* @stable ICU 2.0
	99	* @system
	100	*/
374ca955	101	U_STABLE void U_EXPORT2
b75a7d8f A	102	u_cleanup(void);
b75a7d8f A	103
f3c0d7a5	104	U_CDECL_BEGIN
57a6839d A	105	/**
57a6839d A	106	* Pointer type for a user supplied memory allocation function.
0f5d89e8	107	* @param context user supplied value, obtained from u_setMemoryFunctions().
57a6839d A	108	* @param size The number of bytes to be allocated
	109	* @return Pointer to the newly allocated memory, or NULL if the allocation failed.
	110	* @stable ICU 2.8
	111	* @system
	112	*/
	113	typedef void U_CALLCONV UMemAllocFn(const void context, size_t size);
	114	/**
	115	* Pointer type for a user supplied memory re-allocation function.
0f5d89e8	116	* @param context user supplied value, obtained from u_setMemoryFunctions().
57a6839d A	117	* @param size The number of bytes to be allocated
	118	* @return Pointer to the newly allocated memory, or NULL if the allocation failed.
	119	* @stable ICU 2.8
	120	* @system
	121	*/
	122	typedef void U_CALLCONV UMemReallocFn(const void context, void *mem, size_t size);
	123	/**
	124	* Pointer type for a user supplied memory free function. Behavior should be
	125	* similar the standard C library free().
0f5d89e8	126	* @param context user supplied value, obtained from u_setMemoryFunctions().
57a6839d A	127	* @param mem Pointer to the memory block to be resized
	128	* @param size The new size for the block
	129	* @return Pointer to the resized memory block, or NULL if the resizing failed.
	130	* @stable ICU 2.8
	131	* @system
	132	*/
	133	typedef void U_CALLCONV UMemFreeFn (const void context, void mem);
	134
	135	/**
	136	* Set the functions that ICU will use for memory allocation.
	137	* Use of this function is optional; by default (without this function), ICU will
	138	* use the standard C library malloc() and free() functions.
	139	* This function can only be used when ICU is in an initial, unused state, before
	140	* u_init() has been called.
	141	* @param context This pointer value will be saved, and then (later) passed as
	142	* a parameter to the memory functions each time they
	143	* are called.
	144	* @param a Pointer to a user-supplied malloc function.
	145	* @param r Pointer to a user-supplied realloc function.
	146	* @param f Pointer to a user-supplied free function.
	147	* @param status Receives error values.
	148	* @stable ICU 2.8
	149	* @system
	150	*/
	151	U_STABLE void U_EXPORT2
0f5d89e8	152	u_setMemoryFunctions(const void context, UMemAllocFn U_CALLCONV_FPTR a, UMemReallocFn * U_CALLCONV_FPTR r, UMemFreeFn * U_CALLCONV_FPTR f,
57a6839d	153	UErrorCode *status);
374ca955	154
f3c0d7a5	155	U_CDECL_END
374ca955	156
b331163b	157	#ifndef U_HIDE_DEPRECATED_API
57a6839d A	158	/*********************************************************************************
	159	*
	160	* Deprecated Functions
	161	*
	162	* The following functions for user supplied mutexes are no longer supported.
	163	* Any attempt to use them will return a U_UNSUPPORTED_ERROR.
	164	*
	165	**********************************************************************************/
	166
374ca955 A	167	/**
	168	* An opaque pointer type that represents an ICU mutex.
	169	* For user-implemented mutexes, the value will typically point to a
	170	* struct or object that implements the mutex.
57a6839d	171	* @deprecated ICU 52. This type is no longer supported.
374ca955 A	172	* @system
	173	*/
	174	typedef void *UMTX;
	175
f3c0d7a5	176	U_CDECL_BEGIN
374ca955 A	177	/**
	178	* Function Pointer type for a user supplied mutex initialization function.
	179	* The user-supplied function will be called by ICU whenever ICU needs to create a
	180	* new mutex. The function implementation should create a mutex, and store a pointer
	181	* to something that uniquely identifies the mutex into the UMTX that is supplied
0f5d89e8 A	182	* as a parameter.
0f5d89e8 A	183	* @param context user supplied value, obtained from u_setMutexFunctions().
374ca955 A	184	* @param mutex Receives a pointer that identifies the new mutex.
	185	* The mutex init function must set the UMTX to a non-null value.
	186	* Subsequent calls by ICU to lock, unlock, or destroy a mutex will
	187	* identify the mutex by the UMTX value.
	188	* @param status Error status. Report errors back to ICU by setting this variable
	189	* with an error code.
57a6839d	190	* @deprecated ICU 52. This function is no longer supported.
374ca955 A	191	* @system
	192	*/
	193	typedef void U_CALLCONV UMtxInitFn (const void context, UMTX mutex, UErrorCode* status);
	194
	195
	196	/**
	197	* Function Pointer type for a user supplied mutex functions.
	198	* One of the user-supplied functions with this signature will be called by ICU
	199	* whenever ICU needs to lock, unlock, or destroy a mutex.
0f5d89e8	200	* @param context user supplied value, obtained from u_setMutexFunctions().
374ca955	201	* @param mutex specify the mutex on which to operate.
57a6839d	202	* @deprecated ICU 52. This function is no longer supported.
374ca955 A	203	* @system
	204	*/
	205	typedef void U_CALLCONV UMtxFn (const void context, UMTX mutex);
f3c0d7a5	206	U_CDECL_END
374ca955 A	207
	208	/**
	209	* Set the functions that ICU will use for mutex operations
	210	* Use of this function is optional; by default (without this function), ICU will
	211	* directly access system functions for mutex operations
	212	* This function can only be used when ICU is in an initial, unused state, before
	213	* u_init() has been called.
374ca955 A	214	* @param context This pointer value will be saved, and then (later) passed as
	215	* a parameter to the user-supplied mutex functions each time they
	216	* are called.
	217	* @param init Pointer to a mutex initialization function. Must be non-null.
	218	* @param destroy Pointer to the mutex destroy function. Must be non-null.
	219	* @param lock pointer to the mutex lock function. Must be non-null.
	220	* @param unlock Pointer to the mutex unlock function. Must be non-null.
	221	* @param status Receives error values.
57a6839d	222	* @deprecated ICU 52. This function is no longer supported.
374ca955 A	223	* @system
374ca955 A	224	*/
57a6839d	225	U_DEPRECATED void U_EXPORT2
374ca955 A	226	u_setMutexFunctions(const void context, UMtxInitFn init, UMtxFn destroy, UMtxFn lock, UMtxFn *unlock,
	227	UErrorCode *status);
	228
	229
	230	/**
	231	* Pointer type for a user supplied atomic increment or decrement function.
0f5d89e8	232	* @param context user supplied value, obtained from u_setAtomicIncDecFunctions().
374ca955 A	233	* @param p Pointer to a 32 bit int to be incremented or decremented
374ca955 A	234	* @return The value of the variable after the inc or dec operation.
57a6839d	235	* @deprecated ICU 52. This function is no longer supported.
374ca955 A	236	* @system
	237	*/
	238	typedef int32_t U_CALLCONV UMtxAtomicFn(const void context, int32_t p);
	239
	240	/**
	241	* Set the functions that ICU will use for atomic increment and decrement of int32_t values.
	242	* Use of this function is optional; by default (without this function), ICU will
	243	* use its own internal implementation of atomic increment/decrement.
	244	* This function can only be used when ICU is in an initial, unused state, before
	245	* u_init() has been called.
	246	* @param context This pointer value will be saved, and then (later) passed as
	247	* a parameter to the increment and decrement functions each time they
	248	* are called. This function can only be called
	249	* @param inc Pointer to a function to do an atomic increment operation. Must be non-null.
	250	* @param dec Pointer to a function to do an atomic decrement operation. Must be non-null.
	251	* @param status Receives error values.
57a6839d	252	* @deprecated ICU 52. This function is no longer supported.
374ca955 A	253	* @system
374ca955 A	254	*/
57a6839d	255	U_DEPRECATED void U_EXPORT2
374ca955 A	256	u_setAtomicIncDecFunctions(const void context, UMtxAtomicFn inc, UMtxAtomicFn *dec,
	257	UErrorCode *status);
	258
b331163b	259	#endif /* U_HIDE_DEPRECATED_API */
4388f060	260	#endif /* U_HIDE_SYSTEM_API */
374ca955	261
b75a7d8f	262	#endif