y.algo
Class AbortHandler

java.lang.Object
  y.algo.AbortHandler

public class AbortHandler
extends java.lang.Object

This class provides a means for early termination of graph algorithms.

Instances of this class may be attached to and retrieved from a graph and may receive requests for stopping and canceling an algorithm that is currently executed on the given graph.

Client Code Usage

An instance of this class can be attached to a graph using method createForGraph(y.base.Graph). Using the handler's stop() and cancel() methods, it is possible to schedule requests for early termination. Algorithms can check for these requests and handle them appropriately.

stop()

The algorithm should terminate gracefully, delivering a consistent result. Although the termination will be early, it will usually not be immediate.

cancel()

The algorithm should terminate immediately and all work done so far will be discarded.

IMPORTANT: It is not guaranteed that the processed graph will be in a consistent state after cancellation. For this reason, it is strongly recommended to cancel only algorithms that work on copies of the real graph structure such as layout algorithms running in buffered mode. Furthermore, the state of the used Layouter instance may become corrupted. Hence, a new instance has to be created after each cancellation.

If a graph with an attached handler is processed by multiple algorithms (or multiple times by the same algorithm), the attached handler has to be reset() between algorithm runs. Otherwise, previous requests for early termination may lead to an undesired early termination of the next algorithm run.

Methods stop() and cancel() are primarily meant for multi-threaded scenarios where the algorithm runs in a background thread and stop()/cancel() are called from the main or UI thread. For pure single-threaded use cases, setStopDuration(long) and setCancelDuration(long) may be used for automatically stopping or cancelling the algorithm after a specified period of time has elapsed.

Usage in Algorithms

Algorithms have to retrieve an instance of this class from the graph that is processed using method getFromGraph(y.base.Graph). Then, the algorithm needs to query the retrieved instance of this class for stop or cancel requests using method check().

Alternatively, convenience method check(y.base.Graph) for one-time checks is available. For performance critical code that checks repeatedly, it is recommended to follow the first approach, though.

When handling a stop request, algorithms should ensure that the resulting graph is still in a consistent state.

Field Summary

static java.lang.Object

ABORT_HANDLER_DPKEY A DataProvider key for attaching an AbortHandler instance to a graph Only instances of AbortHandler should be assigned to this DataProvider, otherwise a ClassCastException will occur.

Constructor Summary

AbortHandler()
Creates a new AbortHandler instance.

Method Summary

void	cancel() Schedules a cancel request.
boolean	check() Determines whether or not an algorithm should terminate immediately.
static boolean	check(Graph graph) Determines whether or not an algorithm should terminate immediately.
static void	copyHandler(Graph source, Graph target) Attaches the AbortHandler instance of the given source graph to the target graph as well.
static AbortHandler	createForGraph(Graph graph) Creates an handler instance and attaches it to the given graph.
long	getCancelDuration() Returns the duration (in milliseconds) an algorithm may run before being cancelled automatically.
static AbortHandler	getFromGraph(Graph graph) Returns an AbortHandler instance for the given graph.
long	getStopDuration() Returns the duration (in milliseconds) an algorithm may run before being stopped automatically.
boolean	hasCheckFailed() Returns whether or not methods check() or check(y.base.Graph) were called after a stop or cancel event.
static boolean	hasHandler(Graph graph) Determines whether or not an AbortHandler instance is attached to the given graph.
long	millisToCancel() Determines the remaining time (in milliseconds) until an algorithm that checks this handler is cancelled automatically.
long	millisToStop() Determines the remaining time (in milliseconds) until an algorithm that checks this handler is stopped automatically.
static void	removeFromGraph(Graph graph) Removes any attached AbortHandler instance from the given graph.
void	reset() Resets the state of the handler.
void	setCancelDuration(long ms) Specifies the duration (in milliseconds) an algorithm may run before being cancelled automatically.
void	setStopDuration(long ms) Specifies the duration (in milliseconds) an algorithm may run before being stopped automatically.
void	stop() Schedules a stop request.

