Module jtrim.concurrent
Package org.jtrim2.cancel

Class Cancellation

java.lang.Object
org.jtrim2.cancel.Cancellation
public final class Cancellation extends Object
Contains static helper methods and fields related cancellation.

  • Field Details

    • UNCANCELABLE_TOKEN

      public static final CancellationToken UNCANCELABLE_TOKEN
      A CancellationToken which can never be in the canceled state. The isCanceled method of UNCANCELABLE_TOKEN will always return false when checked. If a listener is registered with this token to be notified of cancellation requests, this CancellationToken will do nothing but return an already unregistered ListenerRef.

    • CANCELED_TOKEN

      public static final CancellationToken CANCELED_TOKEN
      A CancellationToken which is already in the canceled state. The isCanceled method of UNCANCELABLE_TOKEN will always return true when checked. If a listener is registered with this token to be notified of cancellation requests, this CancellationToken will immediately notify the listener and return an already unregistered ListenerRef.

      If you need a CancellationController as well, use the DO_NOTHING_CONTROLLER.

      See Also:

    • DO_NOTHING_CONTROLLER

      public static final CancellationController DO_NOTHING_CONTROLLER
      A CancellationController which does nothing when calling cancel.

      This CancellationController is good for tasks, cannot be canceled or tasks already canceled.

      See Also:

  • Method Details

    • createCancellationSource

      public static CancellationSource createCancellationSource()
      Creates a new CancellationSource whose CancellationToken is not yet in the canceled state. The only possible way to make the CancellationToken of the returned CancellationSource signal cancellation request is to cancel the CancellationController of the returned CancellationSource.
      Returns:
      a new CancellationSource whose CancellationToken is not yet in the canceled state. This method never returns null.

    • createChildCancellationSource

      public static CancellationSource createChildCancellationSource(CancellationToken cancelToken)
      Creates a new CancellationSource which will be notified of the cancellation requests of the specified CancellationToken. That is, if the CancellationToken specified in the argument is canceled, the returned CancellationToken will be canceled as well. Of course, the returned CancellationSource can also be canceled by its own CancellationController
      Parameters:
      cancelToken - the CancellationToken, which when canceled, will cause the returned CancellationSource to be canceled. This argument cannot be null.
      Returns:
      the new ChildCancellationSource which will be notified of the cancellation requests of the specified CancellationToken. This method never returns null.
      Throws:
      NullPointerException - thrown if the specified argument is null

    • anyToken

      public static CancellationToken anyToken(CancellationToken... tokens)
      Returns a CancellationToken which signals cancellation if and only if at least one of the specified tokens are in canceled state.

      If you do not specify any tokens, the returned token will never be in the canceled state.

      Parameters:
      tokens - the array of CancellationToken checked for cancellation. This array might be empty but cannot contain null elements.
      Returns:
      the CancellationToken which signals cancellation if and only if at least one of the specified tokens is in canceled state. This method never returns null.

    • allTokens

      public static CancellationToken allTokens(CancellationToken... tokens)
      Returns a CancellationToken which signals cancellation if and only if all of the specified tokens are in canceled state.

      If you do not specify any tokens, the returned token will always be in the canceled state.

      Parameters:
      tokens - the array of CancellationToken checked for cancellation. This array might be empty but cannot contain null elements.
      Returns:
      the CancellationToken which signals cancellation if and only if all of the specified tokens is in canceled state. This method never returns null.

    • listenForCancellation

      public static WaitableListenerRef listenForCancellation(CancellationToken cancelToken, Runnable listener)
      Adds a cancellation listener to the specified CancellationToken and returns reference which can be used to remove the listener and wait until it has been removed.

      Warning: It is forbidden to call any of the close methods from within the added listener. Attempting to do so will result in an IllegalStateException to be thrown by the close method.

      Calling the unregisterAndWait method of the returned reference ensures the following:

      • After the unregisterAndWait methods returns normally (without throwing an exception), the listener is guaranteed not to be executed anymore.
      • Calling the unregisterAndWait method (with valid argument) ensures that the added listener will be unregistered. This is true even if the unregisterAndWait method gets canceled.
      • If the passed listener is synchronization transparent, then the unregisterAndWait method is synchronization transparent as well.
      Here is an example usage: 
      
 CancellationToken cancelToken = ...;
 WaitableListenerRef ref = listenerForCancellation(cancelToken, () -> {
   System.out.println("CANCELED")
 });
 try {
   // ...
 } finally {
   ref.unregisterAndWait(Cancellation.UNCANCELABLE_TOKEN);
 }
 // When execution reaches this line, it is ensured that if "CANCELED"
 // has not been printed yet, it will never be printed.
      Parameters:
      cancelToken - the CancellationToken to which the listener is to be added. That is, the listener is registered to be notified of the cancellation requests of this token. This argument cannot be null.
      listener - the listener whose run method is to be passed as a cancellation listener to the specified CancellationToken. This argument cannot be null.
      Returns:
      a CancelableCloseable whose close methods can be used to unregister the added listener and wait until it can be ensured that the listener will never be executed. This method never returns null.
      Throws:
      NullPointerException - thrown if any of the arguments is null

    • doAsCancelable

      public static <ResultType> ResultType doAsCancelable(CancellationToken cancelToken, InterruptibleTask<ResultType> task)
      Executes the specified task on the current thread synchronously and interrupts the current thread if the specified CancellationToken signals a cancellation request. The InterruptedException thrown by the specified task is treated as if the task has been canceled. That is, InterruptedException thrown by the task is converted to OperationCanceledException; any other exception is simply propagated to the caller as it was thrown by the task.

      Note that this may cause the current thread to be interrupted without throwing any exception if the underlying task does not detect the thread interruption. The thread interrupted status will not be cleared even if it was caused by a cancellation request because there is no way to detect if outside code has also interrupted the current thread.

      This method is intended to be used to convert code which uses thread interruption for cancellation to the more robust cancellation mechanism provided by JTrim.

      Type Parameters:
      ResultType - the type of the result of the task to be executed
      Parameters:
      cancelToken - the CancellationToken which when signals causes the current thread to be interrupted. This argument will also be passed to the task to be executed. This argument cannot be null.
      task - the task to be executed. This argument cannot be null.
      Returns:
      the return value of the specified task. This value is exactly the same object as the one returned by the task and so if the task returns null, this method may also returns null.
      Throws:
      NullPointerException - thrown if any of the arguments is null
      OperationCanceledException - thrown if the underlying task thrown an OperationCanceledException or an InterruptedException. Note that the current thread will no be re-interrupted if the specified task throws an InterruptedException.