Module stormpot
Package stormpot

Class PoolBuilder<T extends Poolable>

  • Type Parameters:
    T - The type of Poolable objects that a Pool based
    All Implemented Interfaces:
    java.lang.Cloneable
    public final class PoolBuilder<T extends Poolable>
extends java.lang.Object
implements java.lang.Cloneable

    The PoolBuilder collects information about how big a pool should be, and how it should allocate objects, an so on, and finally acts as the factory for building the pool instances themselves, with the build() method.

    Pool builder instances are obtained by calling one of the from* methods on Pool, such as Pool.fromThreaded(Allocator).

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

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

    Author:
    Chris Vest <mr.chrisvest@gmail.com>

    • Method Detail

      • setSize

        public 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 - The target pool size. Must be at least 0.
        Returns:
        This PoolBuilder instance.

      • getSize

        public int getSize()

        Get the currently configured size. The default is 10.

        Returns:
        The configured pool size.

      • setAllocator

        public <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.

        Type Parameters:
        X - The type of Poolable that is created by the allocator,
        Parameters:
        allocator - The allocator we want our pools to use. This cannot be null.
        Returns:
        This PoolBuilder instance, but with a generic type parameter that matches that of the allocator.

      • getAllocator

        public Allocator<T> getAllocator()

        Get the configured Allocator instance.

        Returns:
        The configured Allocator instance.

      • 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.

      • setExpiration

        public 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 - The expiration we want our pools to use. Not null.
        Returns:
        This PoolBuilder instance.

      • setMetricsRecorder

        public PoolBuilder<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 PoolBuilder instance.

      • getMetricsRecorder

        public MetricsRecorder getMetricsRecorder()

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

        Returns:
        The configured MetricsRecorder.

      • getThreadFactory

        public java.util.concurrent.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 PoolBuilder<T> setThreadFactory​(java.util.concurrent.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 PoolBuilder 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 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 - true to turn on precise object leak detection (the default) false to turn it off.
        Returns:
        This PoolBuilder instance.

      • isBackgroundExpirationEnabled

        public boolean isBackgroundExpirationEnabled()

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

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

      • setBackgroundExpirationEnabled

        public 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 - true (the default) to turn background expiration checking on, false to turn it off.
        Returns:
        This PoolBuilder instance.

      • getBackgroundExpirationCheckDelay

        public int getBackgroundExpirationCheckDelay()

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

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

      • setBackgroundExpirationCheckDelay

        public 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 - the desired delay, in milliseconds, between background maintenance tasks.
        Returns:
        This PoolBuilder instance.

      • clone

        public final PoolBuilder<T> clone()

        Returns a shallow copy of this PoolBuilder object.

        Overrides:
        clone in class java.lang.Object
        Returns:
        A new PoolBuilder object of the exact same type as this one, with identical values in all its fields.

      • build

        public Pool<T> build()

        Build a Pool instance based on the collected configuration.

        Returns:
        A Pool instance as configured by this builder.