Methods inherited from class java.lang.Object

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

Field Detail

ABORT_HANDLER_DPKEY

public static final java.lang.Object ABORT_HANDLER_DPKEY

A DataProvider key for attaching an AbortHandler instance to a graph

Only instances of AbortHandler should be assigned to this DataProvider, otherwise a ClassCastException will occur. Layout algorithms will use the attached handler to check for requests to cancel or stop the layout process.

Constructor Detail

AbortHandler

public AbortHandler()

Creates a new AbortHandler instance.

The current time will be used as timestamp for determining whether or not an algorithm should be stopped or cancelled automatically.

See Also:

setStopDuration(long), setCancelDuration(long), reset()

Method Detail

stop

public void stop()

Schedules a stop request.

Algorithms that detect stop requests should terminate gracefully and ensure that the processed graph remains in a consistent state.

If a cancel() request has already been scheduled for this handler, the stop request is ignored. If a cancel() request is scheduled later on, the stop request is overridden.

See Also:

check(), cancel()

millisToStop

public long millisToStop()

Determines the remaining time (in milliseconds) until an algorithm that checks this handler is stopped automatically.

If the stop duration is less than or equal to zero, -1 will be returned which means that the algorithm may run unrestricted.

Returns:

the remaining time (in milliseconds) or -1 if the algorithm may run unrestricted

See Also:

setStopDuration(long), reset(), stop()

getStopDuration

public long getStopDuration()

Returns the duration (in milliseconds) an algorithm may run before being stopped automatically.

An algorithm is terminated gracefully, if the time in between creating or resetting this handler and calling check() exceeds the stop duration.

Automatic termination will only occur for positive values.

Returns:

the duration (in milliseconds)

See Also:

setStopDuration(long), millisToStop(), reset(), stop()

setStopDuration

public void setStopDuration(long ms)

Specifies the duration (in milliseconds) an algorithm may run before being stopped automatically.

An algorithm is terminated gracefully, if the time in between creating or resetting this handler and calling check() exceeds the stop duration.

Automatic termination will only occur for positive values.

Default Value:

The default value is 0. No automatic termination will occur.

Parameters:

ms - the duration (in milliseconds)

Throws:

java.lang.IllegalArgumentException - if the duration is negative

See Also:

setStopDuration(long), millisToStop(), reset(), stop()

cancel

public void cancel()

Schedules a cancel request.

Calling check() after a cancel request has been scheduled will trigger an AlgorithmAbortedException. This usually results in an immediate termination of the algorithm. Thus, a consistent state of the processed graph cannot be guaranteed. For this reason, it is strongly recommended to cancel only algorithms that work on copies of the real graph structure such as layout algorithms running in buffered mode.

See Also:

check(), stop()

millisToCancel

public long millisToCancel()

Determines the remaining time (in milliseconds) until an algorithm that checks this handler is cancelled automatically.

Returns:

the remaining time (in milliseconds)

See Also:

setCancelDuration(long), reset(), cancel()

getCancelDuration

public long getCancelDuration()

Returns the duration (in milliseconds) an algorithm may run before being cancelled automatically.

An algorithm is terminated immediately, if the time in between creating or resetting this handler and calling check() exceeds the cancel duration.

Automatic termination will only occur for positive values.

Returns:

the duration (in milliseconds)

See Also:

setCancelDuration(long), getCancelDuration(), millisToCancel(), reset(), cancel()

setCancelDuration

public void setCancelDuration(long ms)

Specifies the duration (in milliseconds) an algorithm may run before being cancelled automatically.

An algorithm is terminated immediately, if the time in between creating or resetting this handler and calling check() exceeds the cancel duration.

Automatic termination will only occur for positive values.

Default Value:

The default value is 0. No automatic termination will occur.

Parameters:

ms - the duration (in milliseconds)

Throws:

java.lang.IllegalArgumentException - if the duration is negative

See Also:

getCancelDuration(), millisToCancel(), reset(), cancel()

