1--- 2layout: default 3title: Synchronization 4nav_order: 2 5parent: Misc 6--- 7<!-- 8© 2020 and later: Unicode, Inc. and others. 9License & terms of use: http://www.unicode.org/copyright.html 10--> 11 12# Synchronization Issues 13{: .no_toc } 14 15## Contents 16{: .no_toc .text-delta } 17 181. TOC 19{:toc} 20 21--- 22 23## Overview 24 25ICU is designed for use in multi-threaded environments. Guidelines for 26developers using ICU are in the [ICU Design](../../design.md) section of the 27user guide. 28 29Within the ICU implementation, access to shared or global data sometimes must be 30protected in order to provide the threading model promised by the ICU design. 31The information on this page is intended for developers of ICU library code 32itself. 33 34ICU4J uses normal JDK synchronization services. 35 36ICU4C faces a more difficult problem, as there is no standard, fully portable 37set of C or C++ synchronization primitives. Internally, ICU4C provides a small 38set of synchronization operations, and requires that all synchronization needed 39within the ICU library code be implemented using them. 40 41The ICU4C synchronization primitives are for internal use only; they are not 42exported as API to normal users of ICU. 43 44ICU provides implementations of its synchronization functions for Windows, POSIX 45and C++11 platforms, and provides a build-time interface to allow [custom 46implementations](custom.md) for other platforms. 47 48## ICU4C Synchronization Primitives 49 50The functions and types listed below are intended for use throughout the ICU 51library code, where ever synchronization is required. They are defined in the 52internal header 53[umutex.h](https://github.com/unicode-org/icu/blob/master/icu4c/source/common/umutex.h). 54 55All synchronization within ICU4C implementation code must use these, and avoid 56direct use of functions provided by a particular operating system or compiler. 57 58For examples of use, search the ICU library code. 59 60**Low Level Atomics** 61 62| Type/Function | Description | 63|------------------------------------------|-----------------------------------------------------------------| 64| `typedef u_atomic_int32_t` | A 32 bit integer type for use with low level atomic operations. | 65| `umtx_atomic_inc(u_atomic_int32_t &var)` | | 66| `umtx_atomic_dec(u_atomic_int32_t &var)` | | 67 68**Mutexes** 69 70| Type/Function | Description | 71|------------------------------|-----------------------------------------------------------------------| 72| `struct UMutex` | An ICU mutex. All instances must be `static`. | 73| `U_MUTEX_INITIALIZER` | A C style initializer for a `UMutex`. | 74| `umtx_lock(UMutex *mutex)` | Lock a mutex. | 75| `umtx_unlock(UMutex* mutex)` | Unlock a mutex. | 76| `class Mutex` | C++ Mutex wrapper with automatic lock & unlock. See header `mutex.h.` | 77 78**One Time Initialization** 79 80| Type/Function | Description | 81|---------------------------------|-----------------------------------------------------------------------------------------| 82| `struct UInitOnce` | Provides an efficient facility for one-time initialization of static or global objects. | 83| `umtx_initOnce(UInitOnce, ...)` | A family of initialization functions. | 84 85All of these functions are for internal ICU implementation use only. They are 86not exported, and not intended for external use. 87