1 /*

     2 **********************************************************************

     3 *   Copyright (C) 1997-2005, International Business Machines

     4 *   Corporation and others.  All Rights Reserved.

     5 **********************************************************************

     6 *

     7 * File UMUTEX.H

     8 *

     9 * Modification History:

    10 *

    11 *   Date        Name        Description

    12 *   04/02/97  aliu        Creation.

    13 *   04/07/99  srl         rewrite - C interface, multiple mutices

    14 *   05/13/99  stephen     Changed to umutex (from cmutex)

    15 ******************************************************************************

    16 */

    17 

    18 #ifndef UMUTEX_H

    19 #define UMUTEX_H

    20 

    21 #include "unicode/utypes.h"

    22 #include "unicode/uclean.h"  

    23 

    24 

    25 /* APP_NO_THREADS is an old symbol. We'll honour it if present. */

    26 #ifdef APP_NO_THREADS

    27 # define ICU_USE_THREADS 0

    28 #endif

    29 

    30 /* ICU_USE_THREADS

    31  *

    32  *   Allows thread support (use of mutexes) to be compiled out of ICU.

    33  *   Default: use threads.

    34  *   Even with thread support compiled out, applications may override the

    35  *   (empty) mutex implementation with the u_setMutexFunctions() functions.

    36  */ 

    37 #ifndef ICU_USE_THREADS

    38 # define ICU_USE_THREADS 1

    39 #endif

    40 

    41 /**

    42  * By default assume that we are on a machine with a weak memory model,

    43  * and the double check lock won't work reliably.

    44  */

    45 #if !defined(UMTX_STRONG_MEMORY_MODEL)

    46 #define UMTX_STRONG_MEMORY_MODEL 0

    47 #endif

    48 

    49 /**

    50  * \def UMTX_CHECK

    51  * Encapsulates a safe check for an expression (usually a condition)

    52  * for lazy variable inititialization.

    53  * On CPUs with weak memory models, this must use memory fence instructions

    54  * or mutexes.

    55  * @internal

    56  */

    57 #if UMTX_STRONG_MEMORY_MODEL

    58 

    59 #define UMTX_CHECK(pMutex, expression, result) \

    60     (result)=(expression);

    61 

    62 #else

    63 

    64 #define UMTX_CHECK(pMutex, expression, result) \

    65     umtx_lock(pMutex); \

    66     (result)=(expression); \

    67     umtx_unlock(pMutex);

    68 

    69 #endif

    70 

    71 /*

    72  * Code within ICU that accesses shared static or global data should

    73  * instantiate a Mutex object while doing so.  The unnamed global mutex

    74  * is used throughout ICU, so keep locking short and sweet.

    75  *

    76  * For example:

    77  *

    78  * void Function(int arg1, int arg2)

    79  * {

    80  *   static Object* foo;     // Shared read-write object

    81  *   umtx_lock(NULL);        // Lock the ICU global mutex

    82  *   foo->Method();

    83  *   umtx_unlock(NULL);

    84  * }

    85  *

    86  * an alternative C++ mutex API is defined in the file common/mutex.h

    87  */

    88 

    89 /* Lock a mutex. 

    90  * @param mutex The given mutex to be locked.  Pass NULL to specify

    91  *              the global ICU mutex.  Recursive locks are an error

    92  *              and may cause a deadlock on some platforms.

    93  */

    94 U_CAPI void U_EXPORT2 umtx_lock   ( UMTX* mutex ); 

    95 

    96 /* Unlock a mutex. Pass in NULL if you want the single global

    97    mutex. 

    98  * @param mutex The given mutex to be unlocked.  Pass NULL to specify

    99  *              the global ICU mutex.

   100  */

   101 U_CAPI void U_EXPORT2 umtx_unlock ( UMTX* mutex );

   102 

   103 /* Initialize a mutex. Use it this way:

   104    umtx_init( &aMutex ); 

   105  * ICU Mutexes do not need explicit initialization before use.  Use of this

   106  *   function is not necessary.

   107  * Initialization of an already initialized mutex has no effect, and is safe to do.

   108  * Initialization of mutexes is thread safe.  Two threads can concurrently 

   109  *   initialize the same mutex without causing problems.

   110  * @param mutex The given mutex to be initialized

   111  */

   112 U_CAPI void U_EXPORT2 umtx_init   ( UMTX* mutex );

   113 

   114 /* Destroy a mutex. This will free the resources of a mutex.

   115  * Use it this way:

   116  *   umtx_destroy( &aMutex ); 

   117  * Destroying an already destroyed mutex has no effect, and causes no problems.

   118  * This function is not thread safe.  Two threads must not attempt to concurrently

   119  *   destroy the same mutex.

   120  * @param mutex The given mutex to be destroyed.

   121  */

   122 U_CAPI void U_EXPORT2 umtx_destroy( UMTX *mutex );

   123 

   124 

   125 

   126 /*

   127  * Atomic Increment and Decrement of an int32_t value.

   128  *

   129  * Return Values:

   130  *   If the result of the operation is zero, the return zero.

   131  *   If the result of the operation is not zero, the sign of returned value

   132  *      is the same as the sign of the result, but the returned value itself may

   133  *      be different from the result of the operation.

   134  */

   135 U_CAPI int32_t U_EXPORT2 umtx_atomic_inc(int32_t *);

   136 U_CAPI int32_t U_EXPORT2 umtx_atomic_dec(int32_t *);

   137 

   138 

   139 #endif /*_CMUTEX*/

   140 /*eof*/

   141 

   142 

   143