org.apache.qpid.pool

Class ReferenceCountingExecutorService

java.lang.Object

org.apache.qpid.pool.ReferenceCountingExecutorService

public class ReferenceCountingExecutorService
extends Object

ReferenceCountingExecutorService wraps an ExecutorService in order to provide shared reference to it. It counts the references taken, instantiating the service on the first reference, and shutting it down when the last reference is released.

It is important to ensure that an executor service is correctly shut down as failing to do so prevents the JVM from terminating due to the existence of non-daemon threads.

TODO Might be more elegant to make this actually implement ExecutorService, providing better hiding of the implementation details. Also this class introduces a pattern (albeit specific to this usage) that could be generalized to reference count anything. That is, on first instance call a create method, on release of last instance call a destroy method. This could definitely be abstracted out as a re-usable piece of code; a reference counting factory. It could then be re-used to do reference counting in other places (such as messages). Countable objects have a simple create/destroy life cycle, capturable by an interface that the ref counting factory can call to manage the lifecycle.

TODO The getPool() method breaks the encapsulation of the reference counter. Generally when getPool is used further checks are applied to ensure that the executor service has not been shutdown. This passes responsibility for managing the lifecycle of the reference counted object onto the caller rather than neatly encapsulating it here. Could think about adding more state to the lifecycle, to mark ref counted objects as invalid, and have an isValid method, or could make calling code deal with RejectedExecutionException raised by shutdown executors.

Method Summary

Methods

Modifier and Type	Method and Description
ExecutorService	acquireExecutorService() Provides a reference to a shared executor service, incrementing the reference count.
static ReferenceCountingExecutorService	getInstance() Retrieves the singleton instance of this reference counter.
ExecutorService	getPool() Provides access to the executor service, without touching the reference count.
int	getReferenceCount() Return the ReferenceCount to this ExecutorService
ThreadFactory	getThreadFactory() Return the thread factory used by the ThreadPoolExecutor to create new threads.
void	releaseExecutorService() Releases a reference to a shared executor service, decrementing the reference count.
void	setThreadFactory(ThreadFactory threadFactory) Sets the thread factory used by the ThreadPoolExecutor to create new threads.

Methods inherited from class java.lang.Object

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

Method Detail

getInstance

public static ReferenceCountingExecutorService getInstance()

Retrieves the singleton instance of this reference counter.

Returns:

The singleton instance of this reference counter.

acquireExecutorService

public ExecutorService acquireExecutorService()

Provides a reference to a shared executor service, incrementing the reference count.

Returns:

An executor service.

releaseExecutorService

public void releaseExecutorService()

Releases a reference to a shared executor service, decrementing the reference count. If the reference count falls to zero, the executor service is shut down.

getPool

public ExecutorService getPool()

Provides access to the executor service, without touching the reference count.

Returns:

The shared executor service, or null if none has been instantiated yet.

getReferenceCount

public int getReferenceCount()

Return the ReferenceCount to this ExecutorService

Returns:

reference count

getThreadFactory

public ThreadFactory getThreadFactory()

Return the thread factory used by the ThreadPoolExecutor to create new threads.

Returns:

thread factory

setThreadFactory

public void setThreadFactory(ThreadFactory threadFactory)

Sets the thread factory used by the ThreadPoolExecutor to create new threads.

If the pool has been already created, the change will have no effect until getReferenceCount() reaches zero and the pool recreated. For this reason, callers must invoke this method before calling acquireExecutorService().

Parameters:

threadFactory - thread factory