source/common/unicode/uclean.h

   1 // Copyright (C) 2016 and later: Unicode, Inc. and others.
   2 // License & terms of use: http://www.unicode.org/copyright.html
   3 /*
   4 ******************************************************************************
   5 * Copyright (C) 2001-2014, International Business Machines
   6 *                Corporation and others. All Rights Reserved.
   7 ******************************************************************************
   8 *   file name:  uclean.h
   9 *   encoding:   US-ASCII
  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"
  21 /**
  22  * \file
  23  * \brief C API: Initialize and clean up ICU
  24  */
  25
  26 /**
  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.
  43  *
  44  * @param status An ICU UErrorCode parameter. It must not be <code>NULL</code>.
  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  *
  50  * @stable ICU 2.6
  51  */
  52 U_STABLE void U_EXPORT2
  53 u_init(UErrorCode *status);
  54
  55 #ifndef U_HIDE_SYSTEM_API
  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>
  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
  73  * utrace_setFunctions().  If ICU is to be reinitialized after after
  74  * calling u_cleanup(), these runtime override functions will need to
  75  * be set up again if they are still required.
  76  * <p>
  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  */
 101 U_STABLE void U_EXPORT2
 102 u_cleanup(void);
 103
 104
 105 /**
 106   *  Pointer type for a user supplied memory allocation function.
 107   *  @param context user supplied value, obtained from from u_setMemoryFunctions().
 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.
 116   *  @param context user supplied value, obtained from from u_setMemoryFunctions().
 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().
 126   *  @param context user supplied value, obtained from from u_setMemoryFunctions().
 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
 152 u_setMemoryFunctions(const void *context, UMemAllocFn *a, UMemReallocFn *r, UMemFreeFn *f,
 153                     UErrorCode *status);
 154
 155
 156 #ifndef U_HIDE_DEPRECATED_API
 157 /*********************************************************************************
 158  *
 159  * Deprecated Functions
 160  *
 161  *    The following functions for user supplied mutexes are no longer supported.
 162  *    Any attempt to use them will return a U_UNSUPPORTED_ERROR.
 163  *
 164  **********************************************************************************/
 165
 166 /**
 167   * An opaque pointer type that represents an ICU mutex.
 168   * For user-implemented mutexes, the value will typically point to a
 169   *  struct or object that implements the mutex.
 170   * @deprecated ICU 52. This type is no longer supported.
 171   * @system
 172   */
 173 typedef void *UMTX;
 174
 175 /**
 176   *  Function Pointer type for a user supplied mutex initialization function.
 177   *  The user-supplied function will be called by ICU whenever ICU needs to create a
 178   *  new mutex.  The function implementation should create a mutex, and store a pointer
 179   *  to something that uniquely identifies the mutex into the UMTX that is supplied
 180   *  as a paramter.
 181   *  @param context user supplied value, obtained from from u_setMutexFunctions().
 182   *  @param mutex   Receives a pointer that identifies the new mutex.
 183   *                 The mutex init function must set the UMTX to a non-null value.
 184   *                 Subsequent calls by ICU to lock, unlock, or destroy a mutex will
 185   *                 identify the mutex by the UMTX value.
 186   *  @param status  Error status.  Report errors back to ICU by setting this variable
 187   *                 with an error code.
 188   *  @deprecated ICU 52. This function is no longer supported.
 189   *  @system
 190   */
 191 typedef void U_CALLCONV UMtxInitFn (const void *context, UMTX  *mutex, UErrorCode* status);
 192
 193
 194 /**
 195   *  Function Pointer type for a user supplied mutex functions.
 196   *  One of the  user-supplied functions with this signature will be called by ICU
 197   *  whenever ICU needs to lock, unlock, or destroy a mutex.
 198   *  @param context user supplied value, obtained from from u_setMutexFunctions().
 199   *  @param mutex   specify the mutex on which to operate.
 200   *  @deprecated ICU 52. This function is no longer supported.
 201   *  @system
 202   */
 203 typedef void U_CALLCONV UMtxFn   (const void *context, UMTX  *mutex);
 204
 205
 206 /**
 207   *  Set the functions that ICU will use for mutex operations
 208   *  Use of this function is optional; by default (without this function), ICU will
 209   *  directly access system functions for mutex operations
 210   *  This function can only be used when ICU is in an initial, unused state, before
 211   *  u_init() has been called.
 212   *  @param context This pointer value will be saved, and then (later) passed as
 213   *                 a parameter to the user-supplied mutex functions each time they
 214   *                 are called.
 215   *  @param init    Pointer to a mutex initialization function.  Must be non-null.
 216   *  @param destroy Pointer to the mutex destroy function.  Must be non-null.
 217   *  @param lock    pointer to the mutex lock function.  Must be non-null.
 218   *  @param unlock  Pointer to the mutex unlock function.  Must be non-null.
 219   *  @param status  Receives error values.
 220   *  @deprecated ICU 52. This function is no longer supported.
 221   *  @system
 222   */
 223 U_DEPRECATED void U_EXPORT2
 224 u_setMutexFunctions(const void *context, UMtxInitFn *init, UMtxFn *destroy, UMtxFn *lock, UMtxFn *unlock,
 225                     UErrorCode *status);
 226
 227
 228 /**
 229   *  Pointer type for a user supplied atomic increment or decrement function.
 230   *  @param context user supplied value, obtained from from u_setAtomicIncDecFunctions().
 231   *  @param p   Pointer to a 32 bit int to be incremented or decremented
 232   *  @return    The value of the variable after the inc or dec operation.
 233   *  @deprecated ICU 52. This function is no longer supported.
 234   *  @system
 235   */
 236 typedef int32_t U_CALLCONV UMtxAtomicFn(const void *context, int32_t *p);
 237
 238 /**
 239  *  Set the functions that ICU will use for atomic increment and decrement of int32_t values.
 240  *  Use of this function is optional; by default (without this function), ICU will
 241  *  use its own internal implementation of atomic increment/decrement.
 242  *  This function can only be used when ICU is in an initial, unused state, before
 243  *  u_init() has been called.
 244  *  @param context This pointer value will be saved, and then (later) passed as
 245  *                 a parameter to the increment and decrement functions each time they
 246  *                 are called.  This function can only be called
 247  *  @param inc     Pointer to a function to do an atomic increment operation.  Must be non-null.
 248  *  @param dec     Pointer to a function to do an atomic decrement operation.  Must be non-null.
 249  *  @param status  Receives error values.
 250  *  @deprecated ICU 52. This function is no longer supported.
 251  *  @system
 252  */
 253 U_DEPRECATED void U_EXPORT2
 254 u_setAtomicIncDecFunctions(const void *context, UMtxAtomicFn *inc, UMtxAtomicFn *dec,
 255                     UErrorCode *status);
 256
 257 #endif  /* U_HIDE_DEPRECATED_API */
 258 #endif  /* U_HIDE_SYSTEM_API */
 259
 260 #endif