Module jtrim.concurrent
Package org.jtrim2.cancel

Class CancelableWaits

java.lang.Object
org.jtrim2.cancel.CancelableWaits
public final class CancelableWaits extends Object
Defines static helper methods to wait for a cancellation request instead of thread interruption.

Java usually employs thread interruption for canceling methods waiting for a particular event. Since relying on thread interruption is error prone and inconvenient to use, the JTrim library uses CancellationToken to detect that an operation has been canceled. This library contains methods to convert methods which can be canceled by thread interruption to a method call which can be canceled using a CancellationToken.

The order of the arguments of these methods are always as follows:

  1. The CancellationToken.
  2. Optionally a timeout value and its TimeUnit specifying the maximum time to wait.
  3. The object whose "await" method is to be called to wait for a particular event. The method of the object might not actually be called "await". Every method states in its documentation which method it actually calls.

The two general purpose method is which takes an InterruptibleWait as their last argument and this InterruptibleWait must actually be implemented to wait for the desired condition.

The methods of this class do add some additional performance overhead to the wait so it is advised to first check the condition to be waited for before actually calling a method of this class.

Warning: Every methods in this class will clear the interrupted status of the task before they throw a OperationCanceledException. If they return normally, they will leave the interrupted status of thread as it was.

Thread safety

Every method of this class can be called from multiple threads concurrently.

Synchronization transparency

