Package stormpot

Stormpot

See: Description

Interface Summary

Interface	Description
Allocator<T extends Poolable>	An Allocator is responsible for the creation and destruction of Poolable objects.
Completion	A Completion represents some task that is going to be completed at some point in the future, or maybe already has completed.
Expiration<T extends Poolable>	The expiration is used to determine if a given slot has expired, or otherwise become invalid.
LifecycledPool<T extends Poolable>	A LifecycledPool is a Pool that can be shut down to release any internal resources it might be holding on to.
LifecycledResizablePool<T extends Poolable>	An interface for Pools that are both life-cycled and resizable.
ManagedPool	This is the JMX management interface for Stormpot object pools.
MetricsRecorder	A MetricsRecorder implementation supplies the pool with the ability to record and report operational metrics.
Pool<T extends Poolable>	A Pool is a self-renewable set of objects from which one can claim exclusive access to elements, until they are released back into the pool.
Poolable	Objects contained in a Pool must implement the Poolable interface and adhere to its contract.
Reallocator<T extends Poolable>	Reallocators are a special kind of Allocator that can reallocate Poolables that have expired.
ResizablePool<T extends Poolable>	ResizablePools are pools that can change their size after they have been created.
Slot	A Slot represents a location in a Pool where objects can be allocated into, so that they can be claimed and released.
SlotInfo<T extends Poolable>	An informative little interface, used by Expiration instances to determine if a slot has expired or is still invalid for claiming.

Class Summary

Class	Description
BlazePool<T extends Poolable>	BlazePool is a highly optimised LifecycledResizablePool implementation that consists of a queues of Poolable instances, the access to which is made faster with clever use of ThreadLocals.
CompoundExpiration<T extends Poolable>	Provides a way to compose Expirations.
Config<T extends Poolable>	The basic configuration "bean" class.
QueuePool<T extends Poolable>	QueuePool is a fairly simple LifecycledResizablePool implementation that basically consists of a queue of Poolable instances, and a Thread to allocate them.
TimeExpiration<T extends Poolable>	This is a time based Expiration.
Timeout	A Timeout represents the maximum amount of time a caller is willing to wait for a blocking operation to complete.
TimeSpreadExpiration<T extends Poolable>	This is the standard time based Expiration.

Exception Summary

Exception	Description
PoolException	The PoolException may be thrown by a pool implementation in a number of circumstances:

Package stormpot Description

Stormpot

Stormpot is a generic, thread-safe and fast object pooling library.

The object pools themselves implement the Pool interface, or one or both of the LifecycledPool or ResizablePool interfaces, or even the LifecycledResizablePool interface. The things you actually want to pool must all implement the Poolable interface, and you must also provide an implementation of the Allocator interface as a factory to create your pooled objects.

Simplest Possible Usage

Stormpot has an invasive API which means that there is a minimum of things your code needs to do to use it. However, the requirements are quite benign, as this section is all about showing you. The objects that you manage with a Stormpot pool needs to implement the Poolable interface. The absolute minimum amount of code required for its implementation is this:

// MyPoolable.java - minimum Poolable implementation
import stormpot.Poolable;
import stormpot.Slot;

public class MyPoolable implements Poolable {
  private final Slot slot;
  public MyPoolable(Slot slot) {
    this.slot = slot;
  }

  public void release() {
    slot.release(this);
  }
}

The object in essence just needs to keep its Slot instance around, and give itself as a parameter to the Slot#release method. Now that we have a class of objects to pool, we need some way to tell Stormpot how to create them. We do this by implementing the Allocator interface:

// MyAllocator.java - minimum Allocator implementation
import stormpot.Allocator;
import stormpot.Slot;

public class MyAllocator implements Allocator<MyPoolable> {
  public MyPoolable allocate(Slot slot) throws Exception {
    return new MyPoolable(slot);
  }

  public void deallocate(MyPoolable poolable) throws Exception {
    // Nothing to do here
    // But it's a perfect place to close sockets, files, etc.
  }
}

That’s it. Given a slot, create a MyPoolable. Or given a MyPoolable, deallocate it. And that is actually all the parts we need to start using Stormpot. All that is left is a little bit of configuration:

    MyAllocator allocator = new MyAllocator();
    Config<MyPoolable> config = new Config<MyPoolable>().setAllocator(allocator);
    Pool<MyPoolable> pool = new BlazePool<MyPoolable>(config);
    Timeout timeout = new Timeout(1, TimeUnit.SECONDS);

    MyPoolable object = pool.claim(timeout);
    try {
      // Do stuff with 'object'.
      // Note that 'claim' will return 'null' if it times out!
    } finally {
      if (object != null) {
        object.release();
      }
    }

Create a Config object and set the allocator, then create a pool with the configuration and off we go! The blocking methods Pool#claim and Completion#await both take Timeout objects as arguments. These are immutable, and can easily be put in static final constants. Note that claim returns null if the timeout elapses before an object can be claimed. Also, using try-finally is a great way to make sure that you don’t forget to release the objects back into the pool. Stormpot cannot prevent objects from leaking in user code, so if you lose the reference to an object that hasn’t been released back into the pool, it will not come back on its own. Leaked objects can also cause problems with shutting the pool down, because the shut down procedure does not complete until all allocated objects are deallocated. So if you have leaked objects, shutting the pool down will never complete normally. You can still just halt the JVM, though.