stormpot

Class Config<T extends Poolable>

java.lang.Object

stormpot.Config<T>

All Implemented Interfaces:

Cloneable

public class Config<T extends Poolable>
extends Object
implements Cloneable

The basic configuration "bean" class.

Instances of this class is passed to the constructors of pools so that they know how big they should be, how to allocate objects and when to deallocate objects.

This class is made thread-safe by having the fields be protected by the intrinsic object lock on the Config object itself. This way, pools can synchronize on the config object to read the values out atomically.

The various set* methods are made to return the Config instance itself, so that the method calls may be chained if so desired.

Standardised configuration

The contract of the Config class, and how Pools will interpret it, is within the context of a so-called standardised configuration. All pool and Config implementations must behave similarly in a standardised configuration.

It is conceivable that some pool implementations will come with their own sub-classes of Config, that allow greater control over the pools behaviour. It is even permissible that these pool implementations may deviate from the contract of the Pool interface. However, they are only allowed to do so in a non-standard configuration. That is, any deviation from the specified contracts must be explicitly enabled.

Author:

Chris Vest <mr.chrisvest@gmail.com>

Constructor Summary

Constructors

Constructor and Description
Config() Build a new empty Config object.

Method Summary

Modifier and Type	Method and Description
Config<T>	clone() Returns a shallow copy of this Config object.
Allocator<T>	getAllocator() Get the configured Allocator instance.
Expiration<? super T>	getExpiration() Get the configured Expiration instance.
MetricsRecorder	getMetricsRecorder() Get the configured MetricsRecorder instance, or null if none has been configured.
Reallocator<T>	getReallocator() Get the configured Allocator instance as a Reallocator.
int	getSize() Get the currently configured size.
ThreadFactory	getThreadFactory() Get the ThreadFactory that has been configured, and will be used to create the background allocation threads for the pools.
boolean	isBackgroundExpirationEnabled() Return whether or not background expiration is enabled, which it is not by default.
boolean	isPreciseLeakDetectionEnabled() Return whether or not precise object leak detection is enabled, which is the case by default.
<X extends Poolable> Config<X>	setAllocator(Allocator<X> allocator) Set the Allocator or Reallocator to use for the pools we want to configure.
Config<T>	setBackgroundExpirationEnabled(boolean enabled) Enable or disable background object expiration checking.
Config<T>	setExpiration(Expiration<? super T> expiration) Set the Expiration to use for the pools we want to configure.
Config<T>	setMetricsRecorder(MetricsRecorder metricsRecorder) Set the MetricsRecorder to use for the pools we want to configure.
Config<T>	setPreciseLeakDetectionEnabled(boolean enabled) Enable or disable precise object leak detection.
Config<T>	setSize(int size) Set the size of the pools we want to configure them with.
Config<T>	setThreadFactory(ThreadFactory factory) Set the ThreadFactory that the pools will use to create its background threads with.
void	validate() Deprecated. This method will be removed in version 3.0. No alternative is provided, because it is really an internal API.

Methods inherited from class java.lang.Object

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

Constructor Detail

Config

public Config()

Build a new empty Config object. Most settings have reasonable default values. However, no Allocator is configured by default, and one must make sure to set one.

Method Detail

setSize

public Config<T> setSize(int size)

Set the size of the pools we want to configure them with. Pools are required to control the allocations and deallocations, such that no more than this number of objects are allocated at any time.

This means that a pool of size 1, whose single object have expired, will deallocate that one object before allocating a replacement.

The size must be at least one for standard pool configurations. A Pool will throw an IllegalArgumentException from their constructor if this is not the case.

Parameters:

size - The target pool size. Must be at least 1.

Returns:

This Config instance.

getSize

public int getSize()

Get the currently configured size. Default is 10.

Returns:

The configured pool size.

setAllocator

public <X extends Poolable> Config<X> setAllocator(Allocator<X> allocator)

Set the Allocator or Reallocator to use for the pools we want to configure. This will change the type-parameter of the Config object to match that of the new Allocator.

The allocator is initially null in a new Config object, and can be set to null any time. However, in a standard configuration, it must be non-null when the Config is passed to a Pool constructor. Otherwise the constructor will throw an IllegalArgumentException.

Parameters:

allocator - The allocator we want our pools to use.

<X> - The type of Poolable that is created by the allocator, and the type of objects that the configured pools will contain.

Returns:

This Config instance, but with a generic type parameter that matches that of the allocator.

getAllocator

public Allocator<T> getAllocator()

Get the configured Allocator instance. There is no configured allocator by default, so this must be set before instantiating any Pool implementations from this Config.

