org.eclipse.emf.common.util

Class Pool<E>

java.lang.Object

java.util.AbstractCollection<E>

java.util.AbstractSet<E>

org.eclipse.emf.common.util.WeakInterningHashSet<E>

org.eclipse.emf.common.util.Pool<E>

All Implemented Interfaces:

java.io.Serializable, java.lang.Iterable<E>, java.util.Collection<E>, java.util.Set<E>, InterningSet<E>

Direct Known Subclasses:

SegmentSequence.SegmentSequencePool, SegmentSequence.StringArrayPool, URI.URIPool

public class Pool<E>
extends WeakInterningHashSet<E>

A thread safe implementation of a weak interning hash set particularly well-suited for implementing a pool of instances. All access is thread safe, guarded with a shared read lock and an exclusive getWriteLock() lock to support multiple simultaneous readers while ensuring that writes are properly serial. The locks are held for the minimal period to allow maximal concurrency. Removals, i.e., remove, removeAll, clear, and retainAll, are not supported.

Since:

2.9

See Also:

Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
protected static class	Pool.AccessUnit<E> An access unit is used during access to the pool.
protected static class	Pool.ExternalRehasher<E>
protected static class	Pool.ObjectAccessUnit<E>
protected static class	Pool.PoolEntry<E>

Nested classes/interfaces inherited from class org.eclipse.emf.common.util.WeakInterningHashSet

WeakInterningHashSet.Entry<E>, WeakInterningHashSet.SelfCleaningEntry<E>

Field Summary

Fields

Modifier and Type	Field and Description
protected int	accessCount Record the number of accesses so that the cleanup() can be called occasionally.
protected int	cleanupPeriod The number of access between each attempt to clean up garbage collected entries.
protected Pool.AccessUnit.Queue<E>	primaryAccessUnits
protected java.util.concurrent.locks.Lock	readLock To support maximum concurrency, a pair of read and write locks is maintained; this is the read lock.
protected java.util.concurrent.locks.ReentrantReadWriteLock	readWriteLock
protected java.util.concurrent.locks.Lock	writeLock To support maximum concurrency, a pair of read and write locks is maintained; this is the write lock.

Fields inherited from class org.eclipse.emf.common.util.WeakInterningHashSet

capacityIndex, containsNull, entries, externalQueue, internalQueue, modCount, NULL_ENTRY, PRIME_CAPACITIES, size, threshold

Constructor Summary

Constructors

Modifier	Constructor and Description
	Pool() Creates an instance with a capacity of 1031.
	Pool(int minimumCapacity) Creates an instance.
protected	Pool(int minimumCapacity, Pool.AccessUnit.Queue<E> primaryAccessUnits)
protected	Pool(int minimumCapacity, Pool.AccessUnit.Queue<E> primaryAccessUnits, java.lang.ref.ReferenceQueue<java.lang.Object> queue)

Method Summary

Methods

Modifier and Type	Method and Description
protected void	access(boolean isReadLocked, Pool.AccessUnit<E> accessUnit) Collect all the values with a matching hash code.
boolean	add(E value) Specialized to ensure thread safety.
protected E	addEntry(boolean isExclusive, E internalizedValue, Pool.AccessUnit<E> accessUnit) Adds an entry to the pool, but first checks if the entry has been added by another thread since the time when the pool was accessed while without holding any locks.
protected void	cleanup() Specialized to ensure that the write lock is held during cleanup.
void	clear() Throws an UnsupportedOperationException because removal is not supported..
boolean	contains(java.lang.Object value) Specialized to ensure thread safety.
boolean	containsAll(java.util.Collection<?> collection) Specialized to ensure thread safety.
protected void	doCleanup() Calls super.
protected E	doIntern(boolean isExclusive, Pool.AccessUnit<E> accessUnit) Returns the interned version of the value accessed by this access unit and frees the access unit for reuse.
protected boolean	ensureCapacity() Ensures that 3/4 of current capacity is larger than the current size, i.e., that the WeakInterningHashSet.size <= WeakInterningHashSet.threshold.
boolean	equals(java.lang.Object o) Specialized to ensure thread safety.
E	get(E value) Returns either the instance already contained in the set that's equal to the given object, or null if the object is not in the set.
protected WeakInterningHashSet.Entry<E>	getEntry(int hashCode) Gets the first entry with the matching hash code.
java.util.concurrent.locks.Lock	getReadLock() Returns this pool's read lock.
java.util.concurrent.locks.Lock	getWriteLock() Returns this pool's write lock.
void	grow(int minimumCapacity) Specialized to ensure that the exclusive write lock is held during growth.
int	hashCode() Specialized to ensure thread safety.
E	intern(E value) Specialized to ensure thread safety.
java.util.Iterator<E>	iterator() Callers of the iterator must ensure that they hold the shared read lock for the lifetime of the iterator's usage.
protected Pool.AccessUnit.Queue<E>	newDefaultAccessUnits()
protected WeakInterningHashSet.Entry<E>	newExternalEntry(E object, int hashCode) Creates a new entry for the given referent and the given hash code managed by the WeakInterningHashSet.externalQueue.
boolean	remove(java.lang.Object object) Throws an UnsupportedOperationException because removal is not supported..
boolean	removeAll(java.util.Collection<?> collection) Throws an UnsupportedOperationException because removal is not supported..
boolean	retainAll(java.util.Collection<?> collection) Throws an UnsupportedOperationException because removal is not supported..
java.lang.Object[]	toArray() Specialized to ensure thread safety.
<T> T[]	toArray(T[] a) Specialized to ensure thread safety.
java.lang.String	toString() Specialized to ensure thread safety.

