Overview  Package   Class  Use  Deprecated  Index
Home >> All >> org >> apache >> derby >> impl >> services >> [ cache overview ]	PREV CLASS  NEXT CLASS
SUMMARY:  JAVADOC |  SOURCE |  DOWNLOAD | NESTED | FIELD | CONSTR | METHOD	DETAIL: FIELD | CONSTR | METHOD

---

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

java.lang.Object
  java.util.Dictionary
      java.util.Hashtable
          org.apache.derby.impl.services.cache.Clock

All Implemented Interfaces:

org.apache.derby.iapi.services.cache.CacheManager, java.lang.Cloneable, java.util.Map, java.io.Serializable, org.apache.derby.iapi.services.daemon.Serviceable

---

final class Clock

extends java.util.Hashtable

implements org.apache.derby.iapi.services.cache.CacheManager, org.apache.derby.iapi.services.daemon.Serviceable

A cache manager that uses a Hashtable and a ArrayList. The ArrayList holds CachedItem objects, each with a holder object. The Hashtable is keyed by the identity of the holder object (Cacheable.getIdentity()) and the data portion is a pointer to the CachedItem. CachedItems that have holder objects with no identity do not have entries in the hashtable.

CachedItems can in various state.

• isValid - the entry has a valid identity
• inCreate - the entry is being created or being faulted in from persistent store
• inClean - the entry is being written out to persistent store
• isKept - the entry is currently being looked at/updated, do not remove or clean it.

  Multithreading considerations:
  A clock cache manager must be MT-safe. All member variables are accessed single threaded (synchronized on this) or set once or readonly. Assumptions: holders size() and addElement must be synchronized.
  CachedItem is never passed out of the clock cache manager, only the Cacheable object is. The cachedItem is responsible for the setting and clearing of its own member fields (RESOLVE: now they are done in cache manager, need to be moved to the cachedItem). The cache manager will following the following rules while accessing a cacheditem:

  • invalid item is never returned from the cache
  • setValidState and isValid() is only called single threaded through the cache manager.
  • keep() and isKept() is only called single threaded through the cache manager once the item has been added to the holders array
  • item that isKept() won't be cleaned or removed or invalidated from the cache.
  • item that is inClean() or inCreate(), the cache manager will wait on the cachedItem to finish cleaning or creating before it returns the cached item outside of the cache.
  
  The cacheable must be cleaned thru the cache if it is managed by a cache. On CacheItem, a inClean state is maintain to stablelize the content of the cacheable while it is being cleaned. Only unkept items are cleaned. If an item is found to be inClean, it will wait until it exits the inClean state. If a cached item calls it own clean method without notifying the cache, it has to stablize its content for the duration of the clean.
  It is assumed that the cacheable object maintain its own MT-safeness.
  

  ---

  Nested Class Summary

   

  Nested classes inherited from class java.util.Hashtable

   

  Nested classes inherited from class java.util.Map

  java.util.Map.Entry

   

  Field Summary
  private  boolean	active
  private  org.apache.derby.iapi.services.daemon.DaemonService	cleaner
  private  boolean	cleanerRunning
  private  int	clockHand
  private  long	currentByteCount
  private  org.apache.derby.iapi.services.cache.CacheableFactory	holderFactory
  private  java.util.ArrayList	holders
  private static int	ITEM_OVERHEAD
  private  long	maximumSize
  private  int	myClientNumber
  private  java.lang.String	name
  private  boolean	needService
  CacheStat	stat
  private  int	trimRequests
  private  boolean	useByteCount
  private  int	validItemCount
  private  boolean	wokenToClean

   

  Fields inherited from class java.util.Hashtable

   

  Fields inherited from interface org.apache.derby.iapi.services.daemon.Serviceable

  DONE, REQUEUE

   

  Constructor Summary
  (package private)	Clock(org.apache.derby.iapi.services.cache.CacheableFactory holderFactory, java.lang.String name, int initialSize, long maximumSize, boolean useByteCount)           Construct a new clock cache manager.

   

  Method Summary
  private  org.apache.derby.iapi.services.cache.Cacheable	addEntry(CachedItem item, java.lang.Object key, boolean forCreate, java.lang.Object createParameter)           Add a new CachedItem and a holder object to the cache.
  void	ageOut()           Age as many objects as possible out of the cache.
  void	clean(org.apache.derby.iapi.util.Matchable partialKey)           Clean all objects that match a partial key.
  void	cleanAll()           Clean all objects in the cache.
  protected  void	cleanCache(org.apache.derby.iapi.util.Matchable partialKey)           Write out all dirty buffers.
  org.apache.derby.iapi.services.cache.Cacheable	create(java.lang.Object key, java.lang.Object createParameter)           Create a new object with the said key.
  boolean	discard(org.apache.derby.iapi.util.Matchable partialKey)           Discard all objects that match the partial key.
  org.apache.derby.iapi.services.cache.Cacheable	find(java.lang.Object key)           Find the object or materialize one in the cache.
  org.apache.derby.iapi.services.cache.Cacheable	findCached(java.lang.Object key)           Find an object in the cache.
  protected  CachedItem	findFreeItem()
  long[]	getCacheStats()           Return statistics about cache that may be implemented.
  private  long	getCurrentSize()
  private  int	getItemSize(CachedItem item)
  long	getMaximumSize()
  int	getNumberInUse()           Report the number of items in use (with Identity) in this cache.
  private  CachedItem	growCache()           Grow the cache and return a unused, kept item.
  private  int	incrClockHand()           Synchronously increment clock hand position
  protected  int	performWork(boolean shrinkOnly)           The background cleaner tries to make sure that there are serveral cleaned or invalied buffers ahead of the clock hand so that when they are evicted, they don't need to be cleaned.
  int	performWork(org.apache.derby.iapi.services.context.ContextManager contextMgr)           Do whatever it is that you want the daemon to do for you.
  void	release(org.apache.derby.iapi.services.cache.Cacheable entry)           The caller is no longer looking at or updating the entry.
  protected  void	release(CachedItem item)
  void	remove(org.apache.derby.iapi.services.cache.Cacheable entry)           Remove an object from the cache.
  protected  long	removeIdentity(CachedItem item)           Clear an item's identity.
  void	resetCacheStats()           Reset the statistics to 0.
  void	resize(long newSize)           Change the maximum size of the cache.
  protected  CachedItem	rotateClock(float percentOfClock)           Go through the list of holder objects and find a free one.
  void	scan(org.apache.derby.iapi.util.Matchable filter, org.apache.derby.iapi.util.Operator operator)           Perform an operation on (approximately) all entries that matches the filter, or all entries if the filter is null.
  boolean	serviceASAP()           MT - read only.
  boolean	serviceImmediately()           If this work should be done immediately on the user thread then return true.
  void	setUsed(java.lang.Object[] keys)           Mark a set of entries as having been used.
  protected  long	shrinkSize(long currentSize)
  void	shutdown()           MT - synchronization provided by caller
  private  void	trimToSize()
  void	useDaemonService(org.apache.derby.iapi.services.daemon.DaemonService daemon)           MT - synchronization provided by caller can use this Daemomn service if needed

   

  Methods inherited from class java.util.Hashtable

  clear, clone, contains, containsKey, containsValue, elements, entrySet, equals, get, hashCode, isEmpty, keys, keySet, put, putAll, rehash, remove, size, toString, values

   

  Methods inherited from class java.lang.Object

  finalize, getClass, notify, notifyAll, wait, wait, wait

   

  Methods inherited from interface org.apache.derby.iapi.services.cache.CacheManager

  containsKey

   

  Field Detail

  stat

  public final CacheStat stat

  ---

  cleaner

  private org.apache.derby.iapi.services.daemon.DaemonService cleaner

  ---

  holders

  private final java.util.ArrayList holders

  ---

  validItemCount

  private int validItemCount

  ---

  maximumSize

  private long maximumSize

  ---

  useByteCount

  private boolean useByteCount

  ---

  currentByteCount

  private long currentByteCount

  ---

  ITEM_OVERHEAD

  private static final int ITEM_OVERHEAD

  ---

  holderFactory

  private final org.apache.derby.iapi.services.cache.CacheableFactory holderFactory

  ---

  active

  private boolean active

  ---

  name

  private java.lang.String name

  ---

  clockHand

  private int clockHand

  ---

  myClientNumber

  private int myClientNumber

  ---

  wokenToClean

  private boolean wokenToClean

  ---

  cleanerRunning

  private boolean cleanerRunning

  ---

  needService

  private boolean needService

  ---

  trimRequests

  private int trimRequests

  Constructor Detail

  Clock

  Clock(org.apache.derby.iapi.services.cache.CacheableFactory holderFactory,
        java.lang.String name,
        int initialSize,
        long maximumSize,
        boolean useByteCount)

  Construct a new clock cache manager.

  MT - not needed for constructor.

  Method Detail

  find

  public org.apache.derby.iapi.services.cache.Cacheable find(java.lang.Object key)
                                                      throws org.apache.derby.iapi.error.StandardException

  Find the object or materialize one in the cache. If it has not been created in the persistent store yet, return null.

  MT - must be MT-safe. The cache is single threaded through finding the item in cache and finding a free item if it is not in cache, thus preventing another thread from creating the same item while is is being faulted in. (RESOLVE - this is really low performance if the cache cleaner cannot keep a steady supply of free items and we have to do an I/O while blocking the cache). If it needs to be faulted in, the inCreate bit is set. The item is kept before it exits the sync block.
  If the item is in cache but in the middle of being faulted in or cleaned, it needs to wait until this is done being before returning.
  The keep status prevents other threads from removing this item. The inCreate status prevents other threads from looking at or writing out this item while it is being faulted in. (RESOLVE: need to handle the case where the object is marked for removal and being waited on)

  Specified by:

  find in interface org.apache.derby.iapi.services.cache.CacheManager

  ---

  findCached

  public org.apache.derby.iapi.services.cache.Cacheable findCached(java.lang.Object key)
                                                            throws org.apache.derby.iapi.error.StandardException

  Find an object in the cache. Do not fault in or create the object if is is not found in the cache.

  MT - must be MT-safe. The cache is single threaded through finding the item in cache. If it needs to wait for it to be faulted in or cleaned it is synchronized/waited on the cached item itself.

  Specified by:

  findCached in interface org.apache.derby.iapi.services.cache.CacheManager

  ---

  setUsed

  public void setUsed(java.lang.Object[] keys)

  Mark a set of entries as having been used. Normally this is done as a side effect of find() or findCached. Entries that are no longer in the cache are ignored.

  Specified by:

  setUsed in interface org.apache.derby.iapi.services.cache.CacheManager

  ---

  create

  public org.apache.derby.iapi.services.cache.Cacheable create(java.lang.Object key,
                                                               java.lang.Object createParameter)
                                                        throws org.apache.derby.iapi.error.StandardException

  Create a new object with the said key.

  MT - must be MT-safe. Single thread thru verifying no such item exist in cache and finding a free item, keep the item and set inCreate state. The actual creating of the object is done outside the sync block and is protected by the isKept and inCreate bits.

  Specified by:

  create in interface org.apache.derby.iapi.services.cache.CacheManager

  ---

  release

  public void release(org.apache.derby.iapi.services.cache.Cacheable entry)

  The caller is no longer looking at or updating the entry. Since there could be more than one piece of code looking at this entry, release does not mean nobody is looking at or updating the entry, just one less. If the cacheable is marked for remove (someone is waiting to remove the persistent object once nobody is looking at it), then notify the waiter if this is the last one looking at it.
  Unless there is a good reason to do otherwise, release should be used to release a cachable and not directly call cachedItem unkeep, since unkeep does not handle the case of remove.

  MT - must be MT-safe. Getting and deleteing item from the hashtable is in the same synchronized block. If the cacheable object is waiting to be removed, that is synchronized thru the cachedItem itself (RESOLVE: need to move this sync block to cachedItem instead)

  Specified by:

  release in interface org.apache.derby.iapi.services.cache.CacheManager

  ---

  release

  protected void release(CachedItem item)

  ---

  remove

  public void remove(org.apache.derby.iapi.services.cache.Cacheable entry)
              throws org.apache.derby.iapi.error.StandardException

  Remove an object from the cache. The item will be placed into the NoIdentity state through clean() (if required) and clearIdentity(). The removal of the object will be delayed until it is not kept by anyone. After this call the caller must throw away the reference to item.

  MT - must be MT-safe. Single thread thru finding and setting the remove state of the item, the actual removal of the cacheable is synchronized on the cachedItem itself.

  Specified by:

  remove in interface org.apache.derby.iapi.services.cache.CacheManager

  ---

  cleanAll

  public void cleanAll()
                throws org.apache.derby.iapi.error.StandardException

  Clean all objects in the cache.

  Specified by:

  cleanAll in interface org.apache.derby.iapi.services.cache.CacheManager

  ---

  clean

  public void clean(org.apache.derby.iapi.util.Matchable partialKey)
             throws org.apache.derby.iapi.error.StandardException

  Clean all objects that match a partial key.

  Specified by:

  clean in interface org.apache.derby.iapi.services.cache.CacheManager

  ---

  ageOut

  public void ageOut()

  Age as many objects as possible out of the cache.
  MT - thread safe

  Specified by:

  ageOut in interface org.apache.derby.iapi.services.cache.CacheManager

  ---

  shutdown

  public void shutdown()
                throws org.apache.derby.iapi.error.StandardException

  MT - synchronization provided by caller

  Specified by:

  shutdown in interface org.apache.derby.iapi.services.cache.CacheManager

  ---

  useDaemonService

  public void useDaemonService(org.apache.derby.iapi.services.daemon.DaemonService daemon)

  MT - synchronization provided by caller can use this Daemomn service if needed

  Specified by:

  useDaemonService in interface org.apache.derby.iapi.services.cache.CacheManager

  ---

  discard

  public boolean discard(org.apache.derby.iapi.util.Matchable partialKey)

  Discard all objects that match the partial key.
  MT - thread safe

  Specified by:

  discard in interface org.apache.derby.iapi.services.cache.CacheManager

  ---

  addEntry

  private org.apache.derby.iapi.services.cache.Cacheable addEntry(CachedItem item,
                                                                  java.lang.Object key,
                                                                  boolean forCreate,
                                                                  java.lang.Object createParameter)
                                                           throws org.apache.derby.iapi.error.StandardException

  Add a new CachedItem and a holder object to the cache. The holder object is returned kept.

  MT - need to be MT-safe. The insertion of the key into the hash table is synchronized on this.

  ---

  findFreeItem

  protected CachedItem findFreeItem()
                             throws org.apache.derby.iapi.error.StandardException

  ---

  rotateClock

  protected CachedItem rotateClock(float percentOfClock)
                            throws org.apache.derby.iapi.error.StandardException

  Go through the list of holder objects and find a free one.

  MT - must be MT-safe. The moving of the clockHand and finding of an eviction candidate is synchronized. The cleaning of the cachable is handled by the cacheable itself.

  ---

  incrClockHand

  private int incrClockHand()

  Synchronously increment clock hand position

  ---

  performWork

  public int performWork(org.apache.derby.iapi.services.context.ContextManager contextMgr)

  Description copied from interface: org.apache.derby.iapi.services.daemon.Serviceable

  Do whatever it is that you want the daemon to do for you. There may be multiple daemon objects on different thread calling performWork at the same time. The DaemonService will always call performWork with a context manager set up. the DaemonService will clean up the context if an exception is thrown. However, it is up to performWork to manage its own transaction. If you start a transaction in performWork, you must commit or abort it at the end. You may leave the transaction open so that other serviceable may use the transaction and context without starting a new one. On the same token, there may already be an opened transaction on the context. Serviceable performWork should always check the state of the context before use. A Serviceable object should be well behaved while it is performing the daemon work, i.e., it should not take too many resources or hog the CPU for too long or deadlock with anyone else.

  Specified by:

  performWork in interface org.apache.derby.iapi.services.daemon.Serviceable

  ---

  serviceASAP

  public boolean serviceASAP()

  MT - read only.

  Specified by:

  serviceASAP in interface org.apache.derby.iapi.services.daemon.Serviceable

  ---

  serviceImmediately

  public boolean serviceImmediately()

  Description copied from interface: org.apache.derby.iapi.services.daemon.Serviceable

  If this work should be done immediately on the user thread then return true. If it doesn't make any difference if this work is done on a the user thread immediately or if it is performed by another thread asynchronously later, then return false.

  Specified by:

  serviceImmediately in interface org.apache.derby.iapi.services.daemon.Serviceable

  ---

  getNumberInUse

  public int getNumberInUse()

  Description copied from interface: org.apache.derby.iapi.services.cache.CacheManager

  Report the number of items in use (with Identity) in this cache.

  Specified by:

  getNumberInUse in interface org.apache.derby.iapi.services.cache.CacheManager

  ---

  growCache

  private CachedItem growCache()

  Grow the cache and return a unused, kept item.

  ---

  removeIdentity

  protected long removeIdentity(CachedItem item)

  Clear an item's identity. Item must be unkept and valid. This is called for dirty items from the discard code. Caller must hold the cache synchronization.

  ---

  cleanCache

  protected void cleanCache(org.apache.derby.iapi.util.Matchable partialKey)
                     throws org.apache.derby.iapi.error.StandardException

  Write out all dirty buffers.

  MT - must be MT safe. Single thread on the part that finds the next dirty buffer to write out, the synchronization of cleaning of the individual cachable is provided by the cacheable itself.

  ---

  shrinkSize

  protected long shrinkSize(long currentSize)

  ---

  performWork

  protected int performWork(boolean shrinkOnly)

  The background cleaner tries to make sure that there are serveral cleaned or invalied buffers ahead of the clock hand so that when they are evicted, they don't need to be cleaned. The way this routine work is as follows, starting at the current clock hand position, go forward around the cache buffers, moving the same route that the clock hand moves. It keep tracks of the number of invalid or not recently used buffers it sees along the way. If it sees a not recently used buffer, it will clean it. After it has seen N invalid or not recently used buffers, or it has gone around and visited all buffers in the cache, it finished. It does not clean recently used buffers.

  MT - must be MT-safe. It takes a snapshot of the current clock hand position (a synchronous call). Getting and looking at the next serveral cached item is synchronized on this (RESOLVE: probably doesn't need to be). Cleaning of the cacheable is handle by the cacheable itself.

  ---

  getItemSize

  private int getItemSize(CachedItem item)

  ---

  getCacheStats

  public long[] getCacheStats()

  Return statistics about cache that may be implemented.

  Specified by:

  getCacheStats in interface org.apache.derby.iapi.services.cache.CacheManager

  ---

  resetCacheStats

  public void resetCacheStats()

  Reset the statistics to 0.

  Specified by:

  resetCacheStats in interface org.apache.derby.iapi.services.cache.CacheManager

  ---

  getMaximumSize

  public long getMaximumSize()

  Specified by:

  getMaximumSize in interface org.apache.derby.iapi.services.cache.CacheManager

  ---

  resize

  public void resize(long newSize)
              throws org.apache.derby.iapi.error.StandardException

  Change the maximum size of the cache. If the size is decreased then cache entries will be thrown out.

  Specified by:

  resize in interface org.apache.derby.iapi.services.cache.CacheManager

  ---

  getCurrentSize

  private long getCurrentSize()

  ---

  scan

  public void scan(org.apache.derby.iapi.util.Matchable filter,
                   org.apache.derby.iapi.util.Operator operator)

  Perform an operation on (approximately) all entries that matches the filter, or all entries if the filter is null. Entries that are added while the cache is being scanned might or might not be missed.

  Specified by:

  scan in interface org.apache.derby.iapi.services.cache.CacheManager

  ---

  trimToSize

  private void trimToSize()

  ---

  Overview  Package   Class  Use  Deprecated  Index
  Home >> All >> org >> apache >> derby >> impl >> services >> [ cache overview ]	PREV CLASS  NEXT CLASS
  SUMMARY:  JAVADOC |  SOURCE |  DOWNLOAD | NESTED | FIELD | CONSTR | METHOD	DETAIL: FIELD | CONSTR | METHOD

  ---