org.xipki.pkcs11.wrapper

Class ConcurrentBag<T>

java.lang.Object

org.xipki.pkcs11.wrapper.ConcurrentBag<T>

Type Parameters:

T - the templated type to store in the bag

All Implemented Interfaces:

AutoCloseable

public class ConcurrentBag<T>
extends Object
implements AutoCloseable

This is a specialized concurrent bag that achieves superior performance to LinkedBlockingQueue and LinkedTransferQueue for the purposes of a connection pool. It uses ThreadLocal storage when possible to avoid locks, but resorts to scanning a common collection if there are no available items in the ThreadLocal list. Not-in-use items in the ThreadLocal lists can be "stolen" when the borrowing thread has none of its own. It is a "lock-less" implementation using a specialized AbstractQueuedLongSynchronizer to manage cross-thread signaling.

Note that items that are "borrowed" from the bag are not actually removed from any collection, so garbage collection will not occur even if the reference is abandoned. Thus care must be taken to "requite" borrowed objects otherwise a memory leak will result. Only the "remove" method can completely remove an object from the bag.

Author:

Brett Wooldridge, Lijun Liao (xipki)

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	ConcurrentBag.BagEntry<T>

Constructor Summary

Constructors

Constructor and Description
ConcurrentBag() Construct a ConcurrentBag with the specified listener.

Method Summary

Modifier and Type	Method and Description
void	add(ConcurrentBag.BagEntry<T> bagEntry) Add a new object to the bag for others to borrow.
ConcurrentBag.BagEntry<T>	borrow(long timeout, TimeUnit timeUnit) The method will borrow a BagEntry from the bag, blocking for the specified timeout if none are available.
void	close() Close the bag to further adds.
boolean	remove(ConcurrentBag.BagEntry<T> bagEntry) Remove a value from the bag.
void	requite(ConcurrentBag.BagEntry<T> bagEntry) This method will return a borrowed object to the bag.
int	size() Get the total number of items in the bag.
List<ConcurrentBag.BagEntry<T>>	values() This method provides a "snapshot" in time of the bag items.

Methods inherited from class java.lang.Object

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

Constructor Detail

ConcurrentBag

public ConcurrentBag()

Construct a ConcurrentBag with the specified listener.

Method Detail

borrow

public ConcurrentBag.BagEntry<T> borrow(long timeout,
                                        TimeUnit timeUnit)
                                 throws InterruptedException

The method will borrow a BagEntry from the bag, blocking for the specified timeout if none are available.

Parameters:

timeout - how long to wait before giving up, in units of unit

timeUnit - a TimeUnit determining how to interpret the timeout parameter

Returns:

a borrowed instance from the bag or null if a timeout occurs

Throws:

InterruptedException - if interrupted while waiting

requite

public void requite(ConcurrentBag.BagEntry<T> bagEntry)

This method will return a borrowed object to the bag. Objects that are borrowed from the bag but never "requited" will result in a memory leak.

Parameters:

bagEntry - the value to return to the bag

Throws:

NullPointerException - if value is null

IllegalStateException - if the bagEntry was not borrowed from the bag

add

public void add(ConcurrentBag.BagEntry<T> bagEntry)

Add a new object to the bag for others to borrow.

Parameters:

bagEntry - an object to add to the bag

remove

public boolean remove(ConcurrentBag.BagEntry<T> bagEntry)

Remove a value from the bag. This method should only be called with objects obtained by borrow(long, TimeUnit) or reserve(T)

Parameters:

bagEntry - the value to remove

Returns:

true if the entry was removed, false otherwise

Throws:

IllegalStateException - if an attempt is made to remove an object from the bag that was not borrowed or reserved first

close

public void close()

Close the bag to further adds.

Specified by:

close in interface AutoCloseable

values

public List<ConcurrentBag.BagEntry<T>> values()

This method provides a "snapshot" in time of the bag items. It does not "lock" or reserve items in any way. Call reserve(T) on items in the list, or understand the concurrency implications of modifying items, before performing any action on them.

Returns:

a possibly empty list of (all) bag items

size

public int size()

Get the total number of items in the bag.

Returns:

the number of items in the bag