| public T claim(Timeout timeout) throws PoolException, InterruptedException Implements abstract stormpot.PoolTap.claim.
Doc from stormpot.PoolTap.claim.
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.
- Annotations
- @Override
- 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.
|
