stormpot 3.1 · stormpot.PoolBuilder

Modifier and Type	Field and Description
private final AllocationProcess	allocationProcess
private Allocator<T>	allocator
private int	backgroundExpirationCheckDelay
private boolean	backgroundExpirationEnabled
pack-priv static final Map<AllocationProcessMode, PoolBuilderDefaults>	DEFAULTS
private Expiration<? super T>	expiration
private MetricsRecorder	metricsRecorder
pack-priv static final Map<AllocationProcessMode, PoolBuilderPermissions>	PERMISSIONS
private final PoolBuilderPermissions	permissions
private boolean	preciseLeakDetectionEnabled
private int	size
private ThreadFactory	threadFactory

Access	Constructor and Description
pack-priv	PoolBuilder(AllocationProcess allocationProcess, Allocator<T> allocator) Build a new empty `PoolBuilder` object.

Method Summary

Modifier and Type	Method and Description
public synchronized Pool<T>	Returns: A `Pool` instance as configured by this builder. build() Build a `Pool` instance based on the collected configuration.
private void	checkPermission(boolean permission, String fieldDescription)
public final synchronized PoolBuilder<T>	Returns: A new `PoolBuilder` object of the exact same type as this one, with identical values in all its fields. clone() Overrides java.lang.Object.clone. Returns a shallow copy of this `PoolBuilder` object.
pack-priv synchronized Reallocator<T>	getAdaptedReallocator() Returns a `Reallocator`, possibly by adapting the configured `Allocator` if need be.
public synchronized Allocator<T>	Returns: The configured Allocator instance. getAllocator() Get the configured `Allocator` instance.
public synchronized int	Returns: the delay, in milliseconds, between background maintenance tasks. getBackgroundExpirationCheckDelay() Return the default approximate delay, in milliseconds, between background maintenance tasks, such as the background expiration checks and retrying failed allocations.
public synchronized Expiration<? super T>	Returns: The configured Expiration. getExpiration() Get the configured `Expiration` instance.
public synchronized MetricsRecorder	Returns: The configured MetricsRecorder. getMetricsRecorder() Get the configured `MetricsRecorder` instance, or null if none has been configured.
public synchronized Reallocator<T>	Returns: A configured or adapted Reallocator. getReallocator() Get the configured `stormpot.Allocator` instance as a `stormpot.Reallocator`.
public synchronized int	Returns: The configured pool size. getSize() Get the currently configured size.
public synchronized ThreadFactory	Returns: The configured thread factory. getThreadFactory() Get the ThreadFactory that has been configured, and will be used to create the background allocation threads for the pools.
public synchronized boolean	Returns: `true` if background expiration is enabled. isBackgroundExpirationEnabled() Return whether or not background expiration is enabled.
public synchronized boolean	Returns: `true` if precise object leak detection is enabled. isPreciseLeakDetectionEnabled() Return whether or not precise object leak detection is enabled, which is the case by default.
public synchronized < The type of `Poolable` that is created by the allocator, and the type of objects that the configured pools will contain. X extends Poolable> PoolBuilder<X>	Returns: This `PoolBuilder` instance, but with a generic type parameter that matches that of the allocator. setAllocator(Allocator<X> The allocator we want our pools to use. This cannot be `null`. allocator) Set the `Allocator` or `Reallocator` to use for the pools we want to configure.
public synchronized PoolBuilder<T>	Returns: This `PoolBuilder` instance. setBackgroundExpirationCheckDelay(int the desired delay, in milliseconds, between background maintenance tasks. delay) Set the approximate delay, in milliseconds, between background maintenance tasks.
public synchronized PoolBuilder<T>	Returns: This `PoolBuilder` instance. setBackgroundExpirationEnabled(boolean `true` (the default) to turn background expiration checking on, `false` to turn it off. enabled) Enable or disable background object expiration checking.
public synchronized PoolBuilder<T>	Returns: This `PoolBuilder` instance. setExpiration(Expiration<? super T> The expiration we want our pools to use. Not null. expiration) Set the `Expiration` to use for the pools we want to configure.
public synchronized PoolBuilder<T>	Returns: This `PoolBuilder` instance. setMetricsRecorder(MetricsRecorder The MetricsRecorder to use, or null if we don't want to use any. metricsRecorder) Set the `MetricsRecorder` to use for the pools we want to configure.
public synchronized PoolBuilder<T>	Returns: This `PoolBuilder` instance. setPreciseLeakDetectionEnabled(boolean `true` to turn on precise object leak detection (the default) `false` to turn it off. enabled) Enable or disable precise object leak detection.
public synchronized PoolBuilder<T>	Returns: This `PoolBuilder` instance. setSize(int The target pool size. Must be at least 0. size) Set the size of the pool we are building.
public synchronized PoolBuilder<T>	Returns: This `PoolBuilder` instance. setThreadFactory(ThreadFactory The ThreadFactory the pool should use to create their background threads. factory) Set the ThreadFactory that the pools will use to create its background threads with.

Inherited from java.lang.Object:: equals finalize getClass hashCode notify notifyAll toString wait wait wait

allocationProcess	back to summary
private final AllocationProcess allocationProcess

allocator	back to summary
private Allocator<T> allocator

backgroundExpirationCheckDelay	back to summary
private int backgroundExpirationCheckDelay

backgroundExpirationEnabled	back to summary
private boolean backgroundExpirationEnabled

DEFAULTS	back to summary
pack-priv static final Map<AllocationProcessMode, PoolBuilderDefaults> DEFAULTS

expiration	back to summary
private Expiration<? super T> expiration

metricsRecorder	back to summary
private MetricsRecorder metricsRecorder

PERMISSIONS	back to summary
pack-priv static final Map<AllocationProcessMode, PoolBuilderPermissions> PERMISSIONS

permissions	back to summary
private final PoolBuilderPermissions permissions

preciseLeakDetectionEnabled	back to summary
private boolean preciseLeakDetectionEnabled

size	back to summary
private int size

threadFactory	back to summary
private ThreadFactory threadFactory

PoolBuilder	back to summary
pack-priv PoolBuilder(AllocationProcess allocationProcess, Allocator<T> allocator) Build a new empty `PoolBuilder` object.

Method Detail

build back to summary

build	back to summary
public synchronized Pool<T> build() Build a `Pool` instance based on the collected configuration. Returns:Pool<T> A `Pool` instance as configured by this builder.

public synchronized Pool<T> build()

Build a Pool instance based on the collected configuration.

Returns:Pool<T>: A Pool instance as configured by this builder.

checkPermission	back to summary
private void checkPermission(boolean permission, String fieldDescription)

clone	back to summary
public final synchronized PoolBuilder<T> clone() Overrides java.lang.Object.clone. Returns a shallow copy of this `PoolBuilder` object. Returns:PoolBuilder<T> A new `PoolBuilder` object of the exact same type as this one, with identical values in all its fields. Annotations @SuppressWarnings:unchecked @Override

clone

back to summary

public final synchronized PoolBuilder<T> clone()

Overrides java.lang.Object.clone.

Returns a shallow copy of this `PoolBuilder` object.

Returns:PoolBuilder<T>

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

Annotations

@SuppressWarnings:unchecked
@Override

getAdaptedReallocator	back to summary
pack-priv synchronized Reallocator<T> getAdaptedReallocator() Returns a `Reallocator`, possibly by adapting the configured `Allocator` if need be. If a `MetricsRecorder` has been configured, the return `Reallocator` will automatically record allocation, reallocation and deallocation latencies.

getAllocator back to summary

getAllocator	back to summary
public synchronized Allocator<T> getAllocator() Get the configured `Allocator` instance. Returns:Allocator<T> The configured Allocator instance.

public synchronized Allocator<T> getAllocator()

Get the configured Allocator instance.

Returns:Allocator<T>: The configured Allocator instance.

getBackgroundExpirationCheckDelay	back to summary
public synchronized int getBackgroundExpirationCheckDelay() Return the default approximate delay, in milliseconds, between background maintenance tasks, such as the background expiration checks and retrying failed allocations. Returns:int the delay, in milliseconds, between background maintenance tasks.

getBackgroundExpirationCheckDelay

back to summary

public synchronized int getBackgroundExpirationCheckDelay()

Return the default approximate delay, in milliseconds, between background maintenance tasks, such as the background expiration checks and retrying failed allocations.

Returns:int: the delay, in milliseconds, between background maintenance tasks.

getExpiration back to summary

getExpiration	back to summary
public synchronized Expiration<? super T> getExpiration() Get the configured `Expiration` instance. The default is a `Expiration#after(long, long, TimeUnit)` that expires objects after somewhere between 8 to 10 minutes. Returns:Expiration<? super T> The configured Expiration.

public synchronized Expiration<? super T> getExpiration()

Get the configured Expiration instance. The default is a Expiration#after(long, long, TimeUnit) that expires objects after somewhere between 8 to 10 minutes.

Returns:Expiration<? super T>: The configured Expiration.

getMetricsRecorder back to summary

getMetricsRecorder	back to summary
public synchronized MetricsRecorder getMetricsRecorder() Get the configured `MetricsRecorder` instance, or null if none has been configured. Returns:MetricsRecorder The configured MetricsRecorder.

public synchronized MetricsRecorder getMetricsRecorder()

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

Returns:MetricsRecorder: The configured MetricsRecorder.

getReallocator back to summary

getReallocator	back to summary
public synchronized Reallocator<T> getReallocator() Get the configured `stormpot.Allocator` instance as a `stormpot.Reallocator`. If the configured allocator implements the Reallocator interface, then it is returned directly. Otherwise, the allocator is wrapped in an adaptor. Returns:Reallocator<T> A configured or adapted Reallocator.

public synchronized Reallocator<T> getReallocator()

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

Returns:Reallocator<T>: A configured or adapted Reallocator.

getSize	back to summary
public synchronized int getSize() Get the currently configured size. The default is 10. Returns:int The configured pool size.

getSize

back to summary

public synchronized int getSize()

Get the currently configured size. The default is 10.

Returns:int: The configured pool size.

getThreadFactory back to summary

getThreadFactory	back to summary
public synchronized 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 `java.util.concurrent.Executors#defaultThreadFactory()`, except the string "Stormpot-" is prepended to the thread name. Returns:ThreadFactory The configured thread factory.

public synchronized 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 java.util.concurrent.Executors#defaultThreadFactory(), except the string "Stormpot-" is prepended to the thread name.

Returns:ThreadFactory: The configured thread factory.

isBackgroundExpirationEnabled back to summary

isBackgroundExpirationEnabled	back to summary
public synchronized boolean isBackgroundExpirationEnabled() Return whether or not background expiration is enabled. By default, background expiration is enabled. Returns:boolean `true` if background expiration is enabled. See Also `setBackgroundExpirationEnabled(boolean)`

public synchronized boolean isBackgroundExpirationEnabled()

Return whether or not background expiration is enabled. By default, background expiration is enabled.

Returns:boolean: `true` if background expiration is enabled.
See Also: setBackgroundExpirationEnabled(boolean)

isPreciseLeakDetectionEnabled back to summary

isPreciseLeakDetectionEnabled	back to summary
public synchronized boolean isPreciseLeakDetectionEnabled() Return whether or not precise object leak detection is enabled, which is the case by default. Returns:boolean `true` if precise object leak detection is enabled. See Also `setPreciseLeakDetectionEnabled(boolean)`

public synchronized boolean isPreciseLeakDetectionEnabled()

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

Returns:boolean: `true` if precise object leak detection is enabled.
See Also: setPreciseLeakDetectionEnabled(boolean)

setAllocator back to summary

setAllocator	back to summary
public synchronized <X extends Poolable> PoolBuilder<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 `PoolBuilder` object to match that of the new Allocator. The allocator is initially specified by the `Pool#from(Allocator)` method, so there is usually no need to set it later. Parameters <X> The type of `Poolable` that is created by the allocator, and the type of objects that the configured pools will contain. allocator:Allocator<X> The allocator we want our pools to use. This cannot be `null`. Returns:PoolBuilder<X> This `PoolBuilder` instance, but with a generic type parameter that matches that of the allocator. Annotations @SuppressWarnings:unchecked

public synchronized <X extends Poolable> PoolBuilder<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 `PoolBuilder` object to match that of the new Allocator. The allocator is initially specified by the Pool#from(Allocator) method, so there is usually no need to set it later.

Parameters

<X>: The type of Poolable that is created by the allocator, and the type of objects that the configured pools will contain.
allocator:Allocator<X>: The allocator we want our pools to use. This cannot be `null`.

Returns:PoolBuilder<X>

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

Annotations

@SuppressWarnings:unchecked

setBackgroundExpirationCheckDelay	back to summary
public synchronized PoolBuilder<T> setBackgroundExpirationCheckDelay(int delay) Set the approximate delay, in milliseconds, between background maintenance tasks. These tasks include the background expiration checks, and retrying failed allocations. The default delay is 1.000 milliseconds (1 second). Lowering this value will improve the pools responsiveness to repairing failed allocations, and also increase the frequency of the background expiration checks. This comes at the cost of higher idle CPU usage. It is not recommended to set this value lower than 100 milliseconds. Values lower than this tend to have increased CPU and power usage, for very little gain in responsiveness for the background tasks. Parameters delay:int the desired delay, in milliseconds, between background maintenance tasks. Returns:PoolBuilder<T> This `PoolBuilder` instance.

setBackgroundExpirationCheckDelay

back to summary

public synchronized PoolBuilder<T> setBackgroundExpirationCheckDelay(int delay)

Set the approximate delay, in milliseconds, between background maintenance tasks. These tasks include the background expiration checks, and retrying failed allocations. The default delay is 1.000 milliseconds (1 second). Lowering this value will improve the pools responsiveness to repairing failed allocations, and also increase the frequency of the background expiration checks. This comes at the cost of higher idle CPU usage. It is not recommended to set this value lower than 100 milliseconds. Values lower than this tend to have increased CPU and power usage, for very little gain in responsiveness for the background tasks.

Parameters

delay:int: the desired delay, in milliseconds, between background maintenance tasks.

Returns:PoolBuilder<T>

This `PoolBuilder` instance.

setBackgroundExpirationEnabled	back to summary
public synchronized PoolBuilder<T> setBackgroundExpirationEnabled(boolean enabled) Enable or disable background object expiration checking. This is enabled by default, but can be turned off if the check is expensive. 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:boolean `true` (the default) to turn background expiration checking on, `false` to turn it off. Returns:PoolBuilder<T> This `PoolBuilder` instance.

setBackgroundExpirationEnabled

back to summary

public synchronized PoolBuilder<T> setBackgroundExpirationEnabled(boolean enabled)

Enable or disable background object expiration checking. This is enabled by default, but can be turned off if the check is expensive. 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:boolean: `true` (the default) to turn background expiration checking on, `false` to turn it off.

Returns:PoolBuilder<T>

This `PoolBuilder` instance.

setExpiration back to summary

setExpiration	back to summary
public synchronized PoolBuilder<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 an `Expiration#after(long, long, TimeUnit)` that invalidates the objects after they have been active for somewhere between 8 to 10 minutes. Parameters expiration:Expiration<? super T> The expiration we want our pools to use. Not null. Returns:PoolBuilder<T> This `PoolBuilder` instance.

public synchronized PoolBuilder<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 an Expiration#after(long, long, TimeUnit) that invalidates the objects after they have been active for somewhere between 8 to 10 minutes.

Parameters

expiration:Expiration<? super T>: The expiration we want our pools to use. Not null.

Returns:PoolBuilder<T>

This `PoolBuilder` instance.

setMetricsRecorder back to summary

setMetricsRecorder	back to summary
public synchronized PoolBuilder<T> setMetricsRecorder(MetricsRecorder metricsRecorder) Set the `MetricsRecorder` to use for the pools we want to configure. Parameters metricsRecorder:MetricsRecorder The MetricsRecorder to use, or null if we don't want to use any. Returns:PoolBuilder<T> This `PoolBuilder` instance.

public synchronized PoolBuilder<T> setMetricsRecorder(MetricsRecorder metricsRecorder)

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

Parameters

metricsRecorder:MetricsRecorder: The MetricsRecorder to use, or null if we don't want to use any.

Returns:PoolBuilder<T>

This `PoolBuilder` instance.

setPreciseLeakDetectionEnabled	back to summary
public synchronized PoolBuilder<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:boolean `true` to turn on precise object leak detection (the default) `false` to turn it off. Returns:PoolBuilder<T> This `PoolBuilder` instance.

setPreciseLeakDetectionEnabled

back to summary

public synchronized PoolBuilder<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:boolean: `true` to turn on precise object leak detection (the default) `false` to turn it off.

Returns:PoolBuilder<T>

This `PoolBuilder` instance.

setSize back to summary

setSize	back to summary
public synchronized PoolBuilder<T> setSize(int size) Set the size of the pool we are building. 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, or an `IllegalArgumentException` will be thrown when building the pool. Note that the pool size can be modified after the pool has been built, by calling the `Pool#setTargetSize(int)` or `ManagedPool#setTargetSize(int)` methods. Parameters size:int The target pool size. Must be at least 0. Returns:PoolBuilder<T> This `PoolBuilder` instance.

public synchronized PoolBuilder<T> setSize(int size)

Set the size of the pool we are building. 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, or an IllegalArgumentException will be thrown when building the pool. Note that the pool size can be modified after the pool has been built, by calling the Pool#setTargetSize(int) or ManagedPool#setTargetSize(int) methods.

Parameters

size:int: The target pool size. Must be at least 0.

Returns:PoolBuilder<T>

This `PoolBuilder` instance.

setThreadFactory	back to summary
public synchronized PoolBuilder<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:ThreadFactory The ThreadFactory the pool should use to create their background threads. Returns:PoolBuilder<T> This `PoolBuilder` instance.

setThreadFactory

back to summary

public synchronized PoolBuilder<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:ThreadFactory: The ThreadFactory the pool should use to create their background threads.

Returns:PoolBuilder<T>

This `PoolBuilder` instance.

public final Class PoolBuilder<T extends Poolable>

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail