Back to home page

EIC code displayed by LXR

 
 

    


Warning, file /include/unicode/uclean.h was not indexed or was modified since last indexation (in which case cross-reference links may be missing, inaccurate or erroneous).

0001 // © 2016 and later: Unicode, Inc. and others.
0002 // License & terms of use: http://www.unicode.org/copyright.html
0003 /*
0004 ******************************************************************************
0005 * Copyright (C) 2001-2014, International Business Machines
0006 *                Corporation and others. All Rights Reserved.
0007 ******************************************************************************
0008 *   file name:  uclean.h
0009 *   encoding:   UTF-8
0010 *   tab size:   8 (not used)
0011 *   indentation:4
0012 *
0013 *   created on: 2001July05
0014 *   created by: George Rhoten
0015 */
0016 
0017 #ifndef __UCLEAN_H__
0018 #define __UCLEAN_H__
0019 
0020 #include "unicode/utypes.h"
0021 /**
0022  * \file
0023  * \brief C API: Initialize and clean up ICU
0024  */
0025  
0026 /**
0027  *  Initialize ICU.
0028  *
0029  *  Use of this function is optional.  It is OK to simply use ICU
0030  *  services and functions without first having initialized
0031  *  ICU by calling u_init().
0032  *
0033  *  u_init() will attempt to load some part of ICU's data, and is
0034  *  useful as a test for configuration or installation problems that
0035  *  leave the ICU data inaccessible.  A successful invocation of u_init()
0036  *  does not, however, guarantee that all ICU data is accessible.
0037  *
0038  *  Multiple calls to u_init() cause no harm, aside from the small amount
0039  *  of time required.
0040  *
0041  *  In old versions of ICU, u_init() was required in multi-threaded applications
0042  *  to ensure the thread safety of ICU.  u_init() is no longer needed for this purpose.
0043  *
0044  * @param status An ICU UErrorCode parameter. It must not be <code>NULL</code>.
0045  *    An Error will be returned if some required part of ICU data can not
0046  *    be loaded or initialized.
0047  *    The function returns immediately if the input error code indicates a
0048  *    failure, as usual.
0049  *
0050  * @stable ICU 2.6
0051  */  
0052 U_CAPI void U_EXPORT2 
0053 u_init(UErrorCode *status);
0054 
0055 #ifndef U_HIDE_SYSTEM_API
0056 /**
0057  * Clean up the system resources, such as allocated memory or open files,
0058  * used in all ICU libraries. This will free/delete all memory owned by the
0059  * ICU libraries, and return them to their original load state. All open ICU
0060  * items (collators, resource bundles, converters, etc.) must be closed before
0061  * calling this function, otherwise ICU may not free its allocated memory
0062  * (e.g. close your converters and resource bundles before calling this
0063  * function). Generally, this function should be called once just before
0064  * an application exits. For applications that dynamically load and unload
0065  * the ICU libraries (relatively uncommon), u_cleanup() should be called
0066  * just before the library unload.
0067  * <p>
0068  * u_cleanup() also clears any ICU heap functions, mutex functions or
0069  * trace functions that may have been set for the process.  
0070  * This has the effect of restoring ICU to its initial condition, before
0071  * any of these override functions were installed.  Refer to
0072  * u_setMemoryFunctions(), u_setMutexFunctions and 
0073  * utrace_setFunctions().  If ICU is to be reinitialized after
0074  * calling u_cleanup(), these runtime override functions will need to
0075  * be set up again if they are still required.
0076  * <p>
0077  * u_cleanup() is not thread safe.  All other threads should stop using ICU
0078  * before calling this function.
0079  * <p>
0080  * Any open ICU items will be left in an undefined state by u_cleanup(),
0081  * and any subsequent attempt to use such an item will give unpredictable
0082  * results.
0083  * <p>
0084  * After calling u_cleanup(), an application may continue to use ICU by
0085  * calling u_init().  An application must invoke u_init() first from one single
0086  * thread before allowing other threads call u_init().  All threads existing
0087  * at the time of the first thread's call to u_init() must also call
0088  * u_init() themselves before continuing with other ICU operations.  
0089  * <p>
0090  * The use of u_cleanup() just before an application terminates is optional,
0091  * but it should be called only once for performance reasons. The primary
0092  * benefit is to eliminate reports of memory or resource leaks originating
0093  * in ICU code from the results generated by heap analysis tools.
0094  * <p>
0095  * <strong>Use this function with great care!</strong>
0096  * </p>
0097  *
0098  * @stable ICU 2.0
0099  * @system
0100  */
0101 U_CAPI void U_EXPORT2 
0102 u_cleanup(void);
0103 
0104 U_CDECL_BEGIN
0105 /**
0106   *  Pointer type for a user supplied memory allocation function.
0107   *  @param context user supplied value, obtained from u_setMemoryFunctions().
0108   *  @param size    The number of bytes to be allocated
0109   *  @return        Pointer to the newly allocated memory, or NULL if the allocation failed.
0110   *  @stable ICU 2.8
0111   *  @system
0112   */
0113 typedef void *U_CALLCONV UMemAllocFn(const void *context, size_t size);
0114 /**
0115   *  Pointer type for a user supplied memory re-allocation function.
0116   *  @param context user supplied value, obtained from u_setMemoryFunctions().
0117   *  @param mem     Pointer to the memory block to be resized.
0118   *  @param size    The new size for the block.
0119   *  @return        Pointer to the newly allocated memory, or NULL if the allocation failed.
0120   *  @stable ICU 2.8
0121   *  @system
0122   */
0123 typedef void *U_CALLCONV UMemReallocFn(const void *context, void *mem, size_t size);
0124 /**
0125   *  Pointer type for a user supplied memory free  function.  Behavior should be
0126   *  similar the standard C library free().
0127   *  @param context user supplied value, obtained from u_setMemoryFunctions().
0128   *  @param mem     Pointer to the memory block to be freed.
0129   *  @return        Pointer to the resized memory block, or NULL if the resizing failed.
0130   *  @stable ICU 2.8
0131   *  @system
0132   */
0133 typedef void  U_CALLCONV UMemFreeFn (const void *context, void *mem);
0134 
0135 /**
0136  *  Set the functions that ICU will use for memory allocation.
0137  *  Use of this function is optional; by default (without this function), ICU will
0138  *  use the standard C library malloc() and free() functions.
0139  *  This function can only be used when ICU is in an initial, unused state, before
0140  *  u_init() has been called.
0141  *  @param context This pointer value will be saved, and then (later) passed as
0142  *                 a parameter to the memory functions each time they
0143  *                 are called.
0144  *  @param a       Pointer to a user-supplied malloc function.
0145  *  @param r       Pointer to a user-supplied realloc function.
0146  *  @param f       Pointer to a user-supplied free function.
0147  *  @param status  Receives error values.
0148  *  @stable ICU 2.8
0149  *  @system
0150  */  
0151 U_CAPI void U_EXPORT2 
0152 u_setMemoryFunctions(const void *context, UMemAllocFn * U_CALLCONV_FPTR a, UMemReallocFn * U_CALLCONV_FPTR r, UMemFreeFn * U_CALLCONV_FPTR f, 
0153                     UErrorCode *status);
0154 
0155 U_CDECL_END
0156 
0157 #ifndef U_HIDE_DEPRECATED_API
0158 /*********************************************************************************
0159  *
0160  * Deprecated Functions
0161  *
0162  *    The following functions for user supplied mutexes are no longer supported.
0163  *    Any attempt to use them will return a U_UNSUPPORTED_ERROR.
0164  *
0165  **********************************************************************************/
0166 
0167 /**
0168   * An opaque pointer type that represents an ICU mutex.
0169   * For user-implemented mutexes, the value will typically point to a
0170   *  struct or object that implements the mutex.
0171   * @deprecated ICU 52. This type is no longer supported.
0172   * @system
0173   */
0174 typedef void *UMTX;
0175 
0176 U_CDECL_BEGIN
0177 /**
0178   *  Function Pointer type for a user supplied mutex initialization function.
0179   *  The user-supplied function will be called by ICU whenever ICU needs to create a
0180   *  new mutex.  The function implementation should create a mutex, and store a pointer
0181   *  to something that uniquely identifies the mutex into the UMTX that is supplied
0182   *  as a parameter.
0183   *  @param context user supplied value, obtained from u_setMutexFunctions().
0184   *  @param mutex   Receives a pointer that identifies the new mutex.
0185   *                 The mutex init function must set the UMTX to a non-null value.   
0186   *                 Subsequent calls by ICU to lock, unlock, or destroy a mutex will 
0187   *                 identify the mutex by the UMTX value.
0188   *  @param status  Error status.  Report errors back to ICU by setting this variable
0189   *                 with an error code.
0190   *  @deprecated ICU 52. This function is no longer supported.
0191   *  @system
0192   */
0193 typedef void U_CALLCONV UMtxInitFn (const void *context, UMTX  *mutex, UErrorCode* status);
0194 
0195 
0196 /**
0197   *  Function Pointer type for a user supplied mutex functions.
0198   *  One of the  user-supplied functions with this signature will be called by ICU
0199   *  whenever ICU needs to lock, unlock, or destroy a mutex.
0200   *  @param context user supplied value, obtained from u_setMutexFunctions().
0201   *  @param mutex   specify the mutex on which to operate.
0202   *  @deprecated ICU 52. This function is no longer supported.
0203   *  @system
0204   */
0205 typedef void U_CALLCONV UMtxFn   (const void *context, UMTX  *mutex);
0206 U_CDECL_END
0207 
0208 /**
0209   *  Set the functions that ICU will use for mutex operations
0210   *  Use of this function is optional; by default (without this function), ICU will
0211   *  directly access system functions for mutex operations
0212   *  This function can only be used when ICU is in an initial, unused state, before
0213   *  u_init() has been called.
0214   *  @param context This pointer value will be saved, and then (later) passed as
0215   *                 a parameter to the user-supplied mutex functions each time they
0216   *                 are called. 
0217   *  @param init    Pointer to a mutex initialization function.  Must be non-null.
0218   *  @param destroy Pointer to the mutex destroy function.  Must be non-null.
0219   *  @param lock    pointer to the mutex lock function.  Must be non-null.
0220   *  @param unlock  Pointer to the mutex unlock function.  Must be non-null.
0221   *  @param status  Receives error values.
0222   *  @deprecated ICU 52. This function is no longer supported.
0223   *  @system
0224   */  
0225 U_DEPRECATED void U_EXPORT2 
0226 u_setMutexFunctions(const void *context, UMtxInitFn *init, UMtxFn *destroy, UMtxFn *lock, UMtxFn *unlock,
0227                     UErrorCode *status);
0228 
0229 
0230 /**
0231   *  Pointer type for a user supplied atomic increment or decrement function.
0232   *  @param context user supplied value, obtained from u_setAtomicIncDecFunctions().
0233   *  @param p   Pointer to a 32 bit int to be incremented or decremented
0234   *  @return    The value of the variable after the inc or dec operation.
0235   *  @deprecated ICU 52. This function is no longer supported.
0236   *  @system
0237   */
0238 typedef int32_t U_CALLCONV UMtxAtomicFn(const void *context, int32_t *p);
0239 
0240 /**
0241  *  Set the functions that ICU will use for atomic increment and decrement of int32_t values.
0242  *  Use of this function is optional; by default (without this function), ICU will
0243  *  use its own internal implementation of atomic increment/decrement.
0244  *  This function can only be used when ICU is in an initial, unused state, before
0245  *  u_init() has been called.
0246  *  @param context This pointer value will be saved, and then (later) passed as
0247  *                 a parameter to the increment and decrement functions each time they
0248  *                 are called.  This function can only be called 
0249  *  @param inc     Pointer to a function to do an atomic increment operation.  Must be non-null.
0250  *  @param dec     Pointer to a function to do an atomic decrement operation.  Must be non-null.
0251  *  @param status  Receives error values.
0252  *  @deprecated ICU 52. This function is no longer supported.
0253  *  @system
0254  */  
0255 U_DEPRECATED void U_EXPORT2 
0256 u_setAtomicIncDecFunctions(const void *context, UMtxAtomicFn *inc, UMtxAtomicFn *dec,
0257                     UErrorCode *status);
0258 
0259 #endif  /* U_HIDE_DEPRECATED_API */
0260 #endif  /* U_HIDE_SYSTEM_API */
0261 
0262 #endif