Package net.algart.contexts

Interface InterruptionContext

All Superinterfaces:

Context

All Known Implementing Classes:

DefaultContext

public interface InterruptionContext
extends Context

The context allowing the user to interrupt any algorithm. It is an extension of standard technique based on thread.interrupt() and Thread.interrupted() calls.

The basic way of using this context is calling checkInterruption() method in the points of algorithm that are "safe" for interruption. In other words, this method should be called in the places where Thread.interrupted() is called in the standard technique. For example:

 public void someComplexAlgorithm(Context context, some-other-arguments...) {
     InterruptionContext ic = context.as(InterruptionContext.class);
     . . .
     for (int k = 0; k < n; k++) { // the main long-working loop
         . . .
         ic.checkInterruption()
     }
  
     . . .
 }
 

Unlike Thread.interrupted(), the checkInterruption() method informs about interruption request by throwing special InterruptionException. This behavior complies with the context definition: the method results do not depend on the presense or features of the context. This exception, unlike the standard InterruptedException, is unchecked, so you don't need to specify it in the method declaration.

Another possible way of using this context is adding a listener, which will be invoked when the application will attempt to interrupt the executing module. The implementation of this listener, provided by the algorithm, for example, can set some volatile flag "isInterrupted", which is checked inside the main loop. Please not forget to remove all added listeners (usually in the finally section).

Please note: some interruption contexts may provide empty implementations of addInterruptionListener / removeInterruptionListener methods! So, we recommend to use checkInterruption() method always, when this solution is possible. In most situations the checkInterruption() method is quite enough technique; interruption listeners are usually needed in very advanced algorithms only.

Author:

Daniel Alievsky

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static class	InterruptionContext.Event	The interruption event: an argument of InterruptionContext.Listener.interruptionRequested(InterruptionContext.Event) method.
static interface	InterruptionContext.Listener	The interruption listener, that can be added and removed by the interruption context.

Method Summary

Modifier and Type	Method	Description
void	addInterruptionListener(InterruptionContext.Listener listener)	Adds the listener to receive interruption requests.
void	checkInterruption()	Checks, whether interruption is requested by the application, and throws InterruptionException in this case.
void	removeInterruptionListener(InterruptionContext.Listener listener)	Removes the listener added by addInterruptionListener(Listener) method.

Methods inherited from interface net.algart.contexts.Context

as, is

Method Details

checkInterruption

void checkInterruption()
                throws InterruptionException

Checks, whether interruption is requested by the application, and throws InterruptionException in this case.

Throws:

InterruptionException - if the application has requested to interrupt the currently executing module.

addInterruptionListener

void addInterruptionListener(InterruptionContext.Listener listener)

Adds the listener to receive interruption requests. May do nothing in some implementations of this interface. Please not forget to remove all added listener by removeInterruptionListener(Listener) method (usually in the finally section of your method).

If listener is null, no exception is thrown and no action is performed.

Parameters:

listener - the listener that will be invoked when the application attempts to interrupt module execution.

removeInterruptionListener

void removeInterruptionListener(InterruptionContext.Listener listener)

Removes the listener added by addInterruptionListener(Listener) method.

If listener is null, no exception is thrown and no action is performed.

Parameters:

listener - the listener that should be removed.