com.bigdata.cache

Class SynchronizedHardReferenceQueueWithTimeout<T>

java.lang.Object

com.bigdata.cache.SynchronizedHardReferenceQueueWithTimeout<T>

All Implemented Interfaces:

IHardReferenceQueue<T>

public class SynchronizedHardReferenceQueueWithTimeout<T>
extends Object
implements IHardReferenceQueue<T>

Thread-safe version with timeout for clearing stale references from the queue. Clearing of stale entries is accomplished when a value is added to the SynchronizedHardReferenceQueue. The tail of the queue is tested and any entry on the tail whose age exceeds a timeout is evicted. This continues until we reach the first value on the tail of the queue whose age is greater than the timeout. This behavior is enabled if a non-ZERO timeout is specified. Stales references are also cleared by a background thread.

Version:

$Id: SynchronizedHardReferenceQueueWithTimeout.java 4410 2011-04-17 20:11:44Z thompsonbry $

Author:

Bryan Thompson

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	SynchronizedHardReferenceQueueWithTimeout.IRef<T> Interface for something wrapping a reference.

Field Summary

Fields inherited from interface com.bigdata.cache.IHardReferenceQueue

DEFAULT_NSCAN

Constructor Summary

Constructors

Constructor and Description
SynchronizedHardReferenceQueueWithTimeout(int capacity, int nscan, long timeoutNanos) Optional timeout.
SynchronizedHardReferenceQueueWithTimeout(int capacity, long timeoutNanos) Variant with no listener and timeout.

Method Summary

Methods

Modifier and Type	Method and Description
boolean	add(T ref) Add a reference to the cache.
int	capacity() The cache capacity.
void	clear(boolean clearRefs) Clears the cache (sets the head, tail and count to zero) without generating eviction notices.
boolean	evict() Evict the LRU reference.
void	evictAll(boolean clearRefs) Evict all references, starting with the LRU reference and proceeding to the MRU reference.
boolean	isEmpty() True iff the cache is empty.
boolean	isFull() True iff the cache is full.
int	nscan() The #of references that are tested on append requests.
T	peek() The reference at the tail of the queue.
int	size() The #of references in the cache.
static void	stopStaleReferenceCleaner() This method may be invoked by life cycle operations which need to tear down the bigdata environment.
long	timeout() The timeout (in nanoseconds) for an entry in the queue.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SynchronizedHardReferenceQueueWithTimeout

public SynchronizedHardReferenceQueueWithTimeout(int capacity,
                                         long timeoutNanos)

Variant with no listener and timeout.

Parameters:

capacity - The maximum #of references that can be stored on the cache. There is no guarantee that all stored references are distinct.

timeoutNanos - The timeout (in nanoseconds) for an entry in the queue. When ZERO (0L), the timeout is disabled.

SynchronizedHardReferenceQueueWithTimeout

public SynchronizedHardReferenceQueueWithTimeout(int capacity,
                                         int nscan,
                                         long timeoutNanos)

Optional timeout.

Parameters:

capacity - The maximum #of references that can be stored on the cache. There is no guarantee that all stored references are distinct.

nscan - The #of references to scan from the MRU position before appended a reference to the cache. Scanning is used to reduce the chance that references that are touched several times in near succession from entering the cache more than once. The #of reference tests trades off against the latency of adding a reference to the cache.

timeoutNanos - The timeout (in nanoseconds) for an entry in the queue. When ZERO (0L), the timeout is disabled.

Method Detail

timeout

public final long timeout()

The timeout (in nanoseconds) for an entry in the queue. When ZERO (0L), the timeout is disabled.

capacity

public final int capacity()

Description copied from interface: IHardReferenceQueue

The cache capacity.

Specified by:

capacity in interface IHardReferenceQueue<T>

nscan

public final int nscan()

Description copied from interface: IHardReferenceQueue

The #of references that are tested on append requests.

Specified by:

nscan in interface IHardReferenceQueue<T>

add

public boolean add(T ref)

Description copied from interface: IHardReferenceQueue

Add a reference to the cache. If the reference was recently added to the cache then this is a NOP. Otherwise the reference is appended to the cache. If a reference is appended to the cache and then cache is at capacity, then the LRU reference is first evicted from the cache.

Specified by:

add in interface IHardReferenceQueue<T>

Parameters:

ref - The reference to be added.

Returns:

True iff the reference was added to the cache and false iff the reference was found in a scan of the nscan MRU cache entries.

clear

public void clear(boolean clearRefs)

Description copied from interface: IHardReferenceQueue

Clears the cache (sets the head, tail and count to zero) without generating eviction notices.

Specified by:

clear in interface IHardReferenceQueue<T>

Parameters:

clearRefs - When true the references are explicitly set to null which can facilitate garbage collection.

evict

public boolean evict()

Description copied from interface: IHardReferenceQueue

Evict the LRU reference. This is a NOP iff the cache is empty.

Specified by:

evict in interface IHardReferenceQueue<T>

Returns:

true iff a reference was evicted.

See Also:

HardReferenceQueueEvictionListener

evictAll

public void evictAll(boolean clearRefs)

Description copied from interface: IHardReferenceQueue

Evict all references, starting with the LRU reference and proceeding to the MRU reference.

Specified by:

evictAll in interface IHardReferenceQueue<T>

Parameters:

clearRefs - When true, the reference are actually cleared from the cache. This may be false to force persistence of the references in the cache without actually clearing the cache.

peek

public T peek()

Description copied from interface: IHardReferenceQueue

The reference at the tail of the queue. This is the next reference that will be evicted from the queue.

Specified by:

peek in interface IHardReferenceQueue<T>

isEmpty

public boolean isEmpty()

Description copied from interface: IHardReferenceQueue

True iff the cache is empty.

Specified by:

isEmpty in interface IHardReferenceQueue<T>

isFull

public boolean isFull()

Description copied from interface: IHardReferenceQueue

True iff the cache is full.

Specified by:

isFull in interface IHardReferenceQueue<T>

size

public int size()

Description copied from interface: IHardReferenceQueue

The #of references in the cache. Note that there is no guarantee that the references are distinct.

Specified by:

size in interface IHardReferenceQueue<T>

stopStaleReferenceCleaner

public static final void stopStaleReferenceCleaner()

This method may be invoked by life cycle operations which need to tear down the bigdata environment. Normally you do not need to do this as the cleaner service uses a daemon thread and will not prevent the JVM from halting. However, a servlet container running bigdata can complain that some threads were not terminated if the webapp running bigdata is stopped. You can invoke this method to terminate the stale reference cleaner thread.