intl/icu/source/common/unicode/uclean.h@6474c204b198
intl/icu/source/common/unicode/uclean.h
Wed, 31 Dec 2014 06:09:35 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Wed, 31 Dec 2014 06:09:35 +0100
- changeset 0
- 6474c204b198
- permissions
- -rw-r--r--
Cloned upstream origin tor-browser at tor-browser-31.3.0esr-4.5-1-build1
revision ID fc1c9ff7c1b2defdbc039f12214767608f46423f for hacking purpose.
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 */
15 #ifndef __UCLEAN_H__
16 #define __UCLEAN_H__
18 #include "unicode/utypes.h"
19 /**
20 * \file
21 * \brief C API: Initialize and clean up ICU
22 */
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 */
50 U_STABLE void U_EXPORT2
51 u_init(UErrorCode *status);
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 */
99 U_STABLE void U_EXPORT2
100 u_cleanup(void);
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 */
111 typedef 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 */
120 typedef 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 */
131 typedef void U_CALLCONV UMemFreeFn (const void *context, void *mem);
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 */
149 U_STABLE void U_EXPORT2
150 u_setMemoryFunctions(const void *context, UMemAllocFn *a, UMemReallocFn *r, UMemFreeFn *f,
151 UErrorCode *status);
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 **********************************************************************************/
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 */
170 typedef void *UMTX;
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 */
188 typedef void U_CALLCONV UMtxInitFn (const void *context, UMTX *mutex, UErrorCode* status);
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 */
200 typedef void U_CALLCONV UMtxFn (const void *context, UMTX *mutex);
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 */
220 U_DEPRECATED void U_EXPORT2
221 u_setMutexFunctions(const void *context, UMtxInitFn *init, UMtxFn *destroy, UMtxFn *lock, UMtxFn *unlock,
222 UErrorCode *status);
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 */
233 typedef int32_t U_CALLCONV UMtxAtomicFn(const void *context, int32_t *p);
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 */
250 U_DEPRECATED void U_EXPORT2
251 u_setAtomicIncDecFunctions(const void *context, UMtxAtomicFn *inc, UMtxAtomicFn *dec,
252 UErrorCode *status);
254 #endif /* U_HIDE_SYSTEM_API */
256 #endif
