Package 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:

Serializable, Iterable<E>, Collection<E>, 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	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	Description
protected int	accessCount	Record the number of accesses so that the cleanup() can be called occasionally.
protected int	cleanupPeriod	The number of accesses between each attempt to clean up garbage collected entries.
protected final Pool.AccessUnit.Queue<E>	primaryAccessUnits
protected final Lock	readLock	To support maximum concurrency, a pair of read and write locks is maintained; this is the read lock.
protected final ReentrantReadWriteLock	readWriteLock
protected final 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	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, ReferenceQueue<Object> queue)

Method Summary

Modifier and Type	Method	Description
protected final 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 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 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(Object value)	Specialized to ensure thread safety.
boolean	containsAll(Collection<?> collection)	Specialized to ensure thread safety.
protected void	doCleanup()	Calls super.WeakInterningHashSet.cleanup().
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 invalid input: '<'= WeakInterningHashSet.threshold.
boolean	equals(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.
Lock	getReadLock()	Returns this pool's read lock.
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.
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(Object object)	Throws an UnsupportedOperationException because removal is not supported..
boolean	removeAll(Collection<?> collection)	Throws an UnsupportedOperationException because removal is not supported..
boolean	retainAll(Collection<?> collection)	Throws an UnsupportedOperationException because removal is not supported..
Object[]	toArray()	Specialized to ensure thread safety.
<T> T[]	toArray(T[] a)	Specialized to ensure thread safety.
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.Collection

parallelStream, removeIf, stream, toArray

Methods inherited from interface java.lang.Iterable

forEach

Methods inherited from interface java.util.Set

addAll, isEmpty, spliterator

Field Details

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 accesses 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 ReentrantReadWriteLock readWriteLock

readLock

protected final Lock readLock

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

writeLock

protected final 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 Details

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,
 ReferenceQueue<Object> queue)

Method Details

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 invalid input: '<'= 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 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 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 WeakInterningHashSet.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 without holding any locks. The access unit is used to determine whether an entry was already 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 Collection<E>

Specified by:

add in interface 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(Object value)

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

Specified by:

contains in interface Collection<E>

Specified by:

contains in interface Set<E>

Overrides:

contains in class WeakInterningHashSet<E>

iterator

public 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 Collection<E>

Specified by:

iterator in interface Iterable<E>

Specified by:

iterator in interface Set<E>

Overrides:

iterator in class WeakInterningHashSet<E>

equals

public boolean equals(Object o)

Specialized to ensure thread safety.

Specified by:

equals in interface Collection<E>

Specified by:

equals in interface Set<E>

Overrides:

equals in class AbstractSet<E>

hashCode

public int hashCode()

Specialized to ensure thread safety.

Specified by:

hashCode in interface Collection<E>

Specified by:

hashCode in interface Set<E>

Overrides:

hashCode in class AbstractSet<E>

toArray

public Object[] toArray()

Specialized to ensure thread safety.

Specified by:

toArray in interface Collection<E>

Specified by:

toArray in interface Set<E>

Overrides:

toArray in class AbstractCollection<E>

toArray

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

Specialized to ensure thread safety.

Specified by:

toArray in interface Collection<E>

Specified by:

toArray in interface Set<E>

Overrides:

toArray in class AbstractCollection<E>

containsAll

public boolean containsAll(Collection<?> collection)

Specialized to ensure thread safety.

Specified by:

containsAll in interface Collection<E>

Specified by:

containsAll in interface Set<E>

Overrides:

containsAll in class AbstractCollection<E>

remove

public boolean remove(Object object)

Throws an UnsupportedOperationException because removal is not supported..

Specified by:

remove in interface Collection<E>

Specified by:

remove in interface Set<E>

Overrides:

remove in class WeakInterningHashSet<E>

removeAll

public boolean removeAll(Collection<?> collection)

Throws an UnsupportedOperationException because removal is not supported..

Specified by:

removeAll in interface Collection<E>

Specified by:

removeAll in interface Set<E>

Overrides:

removeAll in class AbstractSet<E>

retainAll

public boolean retainAll(Collection<?> collection)

Throws an UnsupportedOperationException because removal is not supported..

Specified by:

retainAll in interface Collection<E>

Specified by:

retainAll in interface Set<E>

Overrides:

retainAll in class AbstractCollection<E>

clear

public void clear()

Throws an UnsupportedOperationException because removal is not supported..

Specified by:

clear in interface Collection<E>

Specified by:

clear in interface Set<E>

Overrides:

clear in class WeakInterningHashSet<E>

toString

public String toString()

Specialized to ensure thread safety.

Overrides:

toString in class AbstractCollection<E>