com.bigdata.counters.striped

Class StripedCounters<T extends StripedCounters<T>>

java.lang.Object

com.bigdata.counters.striped.StripedCounters<T>

Direct Known Subclasses:

RWStore.StoreCounters, WORMStrategy.StoreCounters

public class StripedCounters<T extends StripedCounters<T>>
extends Object

Abstract base class and template for striped counters designed for high concurrency with eventual consistency and approximate read back without CAS contention.

Each instance of this class in use by the application is backed by an array of N instances protected by striped locks. You acquire() an instance and then directly manipulate the value of the counters on that instance. When you release() the instance, the counters MAY be published to the outer instance visible to your application using add(StripedCounters). This is similar to an eventually consistent transactional model, except that there are no constraints on the validity of the updates imposed by this scheme.

If reads will be made against the shared instance without holding a lock, then the individual counters should be volatile fields, AtomicLong, or the like so that updates will be visible each time add(StripedCounters) is invoked by release() will be published in a timely manner.

Author:

Bryan Thompson

Field Summary

Fields

Modifier and Type	Field and Description
protected int	batchSize #of releases before we post the counters to the parent.
protected ReentrantLock[]	locks
protected int	n Decremented by release() - when ZERO (0) we post the counters to the parent and reset to the batchSize
protected T	parent

Constructor Summary

Constructors

Constructor and Description
StripedCounters() Required public zero argument constructor provides no concurrency control.
StripedCounters(int batchSize) Create a striped counters object using numProcessors*2 stripes and the specified batchSize.
StripedCounters(int nstripes, int batchSize) Create a striped counters object.

Method Summary

Methods

Modifier and Type	Method and Description
T	acquire() Acquire a "stripe" counters object.
void	add(T o) Adds counters to the current counters.
void	clear() Clear the counter values back to zero.
CounterSet	getCounters() Return a new, empty CounterSet.
void	release() Release the counters.
T	subtract(T o) Returns a new StripedCounters containing the current counter values minus the given counter values.
String	toString() Return a serialization of the performance counters.

Methods inherited from class java.lang.Object

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

Field Detail

batchSize

protected int batchSize

#of releases before we post the counters to the parent.

n

protected int n

Decremented by release() - when ZERO (0) we post the counters to the parent and reset to the batchSize

locks

protected final ReentrantLock[] locks

parent

protected T extends StripedCounters<T> parent

Constructor Detail

StripedCounters

public StripedCounters()

Required public zero argument constructor provides no concurrency control. Instances created with this constructor are used (internally) in a variety of contexts where striped locks are not appropriate and may be used by the application as well if striped locks are not necessary.

StripedCounters

public StripedCounters(int batchSize)

Create a striped counters object using numProcessors*2 stripes and the specified batchSize.

Parameters:

batchSize - The values on the instance stripes will be published to the outer instance every batchSize release()s.

StripedCounters

public StripedCounters(int nstripes,
               int batchSize)

Create a striped counters object.

Parameters:

nstripes - The #of stripes. Each stripe is protected by a lock. The stripe is selected by acquire() based on Object.hashCode(). The chances of a contention with a concurrent thread are (1.0/nstripes).

batchSize - The values on the instance stripes will be published to the outer instance every batchSize release()s.

Method Detail

acquire

public final T acquire()

Acquire a "stripe" counters object. The selected stripe is based on Object.hashCode(). The chances of a contention with a concurrent thread are (1.0/nstripes).

Note: When using this class you MUST be careful to avoid constructions which could lead to lock ordering problems. If there are other locks help, then each acquire() MAY result in a deadlock with an acquire() by another thread depending on which stripe is selected for each thread. Such deadlocks are obviously path dependent and difficult to detect.

release

public final void release()

Release the counters.

add

public void add(T o)

Adds counters to the current counters.

Parameters:

o - The other counters.

subtract

public T subtract(T o)

Returns a new StripedCounters containing the current counter values minus the given counter values.

Parameters:

o - The other counters.

Returns:

A new set of counters.

clear

public void clear()

Clear the counter values back to zero.

getCounters

public CounterSet getCounters()

Return a new, empty CounterSet. This method must be extended to attach the various performance counters to that CounterSet.

toString

public String toString()

Return a serialization of the performance counters.

Overrides:

toString in class Object