ICU-66108.tar.gz

[apple/icu.git] / icuSources / common / sharedobject.h

diff --git a/icuSources/common/sharedobject.h b/icuSources/common/sharedobject.h
index d0b9303925836381d957b9c193e60ea85e8e9c87..c0a5aba4782821bb0bd24a0f068850e9b7af08e5 100644 (file)
--- a/icuSources/common/sharedobject.h
+++ b/icuSources/common/sharedobject.h
@@ -1,3 +1,5 @@
+// © 2016 and later: Unicode, Inc. and others.
+// License & terms of use: http://www.unicode.org/copyright.html

 /*
 ******************************************************************************
 * Copyright (C) 2015-2016, International Business Machines
 /*
 ******************************************************************************
 * Copyright (C) 2015-2016, International Business Machines


@@ -15,6 +17,8 @@
 
 U_NAMESPACE_BEGIN
 
 
 U_NAMESPACE_BEGIN
 

+class SharedObject;
+

 /**
  * Base class for unified cache exposing enough methods to SharedObject
  * instances to allow their addRef() and removeRef() methods to
 /**
  * Base class for unified cache exposing enough methods to SharedObject
  * instances to allow their addRef() and removeRef() methods to


@@ -26,22 +30,12 @@ public:
     UnifiedCacheBase() { }
 
     /**
     UnifiedCacheBase() { }
 
     /**

-     * Called by addRefWhileHoldingCacheLock() when the hard reference count
-     * of its instance goes from 0 to 1.
+     * Notify the cache implementation that an object was seen transitioning to
+     * zero hard references. The cache may use this to keep track the number of
+     * unreferenced SharedObjects, and to trigger evictions.

      */
      */

-    virtual void incrementItemsInUse() const = 0;
+    virtual void handleUnreferencedObject() const = 0;

 
 

-    /**
-     * Called by removeRef() when the hard reference count of its instance
-     * drops from 1 to 0.
-     */
-    virtual void decrementItemsInUseWithLockingAndEviction() const = 0;
-
-    /**
-     * Called by removeRefWhileHoldingCacheLock() when the hard reference
-     * count of its instance drops from 1 to 0.
-     */
-    virtual void decrementItemsInUse() const = 0;

     virtual ~UnifiedCacheBase();
 private:
     UnifiedCacheBase(const UnifiedCacheBase &);
     virtual ~UnifiedCacheBase();
 private:
     UnifiedCacheBase(const UnifiedCacheBase &);


