stormpot

Interface Slot

public interface Slot

A Slot represents a location in a Pool where objects can be allocated into, so that they can be claimed and released. The Slot is used by the allocated Poolables as a call-back, to tell the pool when an object is released.

The individual pool implementations provide their own Slot implementations.

Slots contain mutable state within them. If objects are claimed, released and otherwise worked on from different threads, then the hand-over must happen through a safe publication mechanism.

See Java Concurrency in Practice by Brian Goetz for more information on safe publication.

Slots also expects single-threaded access, so they cannot be used concurrently by multiple threads. Only one thread at a time can use a Slot instance.

Author:

Chris Vest <mr.chrisvest@gmail.com>

See Also:

Poolable

Method Summary

Methods

Modifier and Type	Method and Description
void	expire(Poolable obj) Mark the object represented by this slot as expired.
void	release(Poolable obj) Signal to the pool that the currently claimed object in this slot has been released.

Method Detail

release

void release(Poolable obj)

Signal to the pool that the currently claimed object in this slot has been released.

It is a user error to release a slot that is not currently claimed. It is likewise a user error to release a Slot while inside the Allocators allocate method, or the Expirations hasExpired method.

On the other hand, it is not an error to release a Poolable from a thread other than the one that claimed it.

Pools are free to throw a PoolException if they detect any of these wrong uses, but it is not guaranteed and the exact behaviour is not specified. "Unspecified behaviour" means that dead-locks and infinite loops are fair responses as well. Therefore, heed the advice and don’t misuse release!

Pools must, however, guarantee that an object is never deallocated more than once. This guarantee must hold even if release is misused.

Parameters:

obj - A reference to the Poolable object that is allocated for this slot, and is being released.

expire

void expire(Poolable obj)

Mark the object represented by this slot as expired. Expired objects cannot be claimed again, and will be deallocated by the pool at the earliest convenience. Objects are normally expired automatically using the Expiration policy that the pool has been configured with. If an object through its use is found to be unusable, then it can be explicitly expired using this method. Objects can only be explicitly expired while they are claimed, and such expired objects will not be deallocated until they are released back to the pool.

It is a user error to expire objects that are not currently claimed. It is likewise a user error to expire a Slot while inside the Allocators allocate method.

The expiration only takes effect after the object has been released, so calling this method from within the Expirations hasExpired method will not prevent the object from being claimed, but will prevent it from being claimed again after it’s been released back to the pool. An Expiration policy that expires all objects with this method, is effectively allowed objects to only be claimed once.

Pools are free to throw a PoolException if they detect any wrong uses, but it is not guaranteed and the exact behaviour is not specified. "Unspecified behaviour" means that dead-locks and infinite loops are fair responses as well. Therefore, heed the advice and don’t misuse expire!

Pools must, however, guarantee that an object is never deallocated more than once. This guarantee must hold even if expire is misused.

Parameters:

obj - A reference to the Poolable object that is allocated for this slot, and is being expired.