Module jtrim.concurrent
Package org.jtrim2.cancel

Interface CancellationToken

public interface CancellationToken
Defines an interface to detect cancellation requests. How cancellation is done is implementation dependent but it is usually controlled by an associated CancellationController sharing the same CancellationSource.

In general there are two ways to listen for cancellation requests:

  • The isCanceled() method may be checked periodically and act accordingly when it returns true. Usually the best way to react to a cancellation request is to throw a OperationCanceledException. In this case the convenient checkCanceled() method can be used.
  • A listener maybe added to be notified immediately when cancellation occurs. This can be done by calling the addCancellationListener(Runnable) method. This asynchronous notification is usually preferable when a subtask (such as an IO operation) must be canceled as a response to a cancellation request .

Thread safety

The methods of this interface must be safe to be accessed by multiple threads concurrently.

Synchronization transparency

The isCanceled() and the checkCanceled() methods must be synchronization transparent but the addCancellationListener is not (as it may invoke cancellation listeners).
See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    ListenerRef
    addCancellationListener(Runnable listener)
    Adds a listener which is to be called when cancellation was requested.
    default void
    checkCanceled()
    Checks if cancellation has been requested and throws a OperationCanceledException if so otherwise returns immediately without doing anything.
    boolean
    isCanceled()
    Returns true if cancellation was requested.

  • Method Details

    • addCancellationListener

      ListenerRef addCancellationListener(Runnable listener)
      Adds a listener which is to be called when cancellation was requested. In case cancellation has already been requested, the listener may be notified on the current thread. Note that the listener may be notified in various places such as the cancel method of CancellationController so it must not do anything expensive and especially must not wait for external events (such as IO).

      The specified listener will always be notified when cancellation is requested regardless when it occurred and it will not be notified multiple times.

      Note that since this method may need to notify the listener on the current thread, it may propagate any unchecked exception the listener throws to the caller.

      Parameters:
      listener - the Runnable whose run method is to be called when cancellation was requested. This listener can be notified in various places, so it is especially important that this listener does as little task as possible and must not wait for external events. This argument cannot be null.
      Returns:
      the ListenerRef which can be used to unregister the listener, so that it will no longer be notified of cancellation requests. Unregistering the listener prevents notifications of subsequent cancellation requests but if cancellation was requested prior to this call (or concurrently with this call), the listener might be notified even after the listener has been unregistered. This method never returns null.

    • isCanceled

      boolean isCanceled()
      Returns true if cancellation was requested. This method may be checked periodically to detect cancellation requests but since the usual way to respond to such request is throwing a OperationCanceledException, it is more convenient to use the checkCanceled() method.

      This method must be implemented so, that once it returned true, it must return true forever after (it cannot revert to returning false).

      Returns:
      true if cancellation was requested, false if not

    • checkCanceled

      default void checkCanceled()
      Checks if cancellation has been requested and throws a OperationCanceledException if so otherwise returns immediately without doing anything.

      This method is only provided for convenience and it is a shorthand for the following code: 

      
 if (token.isCanceled()) {
   throw new OperationCanceledException();
 }
      Throws:
      OperationCanceledException - thrown if cancellation was requested. If this exception is thrown, isCanceled() returns true.