@@ -61,7 +55,6 @@ class U_COMMON_API SharedObject : public UObject {
 public:
     /** Initializes totalRefCount, softRefCount to 0. */
     SharedObject() :
 public:
     /** Initializes totalRefCount, softRefCount to 0. */
     SharedObject() :

-            totalRefCount(0),

             softRefCount(0),
             hardRefCount(0),
             cachePtr(NULL) {}
             softRefCount(0),
             hardRefCount(0),
             cachePtr(NULL) {}


@@ -69,7 +62,6 @@ public:
     /** Initializes totalRefCount, softRefCount to 0. */
     SharedObject(const SharedObject &other) :
             UObject(other),
     /** Initializes totalRefCount, softRefCount to 0. */
     SharedObject(const SharedObject &other) :
             UObject(other),

-            totalRefCount(0),

             softRefCount(0),
             hardRefCount(0),
             cachePtr(NULL) {}
             softRefCount(0),
             hardRefCount(0),
             cachePtr(NULL) {}


@@ -77,93 +69,45 @@ public:
     virtual ~SharedObject();
 
     /**
     virtual ~SharedObject();
 
     /**

-     * Increments the number of references to this object. Thread-safe.
-     */
-    void addRef() const { addRef(FALSE); }
-
-    /**
-     * Increments the number of references to this object.
-     * Must be called only from within the internals of UnifiedCache and
-     * only while the cache global mutex is held.
-     */
-    void addRefWhileHoldingCacheLock() const { addRef(TRUE); }
-
-    /**
-     * Increments the number of soft references to this object.
-     * Must be called only from within the internals of UnifiedCache and
-     * only while the cache global mutex is held.
-     */
-    void addSoftRef() const;
-
-    /**
-     * Decrements the number of references to this object. Thread-safe.
-     */
-    void removeRef() const { removeRef(FALSE); }
-
-    /**
-     * Decrements the number of references to this object.
-     * Must be called only from within the internals of UnifiedCache and
-     * only while the cache global mutex is held.
+     * Increments the number of hard references to this object. Thread-safe.
+     * Not for use from within the Unified Cache implementation.

      */
      */

-    void removeRefWhileHoldingCacheLock() const { removeRef(TRUE); }
+    void addRef() const;

 
     /**
 
     /**

-     * Decrements the number of soft references to this object.
-     * Must be called only from within the internals of UnifiedCache and
-     * only while the cache global mutex is held.
+     * Decrements the number of hard references to this object, and
+     * arrange for possible cache-eviction and/or deletion if ref
+     * count goes to zero. Thread-safe.
+     * 
+     * Not for use from within the UnifiedCache implementation.

      */
      */

-    void removeSoftRef() const;
+    void removeRef() const;

 
     /**
 
     /**

-     * Returns the reference counter including soft references.
+     * Returns the number of hard references for this object.

      * Uses a memory barrier.
      */
     int32_t getRefCount() const;
 
      * Uses a memory barrier.
      */
     int32_t getRefCount() const;
 

-    /**
-     * Returns the count of soft references only.
-     * Must be called only from within the internals of UnifiedCache and
-     * only while the cache global mutex is held.
-     */
-    int32_t getSoftRefCount() const { return softRefCount; }
-
-    /**
-     * Returns the count of hard references only. Uses a memory barrier.
-     * Used for testing the cache. Regular clients won't need this.
-     */
-    int32_t getHardRefCount() const;
-

     /**
      * If noHardReferences() == TRUE then this object has no hard references.
      * Must be called only from within the internals of UnifiedCache.
      */
     /**
      * If noHardReferences() == TRUE then this object has no hard references.
      * Must be called only from within the internals of UnifiedCache.
      */

-    inline UBool noHardReferences() const { return getHardRefCount() == 0; }
+    inline UBool noHardReferences() const { return getRefCount() == 0; }

 
     /**
      * If hasHardReferences() == TRUE then this object has hard references.
      * Must be called only from within the internals of UnifiedCache.
      */
 
     /**
      * If hasHardReferences() == TRUE then this object has hard references.
      * Must be called only from within the internals of UnifiedCache.
      */

-    inline UBool hasHardReferences() const { return getHardRefCount() != 0; }
+    inline UBool hasHardReferences() const { return getRefCount() != 0; }

 
     /**
 
     /**

-     * If noSoftReferences() == TRUE then this object has no soft references.
-     * Must be called only from within the internals of UnifiedCache and
-     * only while the cache global mutex is held.
-     */
-    UBool noSoftReferences() const { return (softRefCount == 0); }
-
-    /**
-     * Deletes this object if it has no references or soft references.
+     * Deletes this object if it has no references.
+     * Available for non-cached SharedObjects only. Ownership of cached objects
+     * is with the UnifiedCache, which is solely responsible for eviction and deletion.

      */
     void deleteIfZeroRefCount() const;
 
      */
     void deleteIfZeroRefCount() const;
 

-    /**
-     * @internal For UnifedCache use only to register this object with itself.
-     *   Must be called before this object is exposed to multiple threads.
-     */ 
-    void registerWithCache(const UnifiedCacheBase *ptr) const {
-        cachePtr = ptr;
-    }

         
     /**
      * Returns a writable version of ptr.
         
     /**
      * Returns a writable version of ptr.


@@ -217,15 +161,21 @@ public:
     }
 
 private:
     }
 
 private:

-    mutable u_atomic_int32_t totalRefCount;
-
-    // Any thread modifying softRefCount must hold the global cache mutex
+    /**
+     * The number of references from the UnifiedCache, which is
+     * the number of times that the sharedObject is stored as a hash table value.
+     * For use by UnifiedCache implementation code only.
+     * All access is synchronized by UnifiedCache's gCacheMutex
+     */

     mutable int32_t softRefCount;
     mutable int32_t softRefCount;

+    friend class UnifiedCache;

 
 

+    /**
+     * Reference count, excluding references from within the UnifiedCache implementation.
+     */

     mutable u_atomic_int32_t hardRefCount;
     mutable u_atomic_int32_t hardRefCount;

+    

     mutable const UnifiedCacheBase *cachePtr;
     mutable const UnifiedCacheBase *cachePtr;

-    void addRef(UBool withCacheLock) const;
-    void removeRef(UBool withCacheLock) const;

 
 };
 
 
 };