Methods inherited from class org.eclipse.emf.common.util.WeakInterningHashSet

addEntry, asInstance, dump, equals, hashCode, index, newEntries, newEntry, newInternalEntry, nullEntry, putEntry, removeEntry, removeEntry, size

Methods inherited from class java.util.AbstractCollection

addAll, isEmpty

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.util.Set

addAll, isEmpty

Field Detail

accessCount

protected int accessCount

Record the number of accesses so that the cleanup() can be called occasionally. It's a state modifying operation, so it must hold the exclusive write lock during execution.

cleanupPeriod

protected int cleanupPeriod

The number of access between each attempt to clean up garbage collected entries. Garbage collecting entries requires the exclusive getWriteLock() to be held, so it's best to do this infrequently.

readWriteLock

protected final java.util.concurrent.locks.ReentrantReadWriteLock readWriteLock

readLock

protected final java.util.concurrent.locks.Lock readLock

To support maximum concurrency, a pair of read and write locks is maintained; this is the read lock.

writeLock

protected final java.util.concurrent.locks.Lock writeLock

To support maximum concurrency, a pair of read and write locks is maintained; this is the write lock.

primaryAccessUnits

protected final Pool.AccessUnit.Queue<E> primaryAccessUnits

Constructor Detail

Pool

public Pool()

Creates an instance with a capacity of 1031.

Pool

public Pool(int minimumCapacity)

Creates an instance.

Pool

protected Pool(int minimumCapacity,
    Pool.AccessUnit.Queue<E> primaryAccessUnits)

Pool

protected Pool(int minimumCapacity,
    Pool.AccessUnit.Queue<E> primaryAccessUnits,
    java.lang.ref.ReferenceQueue<java.lang.Object> queue)

Method Detail

ensureCapacity

protected boolean ensureCapacity()

Description copied from class: WeakInterningHashSet

Ensures that 3/4 of current capacity is larger than the current size, i.e., that the WeakInterningHashSet.size <= WeakInterningHashSet.threshold. If not, it reallocates the entries to the next prime capacity, i.e., it approximate doubles the capacity, and then rehashes the set. The return value indicates whether or note the entries where rehashed.

Overrides:

ensureCapacity in class WeakInterningHashSet<E>

newExternalEntry

protected WeakInterningHashSet.Entry<E> newExternalEntry(E object,
                                             int hashCode)

Description copied from class: WeakInterningHashSet

Creates a new entry for the given referent and the given hash code managed by the WeakInterningHashSet.externalQueue.

Overrides:

newExternalEntry in class WeakInterningHashSet<E>

newDefaultAccessUnits

protected Pool.AccessUnit.Queue<E> newDefaultAccessUnits()

getReadLock

public java.util.concurrent.locks.Lock getReadLock()

Returns this pool's read lock. This should be used only for thread-safe iteration in which remove is not called.

getWriteLock

public java.util.concurrent.locks.Lock getWriteLock()

Returns this pool's write lock. This should be used only for thread-safe iteration in which remove is called.

getEntry

protected WeakInterningHashSet.Entry<E> getEntry(int hashCode)

Gets the first entry with the matching hash code. Use Entry#getNextEntry() to navigate to the next entry with the same hash code. This method does no locking so it may fail to find matches if the pool is rehashing or another thread is adding the entry.

Overrides:

getEntry in class WeakInterningHashSet<E>

access

protected final void access(boolean isReadLocked,
          Pool.AccessUnit<E> accessUnit)

Collect all the values with a matching hash code. If isReadLocked is true it's expected that the read lock is already locked. In this case the access will reliably collect all the matching entries currently in the pool. When isReadLocked is false, the access is done without locking and may spuriously fail to return any matches, i.e., if the pool is currently rehashing, or another thread is currently adding the value. Because removal is not supported, there will never be a spurious match to a removed entry. This also increments accessCount and periodically calls cleanup() if it's not a read locked access.

addEntry

protected final E addEntry(boolean isExclusive,
         E internalizedValue,
         Pool.AccessUnit<E> accessUnit)

Adds an entry to the pool, but first checks if the entry has been added by another thread since the time when the pool was accessed while without holding any locks. The access unit is used to record whether an entry was really added. This returns either the value added, or the value that was already added by another thread. The isExlusive argument controls whether the write lock needs to be acquired (false) or is already acquired (true).

