1/*
2******************************************************************************
3* Copyright (C) 2001-2012, 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
105/**
106  * An opaque pointer type that represents an ICU mutex.
107  * For user-implemented mutexes, the value will typically point to a
108  *  struct or object that implements the mutex.
109  * @stable ICU 2.8
110  * @system
111  */
112typedef void *UMTX;
113
114/**
115  *  Function Pointer type for a user supplied mutex initialization function.
116  *  The user-supplied function will be called by ICU whenever ICU needs to create a
117  *  new mutex.  The function implementation should create a mutex, and store a pointer
118  *  to something that uniquely identifies the mutex into the UMTX that is supplied
119  *  as a paramter.
120  *  @param context user supplied value, obtained from from u_setMutexFunctions().
121  *  @param mutex   Receives a pointer that identifies the new mutex.
122  *                 The mutex init function must set the UMTX to a non-null value.
123  *                 Subsequent calls by ICU to lock, unlock, or destroy a mutex will
124  *                 identify the mutex by the UMTX value.
125  *  @param status  Error status.  Report errors back to ICU by setting this variable
126  *                 with an error code.
127  *  @stable ICU 2.8
128  *  @system
129  */
130typedef void U_CALLCONV UMtxInitFn (const void *context, UMTX  *mutex, UErrorCode* status);
131
132
133/**
134  *  Function Pointer type for a user supplied mutex functions.
135  *  One of the  user-supplied functions with this signature will be called by ICU
136  *  whenever ICU needs to lock, unlock, or destroy a mutex.
137  *  @param context user supplied value, obtained from from u_setMutexFunctions().
138  *  @param mutex   specify the mutex on which to operate.
139  *  @stable ICU 2.8
140  *  @system
141  */
142typedef void U_CALLCONV UMtxFn   (const void *context, UMTX  *mutex);
143
144
145/**
146  *  Set the functions that ICU will use for mutex operations
147  *  Use of this function is optional; by default (without this function), ICU will
148  *  directly access system functions for mutex operations
149  *  This function can only be used when ICU is in an initial, unused state, before
150  *  u_init() has been called.
151  *  @param context This pointer value will be saved, and then (later) passed as
152  *                 a parameter to the user-supplied mutex functions each time they
153  *                 are called.
154  *  @param init    Pointer to a mutex initialization function.  Must be non-null.
155  *  @param destroy Pointer to the mutex destroy function.  Must be non-null.
156  *  @param lock    pointer to the mutex lock function.  Must be non-null.
157  *  @param unlock  Pointer to the mutex unlock function.  Must be non-null.
158  *  @param status  Receives error values.
159  *  @stable ICU 2.8
160  *  @system
161  */
162U_STABLE void U_EXPORT2
163u_setMutexFunctions(const void *context, UMtxInitFn *init, UMtxFn *destroy, UMtxFn *lock, UMtxFn *unlock,
164                    UErrorCode *status);
165
166
167/**
168  *  Pointer type for a user supplied atomic increment or decrement function.
169  *  @param context user supplied value, obtained from from u_setAtomicIncDecFunctions().
170  *  @param p   Pointer to a 32 bit int to be incremented or decremented
171  *  @return    The value of the variable after the inc or dec operation.
172  *  @stable ICU 2.8
173  *  @system
174  */
175typedef int32_t U_CALLCONV UMtxAtomicFn(const void *context, int32_t *p);
176
177/**
178 *  Set the functions that ICU will use for atomic increment and decrement of int32_t values.
179 *  Use of this function is optional; by default (without this function), ICU will
180 *  use its own internal implementation of atomic increment/decrement.
181 *  This function can only be used when ICU is in an initial, unused state, before
182 *  u_init() has been called.
183 *  @param context This pointer value will be saved, and then (later) passed as
184 *                 a parameter to the increment and decrement functions each time they
185 *                 are called.  This function can only be called
186 *  @param inc     Pointer to a function to do an atomic increment operation.  Must be non-null.
187 *  @param dec     Pointer to a function to do an atomic decrement operation.  Must be non-null.
188 *  @param status  Receives error values.
189 *  @stable ICU 2.8
190 *  @system
191 */
192U_STABLE void U_EXPORT2
193u_setAtomicIncDecFunctions(const void *context, UMtxAtomicFn *inc, UMtxAtomicFn *dec,
194                    UErrorCode *status);
195
196
197
198/**
199  *  Pointer type for a user supplied memory allocation function.
200  *  @param context user supplied value, obtained from from u_setMemoryFunctions().
201  *  @param size    The number of bytes to be allocated
202  *  @return        Pointer to the newly allocated memory, or NULL if the allocation failed.
203  *  @stable ICU 2.8
204  *  @system
205  */
206typedef void *U_CALLCONV UMemAllocFn(const void *context, size_t size);
207/**
208  *  Pointer type for a user supplied memory re-allocation function.
209  *  @param context user supplied value, obtained from from u_setMemoryFunctions().
210  *  @param size    The number of bytes to be allocated
211  *  @return        Pointer to the newly allocated memory, or NULL if the allocation failed.
212  *  @stable ICU 2.8
213  *  @system
214  */
215typedef void *U_CALLCONV UMemReallocFn(const void *context, void *mem, size_t size);
216/**
217  *  Pointer type for a user supplied memory free  function.  Behavior should be
218  *  similar the standard C library free().
219  *  @param context user supplied value, obtained from from u_setMemoryFunctions().
220  *  @param mem     Pointer to the memory block to be resized
221  *  @param size    The new size for the block
222  *  @return        Pointer to the resized memory block, or NULL if the resizing failed.
223  *  @stable ICU 2.8
224  *  @system
225  */
226typedef void  U_CALLCONV UMemFreeFn (const void *context, void *mem);
227
228/**
229 *  Set the functions that ICU will use for memory allocation.
230 *  Use of this function is optional; by default (without this function), ICU will
231 *  use the standard C library malloc() and free() functions.
232 *  This function can only be used when ICU is in an initial, unused state, before
233 *  u_init() has been called.
234 *  @param context This pointer value will be saved, and then (later) passed as
235 *                 a parameter to the memory functions each time they
236 *                 are called.
237 *  @param a       Pointer to a user-supplied malloc function.
238 *  @param r       Pointer to a user-supplied realloc function.
239 *  @param f       Pointer to a user-supplied free function.
240 *  @param status  Receives error values.
241 *  @stable ICU 2.8
242 *  @system
243 */
244U_STABLE void U_EXPORT2
245u_setMemoryFunctions(const void *context, UMemAllocFn *a, UMemReallocFn *r, UMemFreeFn *f,
246                    UErrorCode *status);
247#endif  /* U_HIDE_SYSTEM_API */
248
249#endif
250