com.zaxxer.hikari.util

Class ConcurrentBag<T extends ConcurrentBag.IBagManagable>

java.lang.Object

com.zaxxer.hikari.util.ConcurrentBag<T>

Type Parameters:

T - the templated type to store in the bag

public class ConcurrentBag<T extends ConcurrentBag.IBagManagable>
extends Object

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

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	ConcurrentBag.IBagManagable This interface must be implemented by classes wishing to be managed by ConcurrentBag.
static interface	ConcurrentBag.IBagStateListener This interface is implemented by a listener to the bag.

Field Summary

Fields

Modifier and Type	Field and Description
static int	STATE_IN_USE
static int	STATE_NOT_IN_USE

Constructor Summary

Constructors

Constructor and Description
ConcurrentBag() Constructor.

Method Summary

Modifier and Type	Method and Description
void	add(T value) Add a new object to the bag for others to borrow.
void	addBagStateListener(ConcurrentBag.IBagStateListener listener) Add a listener to the bag.
T	borrow(long timeout, TimeUnit timeUnit) The method will borrow an IBagManagable from the bag, blocking for the specified timeout if none are available.
int	getCount(int state)
int	getPendingQueue() Get the number of threads pending (waiting) for an item from the bag to become available.
void	remove(T value) Remove a value from the bag.
void	requite(T value) This method will return a borrowed object to the bag.
boolean	reserve(T value) The method is used to make an item in the bag "unavailable" for borrowing.
int	size() Get the total number of items in the bag.
void	unreserve(T value) This method is used to make an item reserved via reserve(IBagManagable) available again for borrowing.
List<T>	values(int state) This method provides a "snaphot" in time of the IBagManagable items in the bag in the specified state.

Methods inherited from class java.lang.Object

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

Field Detail

STATE_NOT_IN_USE

public static final int STATE_NOT_IN_USE

See Also:

Constant Field Values

STATE_IN_USE

public static final int STATE_IN_USE

See Also:

Constant Field Values

Constructor Detail

ConcurrentBag

public ConcurrentBag()

Constructor.

Method Detail

borrow

public T borrow(long timeout,
                TimeUnit timeUnit)
         throws InterruptedException

The method will borrow an IBagManagable 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(T value)

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:

value - the value to return to the bag

Throws:

NullPointerException - if value is null

IllegalStateException - if the requited value was not borrowed from the bag

add

public void add(T value)

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

Parameters:

value - an object to add to the bag

remove

public void remove(T value)

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

Parameters:

value - the value to remove

Throws:

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

values

public List<T> values(int state)

This method provides a "snaphot" in time of the IBagManagable items in the bag in the specified state. It does not "lock" or reserve items in any way. Call reserve(IBagManagable) on items in list before performing any action on them.

Parameters:

state - one of STATE_NOT_IN_USE or STATE_IN_USE

Returns:

a possibly empty list of objects having the state specified

reserve

public boolean reserve(T value)

The method is used to make an item in the bag "unavailable" for borrowing. It is primarily used when wanting to operate on items returned by the values(int) method. Items that are reserved can be removed from the bag via remove(IBagManagable) without the need to unreserve them. Items that are not removed from the bag can be make available for borrowing again by calling the unreserve(IBagManagable) method.

Parameters:

value - the item to reserve

Returns:

true if the item was able to be reserved, false otherwise

unreserve

public void unreserve(T value)

This method is used to make an item reserved via reserve(IBagManagable) available again for borrowing.

Parameters:

value - the item to unreserve

addBagStateListener

public void addBagStateListener(ConcurrentBag.IBagStateListener listener)

Add a listener to the bag. There can only be one. If this method is called a second time, the original listener will be evicted.

Parameters:

listener - a listener to the bag

getPendingQueue

public int getPendingQueue()

Get the number of threads pending (waiting) for an item from the bag to become available.

Returns:

the number of threads waiting for items from the bag

getCount

public int getCount(int state)

size

public int size()

Get the total number of items in the bag.

Returns:

the number of items in the bag