Class CacheEntry

java.lang.Object
org.apache.derby.impl.services.cache.CacheEntry

final class CacheEntry extends 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
    The cached object.
    Callback object used to notify the replacement algorithm about events on the cached objects (like accesses and requests for removal).
    private Condition
    Condition variable used to notify a thread that it is allowed to remove the entry from the cache.
    private int
    How many threads are currently keeping this entry.
    private final ReentrantLock
    Mutex which guards the internal state of the entry.
    private Condition
    Condition variable used to notify a thread that the setting of this entry's identity is complete.
  • Constructor Summary

    Constructors
    Constructor
    Description
     
  • Method Summary

    Modifier and Type
    Method
    Description
    (package private) void
    Clear this entry and notify the replacement algorithm that the Cacheable can be reused.
    (package private) Cacheable
    Return the cached object held by this entry.
    (package private) boolean
    Check whether or not this entry is kept.
    (package private) boolean
    Check whether this entry holds a valid object.
    (package private) void
    keep(boolean accessed)
    Increase the keep count for this entry.
    (package private) void
    Block until the current thread is granted exclusive access to the entry.
    (package private) void
    Set the cached object held by this entry.
    (package private) void
    Set the callback object used to notify the replacement algorithm about actions performed on the cached object.
    (package private) void
    Notify this entry that the initialization of its cacheable has been completed.
    (package private) void
    Decrement the keep count for this entry.
    (package private) void
    Unkeep the entry and wait until no other thread is keeping it.
    (package private) void
    Give up exclusive access.
    (package private) void
    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 Details

    • mutex

      private final 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 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 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:
    • 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 Details

    • CacheEntry

      CacheEntry()
  • Method Details

    • 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:
    • 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.