stormpot 3.1 · stormpot.PoolTap

Access	Constructor and Description
pack-priv	PoolTap()

Method Summary

Modifier and Type	Method and Description
public final < The return type of the given function. R> Optional<R>	Returns: an `Optional` of either the return value of applying the given function to a claimed object, or empty if the timeout elapsed or the function returned `null`. apply(Timeout The timeout of the maximum permitted amount of time to wait for an object to become available. A timeout with a value of zero or less means that the call will do no waiting, preferring instead to return early if no objects are available. timeout, Function<T, R> The function to apply to the claimed object, if any. The function should avoid further claims, since having more than one object claimed at a time per thread is inherently deadlock prone. function) Claim an object from the pool and apply the given function to it, returning the result and releasing the object back to the pool.
public abstract T	Returns: An object of the Poolable subtype T to which the exclusive rights have been claimed, or `null` if the timeout period elapsed before an object became available. claim(Timeout The timeout of the maximum permitted time-slice to wait for an object to become available. A timeout with a value of zero or less means that the call will do no waiting, preferring instead to return early if no objects are available. timeout) Claim the exclusive rights until released, to an object in the pool.
public final boolean	Returns: `true` if an object could be claimed within the given timeout and passed to the given consumer, or `false` otherwise. supply(Timeout The timeout of the maximum permitted amount of time to wait for an object to become available. A timeout with a value of zero or less means that the call will do no waiting, preferring instead to return early if no objects are available. timeout, Consumer<T> The consumer to pass the claimed object to, if any. The consumer should avoid further claims, since having more than one object claimed at a time per thread is inherently deadlock prone. consumer) Claim an object from the pool and supply it to the given consumer, and then release it back to the pool.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

PoolTap	back to summary
pack-priv PoolTap()

Method Detail

apply back to summary

apply	back to summary
public final <R> Optional<R> apply(Timeout timeout, Function<T, R> function) throws InterruptedException Claim an object from the pool and apply the given function to it, returning the result and releasing the object back to the pool. If an object cannot be claimed within the given timeout, then `Optional#empty()` is returned instead. The `empty()` value is also returned if the function returns `null`. Parameters <R> The return type of the given function. timeout:Timeout The timeout of the maximum permitted amount of time to wait for an object to become available. A timeout with a value of zero or less means that the call will do no waiting, preferring instead to return early if no objects are available. function:Function<T, R> The function to apply to the claimed object, if any. The function should avoid further claims, since having more than one object claimed at a time per thread is inherently deadlock prone. Returns:Optional<R> an `Optional` of either the return value of applying the given function to a claimed object, or empty if the timeout elapsed or the function returned `null`. Exceptions InterruptedException: if the thread was interrupted. See Also The `claim` method for more details on failure modes and memory effects.

public final <R> Optional<R> apply(Timeout timeout, Function<T, R> function) throws InterruptedException

Claim an object from the pool and apply the given function to it, returning the result and releasing the object back to the pool. If an object cannot be claimed within the given timeout, then Optional#empty() is returned instead. The `empty()` value is also returned if the function returns `null`.

Parameters

<R>: The return type of the given function.
timeout:Timeout: The timeout of the maximum permitted amount of time to wait for an object to become available. A timeout with a value of zero or less means that the call will do no waiting, preferring instead to return early if no objects are available.
function:Function<T, R>: The function to apply to the claimed object, if any. The function should avoid further claims, since having more than one object claimed at a time per thread is inherently deadlock prone.

Returns:Optional<R>

an Optional of either the return value of applying the given function to a claimed object, or empty if the timeout elapsed or the function returned `null`.

Exceptions

InterruptedException:: if the thread was interrupted.

claim back to summary

claim	back to summary
public abstract T claim(Timeout timeout) throws PoolException, InterruptedException Claim the exclusive rights until released, to an object in the pool. Possibly waiting up to the specified amount of time, as given by the provided `Timeout` instance, for one to become available if the pool has been depleted. If the timeout elapses before an object can be claimed, then `null` is returned instead. The timeout will be honoured even if the Allocators `allocate` methods blocks forever. If the given timeout has a zero or negative value, then the method will not wait. If the current thread has already one or more objects currently claimed, then a distinct object will be returned, if one is or becomes available. This means that it is possible for a single thread to deplete the pool, if it so desires. However, doing so is inherently deadlock prone, so avoid claiming more than one object at a time per thread, if at all possible. This method may throw a PoolException if the pool have trouble allocating objects. That is, if its assigned Allocator throws exceptions from its allocate method, or returns `null`. An `InterruptedException` will be thrown if the thread has its interrupted flag set upon entry to this method, or is interrupted while waiting. The interrupted flag on the thread will be cleared after this, as per the general contract of interruptible methods. If the pool has been shut down, then an `IllegalStateException` will be thrown when this method is called. Likewise if we are waiting for an object to become available, and someone shuts the pool down. Here's an example code snippet, where an object is claimed, printed to `System.out`, and then released back to the pool: [source,java] ---- include::../src/test/java/examples/Examples.java[tag=poolClaimPrintExample] ---- Memory effects: * The `release` of an object happens-before any subsequent claim or `deallocation` of that object, and, * The `allocation` of an object happens-before any claim of that object. Parameters timeout:Timeout The timeout of the maximum permitted time-slice to wait for an object to become available. A timeout with a value of zero or less means that the call will do no waiting, preferring instead to return early if no objects are available. Returns:T An object of the Poolable subtype T to which the exclusive rights have been claimed, or `null` if the timeout period elapsed before an object became available. Exceptions PoolException: If an object allocation failed because the Allocator threw an exception from its allocate method, or returned `null`, or the `expiration check` threw an exception. InterruptedException: if the current thread is `interrupted` upon entry, or becomes interrupted while waiting. IllegalArgumentException: if the `timeout` argument is `null`.

