1 // Copyright (C) 2016 and later: Unicode, Inc. and others.
2 // License & terms of use: http://www.unicode.org/copyright.html
4 ******************************************************************************
5 * Copyright (C) 2015-2016, International Business Machines
6 * Corporation and others. All Rights Reserved.
7 ******************************************************************************
11 #ifndef __SHAREDOBJECT_H__
12 #define __SHAREDOBJECT_H__
15 #include "unicode/uobject.h"
21 * Base class for unified cache exposing enough methods to SharedObject
22 * instances to allow their addRef() and removeRef() methods to
23 * update cache metrics. No other part of ICU, except for SharedObject,
24 * should directly call the methods of this base class.
26 class U_COMMON_API UnifiedCacheBase : public UObject {
28 UnifiedCacheBase() { }
31 * Called by addRefWhileHoldingCacheLock() when the hard reference count
32 * of its instance goes from 0 to 1.
34 virtual void incrementItemsInUse() const = 0;
37 * Called by removeRef() when the hard reference count of its instance
40 virtual void decrementItemsInUseWithLockingAndEviction() const = 0;
43 * Called by removeRefWhileHoldingCacheLock() when the hard reference
44 * count of its instance drops from 1 to 0.
46 virtual void decrementItemsInUse() const = 0;
47 virtual ~UnifiedCacheBase();
49 UnifiedCacheBase(const UnifiedCacheBase &);
50 UnifiedCacheBase &operator=(const UnifiedCacheBase &);
54 * Base class for shared, reference-counted, auto-deleted objects.
55 * Subclasses can be immutable.
56 * If they are mutable, then they must implement their copy constructor
57 * so that copyOnWrite() works.
59 * Either stack-allocate, use LocalPointer, or use addRef()/removeRef().
60 * Sharing requires reference-counting.
62 class U_COMMON_API SharedObject : public UObject {
64 /** Initializes totalRefCount, softRefCount to 0. */
71 /** Initializes totalRefCount, softRefCount to 0. */
72 SharedObject(const SharedObject &other) :
79 virtual ~SharedObject();
82 * Increments the number of references to this object. Thread-safe.
84 void addRef() const { addRef(FALSE); }
87 * Increments the number of references to this object.
88 * Must be called only from within the internals of UnifiedCache and
89 * only while the cache global mutex is held.
91 void addRefWhileHoldingCacheLock() const { addRef(TRUE); }
94 * Increments the number of soft references to this object.
95 * Must be called only from within the internals of UnifiedCache and
96 * only while the cache global mutex is held.
98 void addSoftRef() const;
101 * Decrements the number of references to this object. Thread-safe.
103 void removeRef() const { removeRef(FALSE); }
106 * Decrements the number of references to this object.
107 * Must be called only from within the internals of UnifiedCache and
108 * only while the cache global mutex is held.
110 void removeRefWhileHoldingCacheLock() const { removeRef(TRUE); }
113 * Decrements the number of soft references to this object.
114 * Must be called only from within the internals of UnifiedCache and
115 * only while the cache global mutex is held.
117 void removeSoftRef() const;
120 * Returns the reference counter including soft references.
121 * Uses a memory barrier.
123 int32_t getRefCount() const;
126 * Returns the count of soft references only.
127 * Must be called only from within the internals of UnifiedCache and
128 * only while the cache global mutex is held.
130 int32_t getSoftRefCount() const { return softRefCount; }
133 * Returns the count of hard references only. Uses a memory barrier.
134 * Used for testing the cache. Regular clients won't need this.
136 int32_t getHardRefCount() const;
139 * If noHardReferences() == TRUE then this object has no hard references.
140 * Must be called only from within the internals of UnifiedCache.
142 inline UBool noHardReferences() const { return getHardRefCount() == 0; }
145 * If hasHardReferences() == TRUE then this object has hard references.
146 * Must be called only from within the internals of UnifiedCache.
148 inline UBool hasHardReferences() const { return getHardRefCount() != 0; }
151 * If noSoftReferences() == TRUE then this object has no soft references.
152 * Must be called only from within the internals of UnifiedCache and
153 * only while the cache global mutex is held.
155 UBool noSoftReferences() const { return (softRefCount == 0); }
158 * Deletes this object if it has no references or soft references.
160 void deleteIfZeroRefCount() const;
163 * @internal For UnifedCache use only to register this object with itself.
164 * Must be called before this object is exposed to multiple threads.
166 void registerWithCache(const UnifiedCacheBase *ptr) const {
171 * Returns a writable version of ptr.
172 * If there is exactly one owner, then ptr itself is returned as a
174 * If there are multiple owners, then ptr is replaced with a
175 * copy-constructed clone,
176 * and that is returned.
177 * Returns NULL if cloning failed.
179 * T must be a subclass of SharedObject.
182 static T *copyOnWrite(const T *&ptr) {
184 if(p->getRefCount() <= 1) { return const_cast<T *>(p); }
186 if(p2 == NULL) { return NULL; }
194 * Makes dest an owner of the object pointed to by src while adjusting
195 * reference counts and deleting the previous object dest pointed to
196 * if necessary. Before this call is made, dest must either be NULL or
197 * be included in the reference count of the object it points to.
199 * T must be a subclass of SharedObject.
202 static void copyPtr(const T *src, const T *&dest) {
204 if(dest != NULL) { dest->removeRef(); }
206 if(src != NULL) { src->addRef(); }
211 * Equivalent to copyPtr(NULL, dest).
214 static void clearPtr(const T *&ptr) {
222 mutable u_atomic_int32_t totalRefCount;
224 // Any thread modifying softRefCount must hold the global cache mutex
225 mutable int32_t softRefCount;
227 mutable u_atomic_int32_t hardRefCount;
228 mutable const UnifiedCacheBase *cachePtr;
229 void addRef(UBool withCacheLock) const;
230 void removeRef(UBool withCacheLock) const;