com.yworks.yfiles.algorithms

Class AbortHandler

java.lang.Object

com.yworks.yfiles.algorithms.AbortHandler

public class AbortHandler
extends 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(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.

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, StopDuration and CancelDuration 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(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(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

Fields

Modifier and Type	Field and Description
static GraphDpKey<AbortHandler>	ABORT_HANDLER_DPKEY A DataProvider key for attaching an AbortHandler instance to a graph Only instances of AbortHandler should be assigned to this IDataProvider, otherwise a ClassCastException will occur.

Constructor Summary

Constructors

Constructor and Description
AbortHandler() Creates a new AbortHandler instance.

Method Summary

Modifier and Type	Method and Description
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.
Duration	getCancelDuration() Gets the duration an algorithm may run before being cancelled automatically.
static AbortHandler	getFromGraph(Graph graph) Returns an AbortHandler instance for the given graph.
Duration	getStopDuration() Gets the duration an algorithm may run before being stopped automatically.
static boolean	hasHandler(Graph graph) Determines whether or not an AbortHandler instance is attached to the given graph.
boolean	isCancelRequested() Returns whether or not a cancel request was scheduled explicitly with the cancel() method.
boolean	isCheckFailed() Gets whether or not methods check() or check(Graph) were called after a stop or cancel event.
boolean	isStopRequested() Returns whether or not a stop request was scheduled explicitly with the stop() method.
static void	removeFromGraph(Graph graph) Removes any attached AbortHandler instance from the given graph.
void	reset() Resets the state of the handler.
void	setCancelDuration(Duration value) Sets the duration an algorithm may run before being cancelled automatically.
void	setStopDuration(Duration value) Sets the duration an algorithm may run before being stopped automatically.
void	stop() Schedules a stop request.
Duration	timeToCancel() Determines the remaining time (in milliseconds) until an algorithm that checks this handler is cancelled automatically.
Duration	timeToStop() Determines the remaining time until an algorithm that checks this handler is stopped automatically.

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 GraphDpKey<AbortHandler> ABORT_HANDLER_DPKEY

A DataProvider key for attaching an AbortHandler instance to a graph

Only instances of AbortHandler should be assigned to this IDataProvider, 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.

See Also:

setStopDuration(Duration), setCancelDuration(Duration), reset()

Method Detail

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()

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.

Throws:

AlgorithmAbortedException - if the algorithm should terminate immediately

Returns:

true, if the algorithm should terminate immediately, false otherwise

See Also:

cancel(), stop()

check

public static final 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.

Throws:

AlgorithmAbortedException - if the algorithm should terminate immediately

NullPointerException - if the given graph is null

Returns:

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

See Also:

check(), cancel(), stop()

copyHandler

public static final void copyHandler(Graph source,
                                     Graph target)

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

Throws:

NullPointerException - if the given source is null

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

createForGraph

public static final 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.

Throws:

NullPointerException - if the given graph is null.

Parameters:

graph - the graph to which the handler will be attached

Returns:

the AbortHandler instance for the given graph

See Also:

hasHandler(Graph)

getCancelDuration

public Duration getCancelDuration()

Gets the duration 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.

Throws:

IllegalArgumentException - if the duration is negative

Automatic termination will only occur for positive values.

Default Value:

The default value is Duration.ZERO. No automatic termination will occur.

Returns:

the duration (in milliseconds)

See Also:

reset(), cancel(), setCancelDuration(Duration)

getFromGraph

public static final AbortHandler getFromGraph(Graph graph)

Returns an AbortHandler instance for the given graph.

If createForGraph(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(Graph) to check whether or not a handler has been already attached to the given graph.

Throws:

NullPointerException - if the given graph is null

Parameters:

graph - the given graph

Returns:

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

See Also:

createForGraph(Graph), hasHandler(Graph)

getStopDuration

public Duration getStopDuration()

Gets the duration 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.

Throws:

IllegalArgumentException - if the duration is negative

Automatic termination will only occur for positive values.

Default Value:

The default value is Duration.ZERO. No automatic termination will occur.

Returns:

the duration

See Also:

timeToStop(), reset(), stop(), setStopDuration(Duration)

hasHandler

public static final boolean hasHandler(Graph graph)

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

Throws:

NullPointerException - if the given graph is null

Parameters:

graph - the given graph

Returns:

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

isCancelRequested

public boolean isCancelRequested()

Returns whether or not a cancel request was scheduled explicitly with the cancel() method.

Returns:

The CancelRequested.

isCheckFailed

public boolean isCheckFailed()

Gets whether or not methods check() or check(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(Graph)

isStopRequested

public boolean isStopRequested()

Returns whether or not a stop request was scheduled explicitly with the stop() method.

Returns:

The StopRequested.

removeFromGraph

public static final void removeFromGraph(Graph graph)

Removes any attached AbortHandler instance from the given graph.

Throws:

NullPointerException - if the given graph is null.

Parameters:

graph - the given graph

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 reset 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(Duration), setStopDuration(Duration)

setCancelDuration

public void setCancelDuration(Duration value)

Sets the duration 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.

Throws:

IllegalArgumentException - if the duration is negative

Automatic termination will only occur for positive values.

Default Value:

The default value is Duration.ZERO. No automatic termination will occur.

Parameters:

value - the duration (in milliseconds)

See Also:

reset(), cancel(), getCancelDuration()

setStopDuration

public void setStopDuration(Duration value)

Sets the duration 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.

Throws:

IllegalArgumentException - if the duration is negative

Automatic termination will only occur for positive values.

Default Value:

The default value is Duration.ZERO. No automatic termination will occur.

Parameters:

value - the duration

See Also:

timeToStop(), reset(), stop(), getStopDuration()

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()

timeToCancel

public Duration timeToCancel()

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

Returns:

the remaining time until the algorithm is cancelled automatically.

See Also:

setCancelDuration(Duration), reset(), cancel()

timeToStop

public Duration timeToStop()

Determines the remaining time 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 until the algorithm is stopped automatically or -1 if the algorithm may run unrestricted

See Also:

setStopDuration(Duration), reset(), stop()