org.apache.derby.impl.services.cache
Class CacheEntry

java.lang.Object
  extended by org.apache.derby.impl.services.cache.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
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
CacheEntry()
           
 
Method Summary
(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.


Built on Thu 2010-12-23 20:49:13+0000, from revision ???

Apache Derby V10.6 Internals - Copyright © 2004,2007 The Apache Software Foundation. All Rights Reserved.