hasCheckFailed

public boolean hasCheckFailed()

Returns whether or not methods check() or check(y.base.Graph) were called after a stop or cancel event.

More precisely, it returns true if one of the check methods either threw an AlgorithmAbortedException or returned true to indicate that the calling algorithm should terminate gracefully. Otherwise, this method returns false.

Returns:

true if the check methods were called after a stop or cancel event, false otherwise

See Also:

check(), check(y.base.Graph)

check

public boolean check()

Determines whether or not an algorithm should terminate immediately.

This method returns true if the algorithm should terminate gracefully and ensures that the processed graph remains in a consistent state.

Returns:

true, if the algorithm should terminate immediately, false otherwise

Throws:

AlgorithmAbortedException - if the algorithm should terminate immediately

See Also:

cancel(), stop()

reset

public void reset()

Resets the state of the handler.

Resetting the handler discards any previous stop or cancel requests. Moreover, the handler's internal timestamp that is used for determining whether or not an algorithm should be stopped or cancelled automatically is updated to the current time as well.

This method should be called whenever a graph with an attached handler is processed an additional time to prevent previous requests for early termination to result in an undesired early termination of the next algorithm run.

See Also:

setCancelDuration(long), setStopDuration(long)

createForGraph

public static AbortHandler createForGraph(Graph graph)

Creates an handler instance and attaches it to the given graph.

If the given graph has already an attached handler instance, this is the instance that will be returned and this method will not create a new AbortHandler.

This method should be called by client code prior to starting a graph algorithm that may be terminated early.

Parameters:

graph - the graph to which the handler will be attached

Returns:

the AbortHandler instance for the given graph

Throws:

java.lang.NullPointerException - if the given graph is null.

See Also:

hasHandler(y.base.Graph)

removeFromGraph

public static void removeFromGraph(Graph graph)

Removes any attached AbortHandler instance from the given graph.

Parameters:

graph - the given graph

Throws:

java.lang.NullPointerException - if the given graph is null.

getFromGraph

public static AbortHandler getFromGraph(Graph graph)

Returns an AbortHandler instance for the given graph.

If createForGraph(y.base.Graph) has been used for attaching a new handler to the given graph, this is the instance that will be returned. Otherwise, a non-functional instance is returned whose methods do nothing. Use hasHandler(y.base.Graph) to check whether or not a handler has been already attached to the given graph.

Parameters:

graph - the given graph

Returns:

an AbortHandler for the given graph or a non-functional instance if no handler has been previously created

Throws:

java.lang.NullPointerException - if the given graph is null

See Also:

createForGraph(y.base.Graph), hasHandler(y.base.Graph)

copyHandler

public static void copyHandler(Graph source,
                               Graph target)

Attaches the AbortHandler instance of the given source graph to the target graph as well.

If there is an AbortHandler attached to the given target graph, this method will silently replace that instance with the one attached to the source graph.

Parameters:

source - the graph whose handler is attached to the target graph

target - the graph to which the handler of the source graph is attached

Throws:

java.lang.NullPointerException - if the given source is null

hasHandler

public static boolean hasHandler(Graph graph)

Determines whether or not an AbortHandler instance is attached to the given graph.

Parameters:

graph - the given graph

Returns:

true if a handler is attached to the given graph, false otherwise

Throws:

java.lang.NullPointerException - if the given graph is null

check

public static boolean check(Graph graph)

Determines whether or not an algorithm should terminate immediately.

This method returns true if the algorithm should terminate gracefully and ensures that the processed graph remains in a consistent state.

This convenience method is meant for one-time checks only. For performance critical code that needs to check repeatedly, it is recommended to retrieve the given graph's attached handler once and only call the handler's check() method repeatedly.

Returns:

true, if the algorithm should stop immediately while still providing some valid result, false otherwise

Throws:

AlgorithmAbortedException - if the algorithm should terminate immediately

java.lang.NullPointerException - if the given graph is null

See Also:

check(), cancel(), stop()