Module stormpot
Package stormpot

Interface PoolBuilder<T extends Poolable>

Type Parameters:
T - The type of Poolable objects that a Pool based on this PoolBuilder will produce.
All Superinterfaces:
Cloneable
All Known Implementing Classes:
PoolBuilderImpl
public sealed interface PoolBuilder<T extends Poolable> extends Cloneable permits PoolBuilderImpl<T>
The PoolBuilder collects information about how big a pool should be, and how it should allocate objects, and 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

  • Method Details

    • setSize

      PoolBuilder<T> setSize(long 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 zero, 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(long) or ManagedPool.setTargetSize(long) methods.

      Parameters:
      size - The target pool size. Must be at least 0.
      Returns:
      This PoolBuilder instance.

    • getSize

      long getSize()
      Get the currently configured size. The default is 10.
      Returns:
      The configured pool size.

    • setAllocator

      <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, and the type of objects that the configured pools will contain.
      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

      Allocator<T> getAllocator()
      Get the configured Allocator instance.
      Returns:
      The configured Allocator instance.

    • getReallocator

      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

      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 from 8 to 10 minutes.

      Parameters:
      expiration - The expiration we want our pools to use. Not null.
      Returns:
      This PoolBuilder instance.

    • getExpiration

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

    • setMetricsRecorder

      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

      MetricsRecorder getMetricsRecorder()
      Get the configured MetricsRecorder instance, or null if none has been configured.
      Returns:
      The configured MetricsRecorder.

    • getThreadFactory

      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

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

    • isPreciseLeakDetectionEnabled

      boolean isPreciseLeakDetectionEnabled()
      Return whether precise object leak detection is enabled, which is the case by default.
      Returns:
      true if precise object leak detection is enabled.
      See Also:

    • setPreciseLeakDetectionEnabled

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

      boolean isBackgroundExpirationEnabled()
      Return whether background expiration is enabled. By default, background expiration is enabled.
      Returns:
      true if background expiration is enabled.
      See Also:

    • setBackgroundExpirationEnabled

      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

      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

      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.

    • isOptimizeForReducedMemoryUsage

      boolean isOptimizeForReducedMemoryUsage()
      Return whether Stormpot will prioritize minimizing its memory overhead over maximizing performance.

      This is true by default, as the performance gains don't show except in intense and highly concurrent use cases.

      Returns:
      true for prioritizing memory usage over absolute performance, otherwise false for prioritizing performance at all costs.

    • setOptimizeForReducedMemoryUsage

      PoolBuilder<T> setOptimizeForReducedMemoryUsage(boolean reduceMemoryUsage)
      Tell the pool to optimize for either low memory usage (when giving true), or maximal performance (when giving false).

      This is true by default, and should only be set to false when the pool is expected to be "relatively small" and will experience an extremely high level of multithreaded access.

      Parameters:
      reduceMemoryUsage - whether to prioritize memory usage or performance.
      Returns:
      This PoolBuilder instance.

    • clone

      PoolBuilder<T> clone()
      Returns a shallow copy of this PoolBuilder object.
      Returns:
      A new PoolBuilder object of the exact same type as this one, with identical values in all its fields.

    • build

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