Home | History | Annotate | Download | only in common 
      1 // Copyright (C) 2016 and later: Unicode, Inc. and others.
      2 // License & terms of use: http://www.unicode.org/copyright.html
      3 /*
      4 ******************************************************************************
      5 * Copyright (C) 2015-2016, International Business Machines
      6 * Corporation and others.  All Rights Reserved.
      7 ******************************************************************************
      8 * sharedobject.h
      9 */
     10 
     11 #ifndef __SHAREDOBJECT_H__
     12 #define __SHAREDOBJECT_H__
     13 
     14 
     15 #include "unicode/uobject.h"
     16 #include "umutex.h"
     17 
     18 U_NAMESPACE_BEGIN
     19 
     20 /**
     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.
     25  */
     26 class U_COMMON_API UnifiedCacheBase : public UObject {
     27 public:
     28     UnifiedCacheBase() { }
     29 
     30     /**
     31      * Called by addRefWhileHoldingCacheLock() when the hard reference count
     32      * of its instance goes from 0 to 1.
     33      */
     34     virtual void incrementItemsInUse() const = 0;
     35 
     36     /**
     37      * Called by removeRef() when the hard reference count of its instance
     38      * drops from 1 to 0.
     39      */
     40     virtual void decrementItemsInUseWithLockingAndEviction() const = 0;
     41 
     42     /**
     43      * Called by removeRefWhileHoldingCacheLock() when the hard reference
     44      * count of its instance drops from 1 to 0.
     45      */
     46     virtual void decrementItemsInUse() const = 0;
     47     virtual ~UnifiedCacheBase();
     48 private:
     49     UnifiedCacheBase(const UnifiedCacheBase &);
     50     UnifiedCacheBase &operator=(const UnifiedCacheBase &);
     51 };
     52 
     53 /**
     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.
     58  *
     59  * Either stack-allocate, use LocalPointer, or use addRef()/removeRef().
     60  * Sharing requires reference-counting.
     61  */
     62 class U_COMMON_API SharedObject : public UObject {
     63 public:
     64     /** Initializes totalRefCount, softRefCount to 0. */
     65     SharedObject() :
     66             totalRefCount(0),
     67             softRefCount(0),
     68             hardRefCount(0),
     69             cachePtr(NULL) {}
     70 
     71     /** Initializes totalRefCount, softRefCount to 0. */
     72     SharedObject(const SharedObject &other) :
     73             UObject(other),
     74             totalRefCount(0),
     75             softRefCount(0),
     76             hardRefCount(0),
     77             cachePtr(NULL) {}
     78 
     79     virtual ~SharedObject();
     80 
     81     /**
     82      * Increments the number of references to this object. Thread-safe.
     83      */
     84     void addRef() const { addRef(FALSE); }
     85 
     86     /**
     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.
     90      */
     91     void addRefWhileHoldingCacheLock() const { addRef(TRUE); }
     92 
     93     /**
     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.
     97      */
     98     void addSoftRef() const;
     99 
    100     /**
    101      * Decrements the number of references to this object. Thread-safe.
    102      */
    103     void removeRef() const { removeRef(FALSE); }
    104 
    105     /**
    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.
    109      */
    110     void removeRefWhileHoldingCacheLock() const { removeRef(TRUE); }
    111 
    112     /**
    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.
    116      */
    117     void removeSoftRef() const;
    118 
    119     /**
    120      * Returns the reference counter including soft references.
    121      * Uses a memory barrier.
    122      */
    123     int32_t getRefCount() const;
    124 
    125     /**
    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.
    129      */
    130     int32_t getSoftRefCount() const { return softRefCount; }
    131 
    132     /**
    133      * Returns the count of hard references only. Uses a memory barrier.
    134      * Used for testing the cache. Regular clients won't need this.
    135      */
    136     int32_t getHardRefCount() const;
    137 
    138     /**
    139      * If noHardReferences() == TRUE then this object has no hard references.
    140      * Must be called only from within the internals of UnifiedCache.
    141      */
    142     inline UBool noHardReferences() const { return getHardRefCount() == 0; }
    143 
    144     /**
    145      * If hasHardReferences() == TRUE then this object has hard references.
    146      * Must be called only from within the internals of UnifiedCache.
    147      */
    148     inline UBool hasHardReferences() const { return getHardRefCount() != 0; }
    149 
    150     /**
    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.
    154      */
    155     UBool noSoftReferences() const { return (softRefCount == 0); }
    156 
    157     /**
    158      * Deletes this object if it has no references or soft references.
    159      */
    160     void deleteIfZeroRefCount() const;
    161 
    162     /**
    163      * @internal For UnifedCache use only to register this object with itself.
    164      *   Must be called before this object is exposed to multiple threads.
    165      */
    166     void registerWithCache(const UnifiedCacheBase *ptr) const {
    167         cachePtr = ptr;
    168     }
    169 
    170     /**
    171      * Returns a writable version of ptr.
    172      * If there is exactly one owner, then ptr itself is returned as a
    173      *  non-const pointer.
    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.
    178      *
    179      * T must be a subclass of SharedObject.
    180      */
    181     template<typename T>
    182     static T *copyOnWrite(const T *&ptr) {
    183         const T *p = ptr;
    184         if(p->getRefCount() <= 1) { return const_cast<T *>(p); }
    185         T *p2 = new T(*p);
    186         if(p2 == NULL) { return NULL; }
    187         p->removeRef();
    188         ptr = p2;
    189         p2->addRef();
    190         return p2;
    191     }
    192 
    193     /**
    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.
    198      *
    199      * T must be a subclass of SharedObject.
    200      */
    201     template<typename T>
    202     static void copyPtr(const T *src, const T *&dest) {
    203         if(src != dest) {
    204             if(dest != NULL) { dest->removeRef(); }
    205             dest = src;
    206             if(src != NULL) { src->addRef(); }
    207         }
    208     }
    209 
    210     /**
    211      * Equivalent to copyPtr(NULL, dest).
    212      */
    213     template<typename T>
    214     static void clearPtr(const T *&ptr) {
    215         if (ptr != NULL) {
    216             ptr->removeRef();
    217             ptr = NULL;
    218         }
    219     }
    220 
    221 private:
    222     mutable u_atomic_int32_t totalRefCount;
    223 
    224     // Any thread modifying softRefCount must hold the global cache mutex
    225     mutable int32_t softRefCount;
    226 
    227     mutable u_atomic_int32_t hardRefCount;
    228     mutable const UnifiedCacheBase *cachePtr;
    229     void addRef(UBool withCacheLock) const;
    230     void removeRef(UBool withCacheLock) const;
    231 
    232 };
    233 
    234 U_NAMESPACE_END
    235 
    236 #endif
    237