cleanup

protected void cleanup()

Specialized to ensure that the write lock is held during cleanup.

Overrides:

cleanup in class WeakInterningHashSet<E>

doCleanup

protected void doCleanup()

Calls super.WeakInterningHashSet.cleanup().

grow

public void grow(int minimumCapacity)

Specialized to ensure that the exclusive write lock is held during growth.

Overrides:

grow in class WeakInterningHashSet<E>

add

public boolean add(E value)

Specialized to ensure thread safety.

Specified by:

add in interface java.util.Collection<E>

Specified by:

add in interface java.util.Set<E>

Overrides:

add in class WeakInterningHashSet<E>

intern

public E intern(E value)

Specialized to ensure thread safety. If the value needs to be added, an internalized version is added to pool. This implementation delegates to doIntern(boolean, AccessUnit).

Specified by:

intern in interface InterningSet<E>

Overrides:

intern in class WeakInterningHashSet<E>

Parameters:

value - the object to intern.

Returns:

the existing instance already contained in the set equal to the given object, or the object itself (or perhaps in some implementations, an object equal to the object itself).

doIntern

protected E doIntern(boolean isExclusive,
         Pool.AccessUnit<E> accessUnit)

Returns the interned version of the value accessed by this access unit and frees the access unit for reuse.

get

public E get(E value)

Description copied from class: WeakInterningHashSet

Returns either the instance already contained in the set that's equal to the given object, or null if the object is not in the set.

Specified by:

get in interface InterningSet<E>

Overrides:

get in class WeakInterningHashSet<E>

Parameters:

value - the object to intern.

Returns:

the existing instance already contained in the set equal to the given object, or null if the object is not in the set.

contains

public boolean contains(java.lang.Object value)

Specialized to ensure thread safety. This access is done while holding only the shared read lock.

Specified by:

contains in interface java.util.Collection<E>

Specified by:

contains in interface java.util.Set<E>

Overrides:

contains in class WeakInterningHashSet<E>

iterator

public java.util.Iterator<E> iterator()

Callers of the iterator must ensure that they hold the shared read lock for the lifetime of the iterator's usage. Remove is not supported.

Specified by:

iterator in interface java.lang.Iterable<E>

Specified by:

iterator in interface java.util.Collection<E>

Specified by:

iterator in interface java.util.Set<E>

Overrides:

iterator in class WeakInterningHashSet<E>

equals

public boolean equals(java.lang.Object o)

Specialized to ensure thread safety.

Specified by:

equals in interface java.util.Collection<E>

Specified by:

equals in interface java.util.Set<E>

Overrides:

equals in class java.util.AbstractSet<E>

hashCode

public int hashCode()

Specialized to ensure thread safety.

Specified by:

hashCode in interface java.util.Collection<E>

Specified by:

hashCode in interface java.util.Set<E>

Overrides:

hashCode in class java.util.AbstractSet<E>

toArray

public java.lang.Object[] toArray()

Specialized to ensure thread safety.

Specified by:

toArray in interface java.util.Collection<E>

Specified by:

toArray in interface java.util.Set<E>

Overrides:

toArray in class java.util.AbstractCollection<E>

toArray

public <T> T[] toArray(T[] a)

Specialized to ensure thread safety.

Specified by:

toArray in interface java.util.Collection<E>

Specified by:

toArray in interface java.util.Set<E>

Overrides:

toArray in class java.util.AbstractCollection<E>

containsAll

public boolean containsAll(java.util.Collection<?> collection)

Specialized to ensure thread safety.

Specified by:

containsAll in interface java.util.Collection<E>

Specified by:

containsAll in interface java.util.Set<E>

Overrides:

containsAll in class java.util.AbstractCollection<E>

remove

public boolean remove(java.lang.Object object)

Throws an UnsupportedOperationException because removal is not supported..

Specified by:

remove in interface java.util.Collection<E>

Specified by:

remove in interface java.util.Set<E>

Overrides:

remove in class WeakInterningHashSet<E>

removeAll

public boolean removeAll(java.util.Collection<?> collection)

Throws an UnsupportedOperationException because removal is not supported..

Specified by:

removeAll in interface java.util.Collection<E>

Specified by:

removeAll in interface java.util.Set<E>

Overrides:

removeAll in class java.util.AbstractSet<E>

retainAll

public boolean retainAll(java.util.Collection<?> collection)

Throws an UnsupportedOperationException because removal is not supported..

Specified by:

retainAll in interface java.util.Collection<E>

Specified by:

retainAll in interface java.util.Set<E>

Overrides:

retainAll in class java.util.AbstractCollection<E>

clear

public void clear()

Throws an UnsupportedOperationException because removal is not supported..

Specified by:

clear in interface java.util.Collection<E>

Specified by:

clear in interface java.util.Set<E>

Overrides:

clear in class WeakInterningHashSet<E>

toString

public java.lang.String toString()

Specialized to ensure thread safety.

Overrides:

toString in class java.util.AbstractCollection<E>