Returns:

The configured Allocator instance, if any.

getReallocator

public Reallocator<T> getReallocator()

Get the configured Allocator instance as a Reallocator. If the configured allocator implements the Reallocator interface, then it is returned directly. Otherwise, the allocator is wrapped in an adaptor.

Returns:

A configured or adapted Reallocator, if any.

setExpiration

public Config<T> setExpiration(Expiration<? super T> expiration)

Set the Expiration to use for the pools we want to configure. The Expiration determines when a pooled object is valid for claiming, or when the objects are invalid and should be deallocated.

The default Expiration is a TimeSpreadExpiration that invalidates the objects after they have been active for somewhere between 8 to 10 minutes.

Parameters:

expiration - The expiration we want our pools to use. Not null.

Returns:

This Config instance.

getExpiration

public Expiration<? super T> getExpiration()

Get the configured Expiration instance. The default is a TimeSpreadExpiration that expires objects after somewhere between 8 to 10 minutes.

Returns:

The configured Expiration.

setMetricsRecorder

public Config<T> setMetricsRecorder(MetricsRecorder metricsRecorder)

Set the MetricsRecorder to use for the pools we want to configure.

Parameters:

metricsRecorder - The MetricsRecorder to use, or null if we don’t want to use any.

Returns:

This Config instance.

getMetricsRecorder

public MetricsRecorder getMetricsRecorder()

Get the configured MetricsRecorder instance, or null if none has been configured.

Returns:

The configured MetricsRecorder.

getThreadFactory

public ThreadFactory getThreadFactory()

Get the ThreadFactory that has been configured, and will be used to create the background allocation threads for the pools. The default is similar to the Executors.defaultThreadFactory(), except the string "Stormpot-" is prepended to the thread name.

Returns:

The configured thread factory.

setThreadFactory

public Config<T> setThreadFactory(ThreadFactory factory)

Set the ThreadFactory that the pools will use to create its background threads with. The ThreadFactory is not allowed to be null, and creating a pool with a null ThreadFactory will throw an IllegalArgumentException.

Parameters:

factory - The ThreadFactory the pool should use to create their background threads.

Returns:

This Config instance.

isPreciseLeakDetectionEnabled

public boolean isPreciseLeakDetectionEnabled()

Return whether or not precise object leak detection is enabled, which is the case by default.

Returns:

true if precise object leak detection is enabled.

See Also:

setPreciseLeakDetectionEnabled(boolean)

setPreciseLeakDetectionEnabled

public Config<T> setPreciseLeakDetectionEnabled(boolean enabled)

Enable or disable precise object leak detection. It is enabled by default. Precise object leak detection makes the pool keep an eye on the allocated Poolables, such that it notices if they get garbage collected without first being deallocated. Using the garbage collector for this purpose, means that no false positives (counting objects as leaked, even though they are not) are ever reported.

Note	While the pool is able to detect object leaks, it cannot prevent them. All leaks are a sign that there is a bug in the system; most likely a bug in your code, or in the way the pool is used.

Precise object leak detection incurs virtually no overhead, and is safe to leave enabled at all times – even in the most demanding production environments.

Parameters:

enabled - true to turn on precise object leak detection (the default) false to turn it off.

Returns:

This Config instance.

isBackgroundExpirationEnabled

public boolean isBackgroundExpirationEnabled()

Return whether or not background expiration is enabled, which it is not by default.

Returns:

true if background expiration has been enabled.

See Also:

setBackgroundExpirationEnabled(boolean)

setBackgroundExpirationEnabled

public Config<T> setBackgroundExpirationEnabled(boolean enabled)

Enable or disable background object expiration checking. This is disabled by default, because the pool does not know how expensive this check is. The cost of the check matters because it might end up taking resources away from the background thread and hinder its ability to keep up with the demand for allocations and deallocations, even though these tasks always take priority over any expiration checking.

Parameters:

enabled - true to turn background expiration checking on, false (the default) to turn it off.

Returns:

This Config instance.

clone

public final Config<T> clone()

Returns a shallow copy of this Config object.

Overrides:

clone in class Object

Returns:

A new Config object of the exact same type as this one, with identical values in all its fields.

validate

@Deprecated
public void validate()
                          throws IllegalArgumentException

Deprecated. This method will be removed in version 3.0. No alternative is provided, because it is really an internal API.

Check that the configuration is valid in terms of the standard configuration. This method is useful in the Pool implementation constructors.

Throws:

IllegalArgumentException - If the size is less than one, if the Expiration is null, if the Allocator is null, or if the ThreadFactory is null.