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