Module stormpot

Package stormpot

Interface Poolable

All Known Implementing Classes:

BasePoolable, Pooled

public interface Poolable

Objects contained in a Pool must implement the Poolable interface and adhere to its contract.

Pools call allocate on Allocators with the specific Slot that they want a Poolable allocated for. The Slot represents a location in the pool, that can fit an object and make it available for others to claim.

The contract of the Poolable interface is, that when release() is called on the Poolable, it must in turn call Slot.release(Poolable) on the specific Slot object that it was allocated with, giving itself as the Poolable parameter.

A simple correct implementation of the Poolable interface looks like this:

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

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

This can be shortened further by extending the BasePoolable class:

  public class CustomPoolable extends BasePoolable {
    public CustomPoolable(Slot slot) {
      super(slot);
    }
  }

It is also possible to directly use the Pooled implementation, which implements both Poolable and AutoCloseable, and holds a reference to the actual object being pooled.

Memory effects: The release of an object happens-before it is claimed by another thread, or deallocated.

Author:

Chris Vest <mr.chrisvest@gmail.com>

See Also:

BasePoolable, Pooled

Method Summary

Modifier and Type	Method	Description
void	release()	Release this Poolable object back into the pool from where it came, so that others can claim it, or the pool deallocate it if it has expired.

Method Detail

release

void release()

Release this Poolable object back into the pool from where it came, so that others can claim it, or the pool deallocate it if it has expired.

A call to this method MUST delegate to a call to Slot.release(Poolable) on the Slot object for which this Poolable was allocated, giving itself as the Poolable parameter.

A Poolable can be released by a thread other than the one that claimed it. It can not, however, be released more than once per claim. The feature of permitting releases from threads other than the claiming thread might be useful in message-passing architectures and the like, but it is not generally recommendable because it makes it more complicated to keep track of object life-cycles.

Great care must be taken, to ensure that Poolables are not used after they are released!