public abstract T claim(Timeout timeout) throws PoolException, InterruptedException

Claim the exclusive rights until released, to an object in the pool. Possibly waiting up to the specified amount of time, as given by the provided Timeout instance, for one to become available if the pool has been depleted. If the timeout elapses before an object can be claimed, then `null` is returned instead. The timeout will be honoured even if the Allocators allocate methods blocks forever. If the given timeout has a zero or negative value, then the method will not wait. If the current thread has already one or more objects currently claimed, then a distinct object will be returned, if one is or becomes available. This means that it is possible for a single thread to deplete the pool, if it so desires. However, doing so is inherently deadlock prone, so avoid claiming more than one object at a time per thread, if at all possible. This method may throw a PoolException if the pool have trouble allocating objects. That is, if its assigned Allocator throws exceptions from its allocate method, or returns `null`. An InterruptedException will be thrown if the thread has its interrupted flag set upon entry to this method, or is interrupted while waiting. The interrupted flag on the thread will be cleared after this, as per the general contract of interruptible methods. If the pool has been shut down, then an IllegalStateException will be thrown when this method is called. Likewise if we are waiting for an object to become available, and someone shuts the pool down. Here's an example code snippet, where an object is claimed, printed to `System.out`, and then released back to the pool: [source,java] ---- include::../src/test/java/examples/Examples.java[tag=poolClaimPrintExample] ---- Memory effects: * The release of an object happens-before any subsequent claim or deallocation of that object, and, * The allocation of an object happens-before any claim of that object.

Parameters

timeout:Timeout: The timeout of the maximum permitted time-slice to wait for an object to become available. A timeout with a value of zero or less means that the call will do no waiting, preferring instead to return early if no objects are available.

Returns:T

An object of the Poolable subtype T to which the exclusive rights have been claimed, or `null` if the timeout period elapsed before an object became available.

Exceptions

PoolException:: If an object allocation failed because the Allocator threw an exception from its allocate method, or returned `null`, or the expiration check threw an exception.
InterruptedException:: if the current thread is interrupted upon entry, or becomes interrupted while waiting.
IllegalArgumentException:: if the `timeout` argument is `null`.

supply back to summary

supply	back to summary
public final boolean supply(Timeout timeout, Consumer<T> consumer) throws InterruptedException Claim an object from the pool and supply it to the given consumer, and then release it back to the pool. If an object cannot be claimed within the given timeout, then this method returns `false`. Otherwise, if an object was claimed and supplied to the consumer, the method returns `true`. Parameters timeout:Timeout The timeout of the maximum permitted amount of time to wait for an object to become available. A timeout with a value of zero or less means that the call will do no waiting, preferring instead to return early if no objects are available. consumer:Consumer<T> The consumer to pass the claimed object to, if any. The consumer should avoid further claims, since having more than one object claimed at a time per thread is inherently deadlock prone. Returns:boolean `true` if an object could be claimed within the given timeout and passed to the given consumer, or `false` otherwise. Exceptions InterruptedException: if the thread was interrupted. See Also The `claim` method for more details on failure modes and memory effects.

public final boolean supply(Timeout timeout, Consumer<T> consumer) throws InterruptedException

Claim an object from the pool and supply it to the given consumer, and then release it back to the pool. If an object cannot be claimed within the given timeout, then this method returns `false`. Otherwise, if an object was claimed and supplied to the consumer, the method returns `true`.

Parameters

timeout:Timeout: The timeout of the maximum permitted amount of time to wait for an object to become available. A timeout with a value of zero or less means that the call will do no waiting, preferring instead to return early if no objects are available.
consumer:Consumer<T>: The consumer to pass the claimed object to, if any. The consumer should avoid further claims, since having more than one object claimed at a time per thread is inherently deadlock prone.

Returns:boolean

`true` if an object could be claimed within the given timeout and passed to the given consumer, or `false` otherwise.

Exceptions

InterruptedException:: if the thread was interrupted.

public abstract Class PoolTap<T extends Poolable>

Constructor Summary

Method Summary

Constructor Detail

Method Detail