| java.util.Hashtable
 org.apache.derby.impl.services.cache.Clock
| Clock | | final class Clock extends Hashtable implements CacheManager,Serviceable(Code) | | 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.
See Also: CachedItem
See Also: Cacheable |
| Constructor Summary | |
| | Clock(CacheableFactory holderFactory, String name, int initialSize, long maximumSize, boolean useByteCount)
Construct a new clock cache manager.
MT - not needed for constructor.
Parameters:
holderFactory - the cacheable object class
Parameters:
name - the name of the cache
Parameters:
initialSize - the initial number of cachable object this cacheholds.
Parameters:
maximumSize - the maximum size of the cache. |
| Clock | | Clock(CacheableFactory holderFactory, String name, int initialSize, long maximumSize, boolean useByteCount)(Code) | | Construct a new clock cache manager.
MT - not needed for constructor.
Parameters:
holderFactory - the cacheable object class
Parameters:
name - the name of the cache
Parameters:
initialSize - the initial number of cachable object this cacheholds.
Parameters:
maximumSize - the maximum size of the cache. The cache may growfrom initialSize to maximumSize if the cache policy notices that thereis not enough free buffers availiable. Once the cache hits maximumSizeit will not grow. If the cache is full, an exception will be thrown |
| ageOut | | public void ageOut()(Code) | | Age as many objects as possible out of the cache.
MT - thread safe
See Also: CacheManager.ageOut |
| cleanCache | | protected void cleanCache(Matchable partialKey) throws StandardException(Code) | | 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.
|
| create | | public Cacheable create(Object key, Object createParameter) throws StandardException(Code) | | 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.
Parameters:
key - the key to the object a cacheable object that is kept in the cache.
exception:
StandardException - Cloudscape Standard error policy |
| discard | | public boolean discard(Matchable partialKey)(Code) | | Discard all objects that match the partial key.
MT - thread safe
|
| find | | public Cacheable find(Object key) throws StandardException(Code) | | 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)
Parameters:
key - the key to the object a cacheable object that is kept in the cache.
exception:
StandardException - Cloudscape Standard error policy |
| findCached | | public Cacheable findCached(Object key) throws StandardException(Code) | | 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.
Parameters:
key - the key to the object a cacheable object that is kept in the cache. |
| getCacheStats | | public synchronized long[] getCacheStats()(Code) | | Return statistics about cache that may be implemented.
|
| getMaximumSize | | public synchronized long getMaximumSize()(Code) | | the current maximum size of the cache. |
| getNumberInUse | | public synchronized int getNumberInUse()(Code) | | |
| performWork | | protected int performWork(boolean shrinkOnly)(Code) | | 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.
|
| release | | public void release(Cacheable entry)(Code) | | 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)
Parameters:
entry - the cached entry |
| remove | | public void remove(Cacheable entry) throws StandardException(Code) | | 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.
exception:
StandardException - Standard Cloudscape error policy. |
| removeIdentity | | protected long removeIdentity(CachedItem item)(Code) | | 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.
the amount by which this shrinks the cache. |
| resetCacheStats | | public void resetCacheStats()(Code) | | Reset the statistics to 0.
|
| resize | | public void resize(long newSize) throws StandardException(Code) | | Change the maximum size of the cache. If the size is decreased then cache entries
will be thrown out.
Parameters:
newSize - the new maximum cache size
exception:
StandardException - Cloudscape Standard error policy |
| rotateClock | | protected CachedItem rotateClock(float percentOfClock) throws StandardException(Code) | | 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.
|
| scan | | public void scan(Matchable filter, Operator operator)(Code) | | 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.
Parameters:
filter -
Parameters:
operator - |
| serviceASAP | | public boolean serviceASAP()(Code) | | MT - read only.
|
| serviceImmediately | | public boolean serviceImmediately()(Code) | | |
| setUsed | | public void setUsed(Object[] keys)(Code) | | 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.
Parameters:
keys - the key of the used entry. |
| shrinkSize | | protected long shrinkSize(long currentSize)(Code) | | |
| useDaemonService | | public void useDaemonService(DaemonService daemon)(Code) | | MT - synchronization provided by caller
can use this Daemomn service if needed
|
|
|