Search this API

y.algo
Class AbortHandler

java.lang.Object
  extended by y.algo.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(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 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 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:
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:
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:
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:
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:
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:
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:
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
NullPointerException - if the given graph is null
See Also:
check(), cancel(), stop()

© Copyright 2000-2016,
yWorks GmbH.
All rights reserved.