ICU-3.13.tar.gz

[apple/icu.git] / icuSources / common / unicode / uclean.h

/*
******************************************************************************
*                                                                            *
* Copyright (C) 2001-2003, International Business Machines                   *
*                Corporation and others. All Rights Reserved.                *
*                                                                            *
******************************************************************************
*   file name:  uclean.h
*   encoding:   US-ASCII
*   tab size:   8 (not used)
*   indentation:4
*
*   created on: 2001July05
*   created by: George Rhoten
*/

#ifndef __UCLEAN_H__
#define __UCLEAN_H__

#include "unicode/utypes.h"

/**
 *  Initialize ICU.  This function loads and initializes data items
 *  that are required internally by various ICU functions.  Use of this explicit
 *  initialization is required in multi-threaded applications; in 
 *  single threaded apps, use is optional, but incurs little additional
 *  cost, and is thus recommended.
 *  <p>
 *  In multi-threaded applications, u_init() should be called  in the
 *  main thread before starting additional threads, or, alternatively
 *  it can be called in each individual thread once, before other ICU
 *  functions are called in that thread.  In this second scenario, the
 *  application must guarantee that the first call to u_init() happen
 *  without contention, in a single thread only.
 *  <p>
 *  Extra, repeated, or otherwise unneeded calls to u_init() do no harm,
 *  other than taking a small amount of time.
 *
 * @param pErrorCode An ICU UErrorCode parameter. It must not be <code>NULL</code>.
 *    An Error will be returned if some required part of ICU data can not
 *    be loaded or initialized.
 *    The function returns immediately if the input error code indicates a
 *    failure, as usual.
 *
 * @draft ICU 2.6
 */  
U_CAPI void U_EXPORT2 
u_init(UErrorCode *status);

/**
 * Clean up the system resources, such as allocated memory or open files,
 * used in all ICU libraries. This will free/delete all memory owned by the
 * ICU libraries, and return them to their original load state. All open ICU
 * items (collators, resource bundles, converters, etc.) must be closed before
 * calling this function, otherwise ICU may not free its allocated memory
 * (e.g. close your converters and resource bundles before calling this
 * function). Generally, this function should be called once just before
 * an application exits. For applications that dynamically load and unload
 * the ICU libraries (relatively uncommon), u_cleanup() should be called
 * just before the library unload.
 * <p>
 * u_cleanup() is not thread safe.  All other threads should stop using ICU
 * before calling this function.
 * <p>
 * Any open ICU items will be left in an undefined state by u_cleanup(),
 * and any subsequent attempt to use such an item will give unpredictable
 * results.
 * <p>
 * After calling u_cleanup(), an application may continue to use ICU by
 * calling u_init().  An application must invoke u_init() first from one single
 * thread before allowing other threads call u_init().  All threads existing
 * at the time of the first thread's call to u_init() must also call
 * u_init() themselves before continuing with other ICU operations.  
 * <p>
 * The use of u_cleanup() just before an application terminates is optional,
 * but it should be called only once for performance reasons. The primary
 * benefit is to eliminate reports of memory or resource leaks originating
 * in ICU code from the results generated by heap analysis tools.
 * <p>
 * <strong>Use this function with great care!</strong>
 * </p>
 *
 * @stable ICU 2.0
 * @system
 */
U_CAPI void U_EXPORT2 
u_cleanup(void);

#endif