Class CacheEntry


  • final class CacheEntry
    extends java.lang.Object
    Class representing an entry in the cache. It is used by ConcurrentCache. When a thread invokes any of the methods in this class, except lock(), it must first have called lock() to ensure exclusive access to the entry.

    When no thread holds the lock on the entry, it must be in one of the following states:

    Uninitialized
    The entry object has just been constructed, but has not yet been initialized. In this state, isValid() returns false, whereas isKept() returns true in order to prevent removal of the entry until it has been initialized. When the entry is in this state, calls to lockWhenIdentityIsSet() will block until settingIdentityComplete() has been called.
    Unkept
    In this state, the entry object contains a reference to a Cacheable and the keep count is zero. isValid() returns true and isKept() returns false in this state. getCacheable() returns a non-null value.
    Kept
    Same as the unkept state, except that the keep count is positive and isKept() returns true.
    Removed
    The entry has been removed from the cache. In this state, isValid() and isKept() return false, and getCacheable() returns null. When an entry has entered the removed state, it cannot be transitioned back to any of the other states.

    To prevent deadlocks, each thread should normally lock only one entry at a time. In some cases it is legitimate to hold the lock on two entries, for instance if an entry must be evicted to make room for a new entry. If this is the case, exactly one of the two entries must be in the uninitialized state, and the uninitialized entry must be locked before the lock on the other entry can be requested.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      private Cacheable cacheable
      The cached object.
      private ReplacementPolicy.Callback callback
      Callback object used to notify the replacement algorithm about events on the cached objects (like accesses and requests for removal).
      private java.util.concurrent.locks.Condition forRemove
      Condition variable used to notify a thread that it is allowed to remove the entry from the cache.
      private int keepCount
      How many threads are currently keeping this entry.
      private java.util.concurrent.locks.ReentrantLock mutex
      Mutex which guards the internal state of the entry.
      private java.util.concurrent.locks.Condition settingIdentity
      Condition variable used to notify a thread that the setting of this entry's identity is complete.
    • Constructor Summary

      Constructors 
      Constructor Description
      CacheEntry()  
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      (package private) void free()
      Clear this entry and notify the replacement algorithm that the Cacheable can be reused.
      (package private) Cacheable getCacheable()
      Return the cached object held by this entry.
      (package private) boolean isKept()
      Check whether or not this entry is kept.
      (package private) boolean isValid()
      Check whether this entry holds a valid object.
      (package private) void keep​(boolean accessed)
      Increase the keep count for this entry.
      (package private) void lock()
      Block until the current thread is granted exclusive access to the entry.
      (package private) void setCacheable​(Cacheable c)
      Set the cached object held by this entry.
      (package private) void setCallback​(ReplacementPolicy.Callback cb)
      Set the callback object used to notify the replacement algorithm about actions performed on the cached object.
      (package private) void settingIdentityComplete()
      Notify this entry that the initialization of its cacheable has been completed.
      (package private) void unkeep()
      Decrement the keep count for this entry.
      (package private) void unkeepForRemove()
      Unkeep the entry and wait until no other thread is keeping it.
      (package private) void unlock()
      Give up exclusive access.
      (package private) void waitUntilIdentityIsSet()
      Block until this entry's cacheable has been initialized (that is, until settingIdentityComplete() has been called on this object).
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

      • mutex

        private final java.util.concurrent.locks.ReentrantLock mutex
        Mutex which guards the internal state of the entry.
      • cacheable

        private Cacheable cacheable
        The cached object. If it is null, it means that the entry is invalid (either uninitialized or removed).
      • keepCount

        private int keepCount
        How many threads are currently keeping this entry.
      • forRemove

        private java.util.concurrent.locks.Condition forRemove
        Condition variable used to notify a thread that it is allowed to remove the entry from the cache. If it is null, there is no thread waiting for the entry to be unkept.
      • settingIdentity

        private java.util.concurrent.locks.Condition settingIdentity
        Condition variable used to notify a thread that the setting of this entry's identity is complete. This variable is non-null when the object is created, and will be set to null when the identity has been set.
        See Also:
        settingIdentityComplete()
      • callback

        private ReplacementPolicy.Callback callback
        Callback object used to notify the replacement algorithm about events on the cached objects (like accesses and requests for removal).
    • Constructor Detail

      • CacheEntry

        CacheEntry()
    • Method Detail

      • lock

        void lock()
        Block until the current thread is granted exclusive access to the entry.
      • waitUntilIdentityIsSet

        void waitUntilIdentityIsSet()
        Block until this entry's cacheable has been initialized (that is, until settingIdentityComplete() has been called on this object). If the cacheable has been initialized before this method is called, it will return immediately. The entry must have been locked for exclusive access before this method is called. If the method needs to wait, it will release the lock and reobtain it when it wakes up again.
      • unlock

        void unlock()
        Give up exclusive access.
      • settingIdentityComplete

        void settingIdentityComplete()
        Notify this entry that the initialization of its cacheable has been completed. This method should be called after Cacheable.setIdentity() or Cacheable.createIdentity() has been called.
      • keep

        void keep​(boolean accessed)
        Increase the keep count for this entry. An entry which is kept cannot be removed from the cache.
        Parameters:
        accessed - if true, notify the entry's callback object that it has been accessed (normally because of calls to create, find or findCached); otherwise, don't notify the callback object
      • unkeep

        void unkeep()
        Decrement the keep count for this entry. An entry cannot be removed from the cache until its keep count is zero.
      • isKept

        boolean isKept()
        Check whether or not this entry is kept.
        Returns:
        true if the object is kept
      • unkeepForRemove

        void unkeepForRemove()
        Unkeep the entry and wait until no other thread is keeping it. This method is used when a thread requests the removal of the entry. As defined by the contract of CacheManager.remove(), it is the responsibility of the caller to ensure that only a single thread executes this method on an object.
        See Also:
        CacheManager.remove(org.apache.derby.iapi.services.cache.Cacheable)
      • setCacheable

        void setCacheable​(Cacheable c)
        Set the cached object held by this entry.
        Parameters:
        c - a cacheable, or null if the entry is about to be removed
      • getCacheable

        Cacheable getCacheable()
        Return the cached object held by this entry.
        Returns:
        the cached object in this entry
      • isValid

        boolean isValid()
        Check whether this entry holds a valid object. That is, it must hold a non-null Cacheable and have completed setting its identity.
        Returns:
        true if the entry holds a valid object
      • setCallback

        void setCallback​(ReplacementPolicy.Callback cb)
        Set the callback object used to notify the replacement algorithm about actions performed on the cached object.
        Parameters:
        cb - the callback object
      • free

        void free()
        Clear this entry and notify the replacement algorithm that the Cacheable can be reused.