Every method of this class has the same synchronization transparency property as the "await" method of the object passed to them.
See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    static boolean
    await(CancellationToken cancelToken, long timeout, TimeUnit timeUnit, Condition condition)
    Calls condition.await(long, TimeUnit) with the specified timeout value and waits until it returns or the specified CancellationToken signals that the waiting must be canceled.
    static boolean
    await(CancellationToken cancelToken, long timeout, TimeUnit timeUnit, InterruptibleLimitedWait wait)
    Calls wait.await with the specified timeout value and waits until it returns or the specified CancellationToken signals that the waiting must be canceled.
    static void
    await(CancellationToken cancelToken, Condition condition)
    Calls condition.await() and waits until it returns or the specified CancellationToken signals that the waiting must be canceled.
    static void
    await(CancellationToken cancelToken, InterruptibleWait wait)
    Waits until wait.await returns or the specified CancellationToken signals that the waiting must be canceled.
    static boolean
    awaitTerminate(CancellationToken cancelToken, long timeout, TimeUnit timeUnit, ExecutorService executor)
    Calls executor.awaitTermination(long, TimeUnit) with the specified timeout value and waits until it returns or the specified CancellationToken signals that the waiting must be canceled.
    static void
    lock(CancellationToken cancelToken, Lock lock)
    Calls lock.lockInterruptibly() and waits until it returns or the specified CancellationToken signals that the waiting must be canceled.
    static void
    sleep(CancellationToken cancelToken, long time, TimeUnit timeUnit)
    Causes the current thread to sleep until the given time elapses or the specified CancellationToken signals a cancellation request.
    static boolean
    tryLock(CancellationToken cancelToken, long timeout, TimeUnit timeUnit, Lock lock)
    Calls lock.tryLock(long, TimeUnit) with the specified timeout value and waits until it returns or the specified CancellationToken signals that the waiting must be canceled.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Method Details

    • lock

      public static void lock(CancellationToken cancelToken, Lock lock)
      Calls lock.lockInterruptibly() and waits until it returns or the specified CancellationToken signals that the waiting must be canceled. That is, if lock.lockInterruptibly() throws an InterruptedException, the lock.lockInterruptibly() method will be called again.

      Whenever the specified CancellationToken signals a cancellation request, the ongoing lock.lockInterruptibly() call will be interrupted using thread interruption. The lock.lockInterruptibly() call must return by throwing an InterruptedException so that this method may clear the interrupted status of the current thread and return by throwing a OperationCanceledException.

      Note that thread interruption may occur due to reasons uncontrolled by this method, so lock.lockInterruptibly() calls may be interrupted spuriously. In such spurious interrupt will the lock.lockInterruptibly() method be called again.

      Parameters:
      cancelToken - the CancellationToken which is to be checked if this operation must be canceled and a OperationCanceledException should be thrown. This argument cannot be null.
      lock - the Lock object whose lockInterruptibly() method is to be invoked. This argument cannot be null.
      Throws:
      NullPointerException - thrown if any of the arguments is null
      OperationCanceledException - thrown if the specified CancellationToken signals a cancellation request before lock.lockInterruptibly() returns

    • tryLock

      public static boolean tryLock(CancellationToken cancelToken, long timeout, TimeUnit timeUnit, Lock lock)
      Calls lock.tryLock(long, TimeUnit) with the specified timeout value and waits until it returns or the specified CancellationToken signals that the waiting must be canceled. That is, if lock.tryLock(long, TimeUnit) throws an InterruptedException, the lock.tryLock(long, TimeUnit) method will be called again with an appropriately lowered timeout value.

      Whenever the specified CancellationToken signals a cancellation request, the ongoing lock.tryLock(long, TimeUnit) call will be interrupted using thread interruption. The lock.tryLock(long, TimeUnit) call must return by throwing an InterruptedException so that this method may clear the interrupted status of the current thread and return by throwing a OperationCanceledException.

      Note that thread interruption may occur due to reasons uncontrolled by this method, so lock.tryLock(long, TimeUnit) calls may be interrupted spuriously. In such spurious interrupt will the lock.tryLock(long, TimeUnit) method be called again.

      Parameters:
      cancelToken - the CancellationToken which is to be checked if this operation must be canceled and a OperationCanceledException should be thrown. This argument cannot be null.
      timeout - the maximum time to wait in the given time unit. After this time elapses, this method returns by throwing a OperationCanceledException. This argument must be greater than or equal to zero.
      timeUnit - the time unit of the timeout argument. This argument cannot be null.
      lock - the Lock object whose tryLock(long, TimeUnit) method is to be invoked. This argument cannot be null.
      Returns:
      the return value of the lock.tryLock(long, TimeUnit) method call. The return value of false means that the lock was not acquired.
      Throws:
      NullPointerException - thrown if any of the arguments is null
      IllegalArgumentException - thrown if the specified timeout value is lower than zero
      OperationCanceledException - thrown if the specified CancellationToken signals a cancellation request before lock.tryLock(long, TimeUnit) returns

    • sleep

      public static void sleep(CancellationToken cancelToken, long time, TimeUnit timeUnit)
      Causes the current thread to sleep until the given time elapses or the specified CancellationToken signals a cancellation request. If the specified time elapses, this method returns by throwing a OperationCanceledException.
      Parameters:
      cancelToken - the CancellationToken which is to be checked if this sleep must be canceled and a OperationCanceledException should be thrown. This argument cannot be null.
      time - the time to wait in the given time unit. This argument must be greater than or equal to zero.
      timeUnit - the time unit of the time argument. This argument cannot be null.
      Throws:
      NullPointerException - thrown if any of the arguments is null
      IllegalArgumentException - thrown if the specified time is lower than zero
      OperationCanceledException - thrown if the specified CancellationToken signals a cancellation request before the specified time elapses

    • awaitTerminate

      public static boolean awaitTerminate(CancellationToken cancelToken, long timeout, TimeUnit timeUnit, ExecutorService executor)
      Calls executor.awaitTermination(long, TimeUnit) with the specified timeout value and waits until it returns or the specified CancellationToken signals that the waiting must be canceled. That is, if executor.awaitTermination(long, TimeUnit) throws an InterruptedException, the executor.awaitTermination(long, TimeUnit) method will be called again with an appropriately lowered timeout value.

      Whenever the specified CancellationToken signals a cancellation request, the ongoing executor.awaitTermination(long, TimeUnit) call will be interrupted using thread interruption. The executor.awaitTermination(long, TimeUnit) call must return by throwing an InterruptedException so that this method may clear the interrupted status of the current thread and return by throwing a OperationCanceledException.

      Note that thread interruption may occur due to reasons uncontrolled by this method, so executor.awaitTermination(long, TimeUnit) calls may be interrupted spuriously. In such spurious interrupt will the executor.awaitTermination(long, TimeUnit) method be called again.

      Parameters:
      cancelToken - the CancellationToken which is to be checked if this operation must be canceled and a OperationCanceledException should be thrown. This argument cannot be null.
      timeout - the maximum time to wait in the given time unit. After this time elapses, this method returns by throwing a OperationCanceledException. This argument must be greater than or equal to zero.
      timeUnit - the time unit of the timeout argument. This argument cannot be null.
      executor - the ExecutorService object whose awaitTermination(long, TimeUnit) method is to be invoked. This argument cannot be null.
      Returns:
      the return value of the executor.awaitTermination(long, TimeUnit) method call. The return value of false means that the timeout elapsed without the executor terminating.
      Throws:
      NullPointerException - thrown if any of the arguments is null
      IllegalArgumentException - thrown if the specified timeout value is lower than zero
      OperationCanceledException - thrown if the specified CancellationToken signals a cancellation request before executor.awaitTermination(long, TimeUnit) returns

    • await

      public static boolean await(CancellationToken cancelToken, long timeout, TimeUnit timeUnit, Condition condition)
      Calls condition.await(long, TimeUnit) with the specified timeout value and waits until it returns or the specified CancellationToken signals that the waiting must be canceled. That is, if condition.await(long, TimeUnit) throws an InterruptedException, the condition.await(long, TimeUnit) method will be called again with an appropriately lowered timeout value.

      Whenever the specified CancellationToken signals a cancellation request, the ongoing condition.await(long, TimeUnit) call will be interrupted using thread interruption. The condition.await(long, TimeUnit) call must return by throwing an InterruptedException so that this method may clear the interrupted status of the current thread and return by throwing a OperationCanceledException.

      Note that thread interruption may occur due to reasons uncontrolled by this method, so condition.await(long, TimeUnit) calls may be interrupted spuriously. In such spurious interrupt will the condition.await(long, TimeUnit) method be called again.

      Parameters:
      cancelToken - the CancellationToken which is to be checked if this operation must be canceled and a OperationCanceledException should be thrown. This argument cannot be null.
      timeout - the maximum time to wait in the given time unit. After this time elapses, this method returns by throwing a OperationCanceledException. This argument must be greater than or equal to zero.
      timeUnit - the time unit of the timeout argument. This argument cannot be null.
      condition - the Condition object whose await(long, TimeUnit) method is to be invoked. This argument cannot be null.
      Returns:
      the return value of the condition.await(long, TimeUnit) method call. The return value of false means that the timeout elapsed without actually receiving the signal.
      Throws:
      NullPointerException - thrown if any of the arguments is null
      IllegalArgumentException - thrown if the specified timeout value is lower than zero
      OperationCanceledException - thrown if the specified CancellationToken signals a cancellation request before condition.await(long, TimeUnit) returns

    • await

      public static void await(CancellationToken cancelToken, Condition condition)
      Calls condition.await() and waits until it returns or the specified CancellationToken signals that the waiting must be canceled. That is, if condition.await() throws an InterruptedException, the condition.await() method will be called again.

      Whenever the specified CancellationToken signals a cancellation request, the ongoing condition.await() call will be interrupted using thread interruption. The condition.await() call must return by throwing an InterruptedException so that this method may clear the interrupted status of the current thread and return by throwing a OperationCanceledException.

      Note that thread interruption may occur due to reasons uncontrolled by this method, so condition.await() calls may be interrupted spuriously. In such spurious interrupt will the condition.await() method be called again.

      Warning: Note that the condition.await() method may return spuriously. That is, without any reason (as documented in its apidoc).

      Parameters:
      cancelToken - the CancellationToken which is to be checked if this operation must be canceled and a OperationCanceledException should be thrown. This argument cannot be null.
      condition - the Condition object whose await() method is to be invoked. This argument cannot be null.
      Throws:
      NullPointerException - thrown if any of the arguments is null
      OperationCanceledException - thrown if the specified CancellationToken signals a cancellation request before condition.await()returns

    • await

      public static boolean await(CancellationToken cancelToken, long timeout, TimeUnit timeUnit, InterruptibleLimitedWait wait)
      Calls wait.await with the specified timeout value and waits until it returns or the specified CancellationToken signals that the waiting must be canceled. That is, if wait.await throws an InterruptedException, the wait.await method will be called again with an appropriately lowered timeout value.

      Whenever the specified CancellationToken signals a cancellation request, the ongoing wait.await call will be interrupted using thread interruption. The wait.await call must return by throwing an InterruptedException so that this method may clear the interrupted status of the current thread and return by throwing a OperationCanceledException.

      Note that thread interruption may occur due to reasons uncontrolled by this method, so wait.await calls may be interrupted spuriously. In such spurious interrupt will the wait.await method be called again.

      This is a general purpose method for converting cancellation by thread interruption to cancellation by a CancellationToken and waiting for only a limited amount of time.

      Parameters:
      cancelToken - the CancellationToken which is to be checked if this operation must be canceled and a OperationCanceledException should be thrown. This argument cannot be null.
      timeout - the maximum time to wait in the given time unit. After this time elapses, this method returns by throwing a OperationCanceledException. This argument must be greater than or equal to zero.
      timeUnit - the time unit of the timeout argument. This argument cannot be null.
      wait - the InterruptibleWait object whose await method is to be called to wait for a particular event. This argument cannot be null.
      Returns:
      the return value of the wait.await method call. Usually a return value of false means that the timeout elapsed without the event to be waited for actually occurred.
      Throws:
      NullPointerException - thrown if any of the arguments is null
      IllegalArgumentException - thrown if the specified timeout value is lower than zero
      OperationCanceledException - thrown if the specified CancellationToken signals a cancellation request before wait.await returns

    • await

      public static void await(CancellationToken cancelToken, InterruptibleWait wait)
      Waits until wait.await returns or the specified CancellationToken signals that the waiting must be canceled. That is, if wait.await throws an InterruptedException, the wait.await method will be called again.

      Whenever the specified CancellationToken signals a cancellation request, the ongoing wait.await call will be interrupted using thread interruption. The wait.await call must return by throwing an InterruptedException so that this method may clear the interrupted status of the current thread and return by throwing a OperationCanceledException.

      Note that thread interruption may occur due to reasons uncontrolled by this method, so wait.await calls may be interrupted spuriously. In such spurious interrupt will the wait.await method be called again.

      This is a general purpose method for converting cancellation by thread interruption to cancellation by a CancellationToken.

      Parameters:
      cancelToken - the CancellationToken which is to be checked if this operation must be canceled and a OperationCanceledException should be thrown. This argument cannot be null.
      wait - the InterruptibleWait object whose await method is to be called to wait for a particular event. This argument cannot be null.
      Throws:
      NullPointerException - thrown if any of the arguments is null
      OperationCanceledException - thrown if the specified CancellationToken signals a cancellation request before wait.await returns