1 // © 2016 and later: Unicode, Inc. and others.
2 // License & terms of use: http://www.unicode.org/copyright.html
3 /*
4 **********************************************************************
5 *   Copyright (C) 1997-2015, International Business Machines
6 *   Corporation and others.  All Rights Reserved.
7 **********************************************************************
8 *
9 * File UMUTEX.H
10 *
11 * Modification History:
12 *
13 *   Date        Name        Description
14 *   04/02/97  aliu        Creation.
15 *   04/07/99  srl         rewrite - C interface, multiple mutices
16 *   05/13/99  stephen     Changed to umutex (from cmutex)
17 ******************************************************************************
18 */
19 
20 #ifndef UMUTEX_H
21 #define UMUTEX_H
22 
23 #include <atomic>
24 #include <condition_variable>
25 #include <mutex>
26 #include <type_traits>
27 
28 #include "unicode/utypes.h"
29 #include "unicode/uclean.h"
30 #include "unicode/uobject.h"
31 
32 #include "putilimp.h"
33 
34 #if defined(U_USER_ATOMICS_H) || defined(U_USER_MUTEX_H)
35 // Support for including an alternate implementation of atomic & mutex operations has been withdrawn.
36 // See issue ICU-20185.
37 #error U_USER_ATOMICS and U_USER_MUTEX_H are not supported
38 #endif
39 
40 // Export an explicit template instantiation of std::atomic<int32_t>.
41 // When building DLLs for Windows this is required as it is used as a data member of the exported SharedObject class.
42 // See digitlst.h, pluralaffix.h, datefmt.h, and others for similar examples.
43 //
44 // Similar story for std::atomic<std::mutex *>, and the exported UMutex class.
45 #if U_PF_WINDOWS <= U_PLATFORM && U_PLATFORM <= U_PF_CYGWIN && !defined(U_IN_DOXYGEN)
46 #if defined(__clang__) || defined(_MSC_VER)
47   #if defined(__clang__)
48     // Suppress the warning that the explicit instantiation after explicit specialization has no effect.
49     #pragma clang diagnostic push
50     #pragma clang diagnostic ignored "-Winstantiation-after-specialization"
51   #endif
52 template struct U_COMMON_API std::atomic<int32_t>;
53 template struct U_COMMON_API std::atomic<std::mutex *>;
54   #if defined(__clang__)
55     #pragma clang diagnostic pop
56   #endif
57 #elif defined(__GNUC__)
58 // For GCC this class is already exported/visible, so no need for U_COMMON_API.
59 template struct std::atomic<int32_t>;
60 template struct std::atomic<std::mutex *>;
61 #endif
62 #endif
63 
64 
65 U_NAMESPACE_BEGIN
66 
67 /****************************************************************************
68  *
69  *   Low Level Atomic Operations, ICU wrappers for.
70  *
71  ****************************************************************************/
72 
73 typedef std::atomic<int32_t> u_atomic_int32_t;
74 #define ATOMIC_INT32_T_INITIALIZER(val) ATOMIC_VAR_INIT(val)
75 
76 inline int32_t umtx_loadAcquire(u_atomic_int32_t &var) {
77     return var.load(std::memory_order_acquire);
78 }
79 
80 inline void umtx_storeRelease(u_atomic_int32_t &var, int32_t val) {
81     var.store(val, std::memory_order_release);
82 }
83 
84 inline int32_t umtx_atomic_inc(u_atomic_int32_t *var) {
85     return var->fetch_add(1) + 1;
86 }
87 
88 inline int32_t umtx_atomic_dec(u_atomic_int32_t *var) {
89     return var->fetch_sub(1) - 1;
90 }
91 
92 
93 /*************************************************************************************************
94  *
95  *  UInitOnce Definitions.
96  *
97  *************************************************************************************************/
98 
99 struct UInitOnce {
100     u_atomic_int32_t   fState;
101     UErrorCode       fErrCode;
102     void reset() {fState = 0;}
103     UBool isReset() {return umtx_loadAcquire(fState) == 0;}
104 // Note: isReset() is used by service registration code.
105 //                 Thread safety of this usage needs review.
106 };
107 
108 #define U_INITONCE_INITIALIZER {ATOMIC_INT32_T_INITIALIZER(0), U_ZERO_ERROR}
109 
110 
111 U_COMMON_API UBool U_EXPORT2 umtx_initImplPreInit(UInitOnce &);
112 U_COMMON_API void  U_EXPORT2 umtx_initImplPostInit(UInitOnce &);
113 
114 template<class T> void umtx_initOnce(UInitOnce &uio, T *obj, void (U_CALLCONV T::*fp)()) {
115     if (umtx_loadAcquire(uio.fState) == 2) {
116         return;
117     }
118     if (umtx_initImplPreInit(uio)) {
119         (obj->*fp)();
120         umtx_initImplPostInit(uio);
121     }
122 }
123 
124 
125 // umtx_initOnce variant for plain functions, or static class functions.
126 //               No context parameter.
127 inline void umtx_initOnce(UInitOnce &uio, void (U_CALLCONV *fp)()) {
128     if (umtx_loadAcquire(uio.fState) == 2) {
129         return;
130     }
131     if (umtx_initImplPreInit(uio)) {
132         (*fp)();
133         umtx_initImplPostInit(uio);
134     }
135 }
136 
137 // umtx_initOnce variant for plain functions, or static class functions.
138 //               With ErrorCode, No context parameter.
139 inline void umtx_initOnce(UInitOnce &uio, void (U_CALLCONV *fp)(UErrorCode &), UErrorCode &errCode) {
140     if (U_FAILURE(errCode)) {
141         return;
142     }
143     if (umtx_loadAcquire(uio.fState) != 2 && umtx_initImplPreInit(uio)) {
144         // We run the initialization.
145         (*fp)(errCode);
146         uio.fErrCode = errCode;
147         umtx_initImplPostInit(uio);
148     } else {
149         // Someone else already ran the initialization.
150         if (U_FAILURE(uio.fErrCode)) {
151             errCode = uio.fErrCode;
152         }
153     }
154 }
155 
156 // umtx_initOnce variant for plain functions, or static class functions,
157 //               with a context parameter.
158 template<class T> void umtx_initOnce(UInitOnce &uio, void (U_CALLCONV *fp)(T), T context) {
159     if (umtx_loadAcquire(uio.fState) == 2) {
160         return;
161     }
162     if (umtx_initImplPreInit(uio)) {
163         (*fp)(context);
164         umtx_initImplPostInit(uio);
165     }
166 }
167 
168 // umtx_initOnce variant for plain functions, or static class functions,
169 //               with a context parameter and an error code.
170 template<class T> void umtx_initOnce(UInitOnce &uio, void (U_CALLCONV *fp)(T, UErrorCode &), T context, UErrorCode &errCode) {
171     if (U_FAILURE(errCode)) {
172         return;
173     }
174     if (umtx_loadAcquire(uio.fState) != 2 && umtx_initImplPreInit(uio)) {
175         // We run the initialization.
176         (*fp)(context, errCode);
177         uio.fErrCode = errCode;
178         umtx_initImplPostInit(uio);
179     } else {
180         // Someone else already ran the initialization.
181         if (U_FAILURE(uio.fErrCode)) {
182             errCode = uio.fErrCode;
183         }
184     }
185 }
186 
187 // UMutex should be constexpr-constructible, so that no initialization code
188 // is run during startup.
189 // This works on all C++ libraries except MS VS before VS2019.
190 #if (defined(_CPPLIB_VER) && !defined(_MSVC_STL_VERSION)) || \
191     (defined(_MSVC_STL_VERSION) && _MSVC_STL_VERSION < 142)
192     // (VS std lib older than VS2017) || (VS std lib version < VS2019)
193 #   define UMUTEX_CONSTEXPR
194 #else
195 #   define UMUTEX_CONSTEXPR constexpr
196 #endif
197 
198 /**
199  * UMutex - ICU Mutex class.
200  *
201  * This is the preferred Mutex class for use within ICU implementation code.
202  * It is a thin wrapper over C++ std::mutex, with these additions:
203  *    - Static instances are safe, not triggering static construction or destruction,
204  *      and the associated order of construction or destruction issues.
205  *    - Plumbed into u_cleanup() for destructing the underlying std::mutex,
206  *      which frees any OS level resources they may be holding.
207  *
208  * Limitations:
209  *    - Static or global instances only. Cannot be heap allocated. Cannot appear as a
210  *      member of another class.
211  *    - No condition variables or other advanced features. If needed, you will need to use
212  *      std::mutex and std::condition_variable directly. For an example, see unifiedcache.cpp
213  *
214  * Typical Usage:
215  *    static UMutex myMutex;
216  *
217  *    {
218  *       Mutex lock(myMutex);
219  *       ...    // Do stuff that is protected by myMutex;
220  *    }         // myMutex is released when lock goes out of scope.
221  */
222 
223 class U_COMMON_API UMutex {
224 public:
225     UMUTEX_CONSTEXPR UMutex() {}
226     ~UMutex() = default;
227 
228     UMutex(const UMutex &other) = delete;
229     UMutex &operator =(const UMutex &other) = delete;
230     void *operator new(size_t) = delete;
231 
232     // requirements for C++ BasicLockable, allows UMutex to work with std::lock_guard
233     void lock() {
234         std::mutex *m = fMutex.load(std::memory_order_acquire);
235         if (m == nullptr) { m = getMutex(); }
236         m->lock();
237     }
238     void unlock() { fMutex.load(std::memory_order_relaxed)->unlock(); }
239 
240     static void cleanup();
241 
242 private:
243     alignas(std::mutex) char fStorage[sizeof(std::mutex)] {};
244     std::atomic<std::mutex *> fMutex { nullptr };
245 
246     /** All initialized UMutexes are kept in a linked list, so that they can be found,
247      * and the underlying std::mutex destructed, by u_cleanup().
248      */
249     UMutex *fListLink { nullptr };
250     static UMutex *gListHead;
251 
252     /** Out-of-line function to lazily initialize a UMutex on first use.
253      * Initial fast check is inline, in lock().  The returned value may never
254      * be nullptr.
255      */
256     std::mutex *getMutex();
257 };
258 
259 
260 /* Lock a mutex.
261  * @param mutex The given mutex to be locked.  Pass NULL to specify
262  *              the global ICU mutex.  Recursive locks are an error
263  *              and may cause a deadlock on some platforms.
264  */
265 U_CAPI void U_EXPORT2 umtx_lock(UMutex* mutex);
266 
267 /* Unlock a mutex.
268  * @param mutex The given mutex to be unlocked.  Pass NULL to specify
269  *              the global ICU mutex.
270  */
271 U_CAPI void U_EXPORT2 umtx_unlock (UMutex* mutex);
272 
273 
274 U_NAMESPACE_END
275 
276 #endif /* UMUTEX_H */
277 /*eof*/
278