/*
**********************************************************************
-* Copyright (C) 1997-2001, International Business Machines
+* Copyright (C) 1997-2008, International Business Machines
* Corporation and others. All Rights Reserved.
**********************************************************************
*
#define UMUTEX_H
#include "unicode/utypes.h"
+#include "unicode/uclean.h"
-/**
- * Mutex data type.
- * @internal
- */
-typedef void *UMTX;
/* APP_NO_THREADS is an old symbol. We'll honour it if present. */
#ifdef APP_NO_THREADS
# define ICU_USE_THREADS 0
#endif
-/* Default: use threads. */
+/* ICU_USE_THREADS
+ *
+ * Allows thread support (use of mutexes) to be compiled out of ICU.
+ * Default: use threads.
+ * Even with thread support compiled out, applications may override the
+ * (empty) mutex implementation with the u_setMutexFunctions() functions.
+ */
#ifndef ICU_USE_THREADS
# define ICU_USE_THREADS 1
#endif
+/**
+ * By default assume that we are on a machine with a weak memory model,
+ * and the double check lock won't work reliably.
+ */
+#if !defined(UMTX_STRONG_MEMORY_MODEL)
+#define UMTX_STRONG_MEMORY_MODEL 0
+#endif
+
+/**
+ * \def UMTX_CHECK
+ * Encapsulates a safe check of an expression
+ * for use with double-checked lazy inititialization.
+ * On CPUs with weak memory models, this must use memory fence instructions
+ * or mutexes.
+ * The expression must involve only a _single_ variable, typically
+ * a possibly null pointer or a boolean that indicates whether some service
+ * is initialized or not.
+ * The setting of the variable involved in the test must be the last step of
+ * the initialization process.
+ *
+ *
+ * @internal
+ */
+#if UMTX_STRONG_MEMORY_MODEL
+
+#define UMTX_CHECK(pMutex, expression, result) \
+ (result)=(expression)
+
+#else
+
+#define UMTX_CHECK(pMutex, expression, result) \
+ umtx_lock(pMutex); \
+ (result)=(expression); \
+ umtx_unlock(pMutex)
+
+#endif
+
/*
- * Code within this library which accesses protected data should
- * instantiate a Mutex object while doing so. Notice that there is
- * only one coarse-grained lock which applies to this entire library,
- * so keep locking short and sweet.
+ * Code within ICU that accesses shared static or global data should
+ * instantiate a Mutex object while doing so. The unnamed global mutex
+ * is used throughout ICU, so keep locking short and sweet.
*
* For example:
*
* void Function(int arg1, int arg2)
* {
- * static Object* foo; // Shared read-write object
- * Mutex mutex;
+ * static Object* foo; // Shared read-write object
+ * umtx_lock(NULL); // Lock the ICU global mutex
* foo->Method();
- * // When 'mutex' goes out of scope and gets destroyed here
- * // the lock is released
+ * umtx_unlock(NULL);
* }
*
- * Note: Do NOT use the form 'Mutex mutex();' as that merely
- * forward-declares a function returning a Mutex. This is a common
- * mistake which silently slips through the compiler!! */
-
+ * an alternative C++ mutex API is defined in the file common/mutex.h
+ */
-/* Lock a mutex. Pass in NULL if you want the (ick) Single Global
- Mutex.
- * @param mutex The given mutex to be locked
+/* Lock a mutex.
+ * @param mutex The given mutex to be locked. Pass NULL to specify
+ * the global ICU mutex. Recursive locks are an error
+ * and may cause a deadlock on some platforms.
*/
U_CAPI void U_EXPORT2 umtx_lock ( UMTX* mutex );
/* Unlock a mutex. Pass in NULL if you want the single global
mutex.
- * @param mutex The given mutex to be unlocked
+ * @param mutex The given mutex to be unlocked. Pass NULL to specify
+ * the global ICU mutex.
*/
U_CAPI void U_EXPORT2 umtx_unlock ( UMTX* mutex );
/* Initialize a mutex. Use it this way:
umtx_init( &aMutex );
- * ICU Mutexes, aside from the global mutex, must be explicitly initialized
- * before use.
+ * ICU Mutexes do not need explicit initialization before use. Use of this
+ * function is not necessary.
+ * Initialization of an already initialized mutex has no effect, and is safe to do.
+ * Initialization of mutexes is thread safe. Two threads can concurrently
+ * initialize the same mutex without causing problems.
* @param mutex The given mutex to be initialized
*/
U_CAPI void U_EXPORT2 umtx_init ( UMTX* mutex );
/* Destroy a mutex. This will free the resources of a mutex.
- Use it this way:
- umtx_destroy( &aMutex );
- * @param mutex The given mutex to be destroyed
+ * Use it this way:
+ * umtx_destroy( &aMutex );
+ * Destroying an already destroyed mutex has no effect, and causes no problems.
+ * This function is not thread safe. Two threads must not attempt to concurrently
+ * destroy the same mutex.
+ * @param mutex The given mutex to be destroyed.
*/
U_CAPI void U_EXPORT2 umtx_destroy( UMTX *mutex );
-/* Is a mutex initialized?
- Use it this way:
- umtx_isInitialized( &aMutex );
- This function is not normally needed. It is more efficient to
- unconditionally call umtx_init(&aMutex) than it is to check first.
- * @param mutex The given mutex to be tested
-*/
-U_CAPI UBool U_EXPORT2 umtx_isInitialized( UMTX *mutex );
+
/*
* Atomic Increment and Decrement of an int32_t value.
projects / apple / icu.git / blobdiff