Package | com.yworks.yfiles.algo |
Class | public class AbortHandler |
Inheritance | AbortHandler YObject Object |
Client Code Usage: An instance of this class can be attached to a graph using method createForGraph() . 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.
If a graph with an attached handler is processed by multiple algorithms (or multiple times by one 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 use case 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, methods stopDuration and cancelDuration may be used to automatically stop or cancel 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(). The algorithm then needs to query the retrieved instance of this class for stop or cancel requests using method check(). Alternatively, convenience method check2() 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.
See also
Property | Defined By | ||
---|---|---|---|
cancelDuration : LongImpl
Specifies the duration (in milliseconds) an algorithm may run before being cancelled automatically. | AbortHandler | ||
DUMMY_HANDLER : AbortHandler [static] [read-only] | AbortHandler | ||
stopDuration : LongImpl
Specifies the duration (in milliseconds) an algorithm may run before being stopped automatically. | AbortHandler |
Method | Defined By | ||
---|---|---|---|
AbortHandler(init:Boolean = true)
Initializes a new AbortHandler instance with the current time (com.yworks.bridge.util.FlexUtils.currentTimeMillis()) to be used as timestamp for determining whether or not an algorithm should be stopped or cancelled automatically. | AbortHandler | ||
cancel():void
Schedules a cancel request. | AbortHandler | ||
check():Boolean
Determines if an algorithm should terminate its work early. | AbortHandler | ||
[static]
Determines if an algorithm should terminate its work early. | AbortHandler | ||
[static]
Attaches the handler instance of the given source graph to the target graph as well. | AbortHandler | ||
[static]
Creates an instance of this class and attaches it to the given graph. | AbortHandler | ||
equals(o:Object):Boolean | YObject | ||
getClass():Class [override] | AbortHandler | ||
[static]
Returns an instance of this class for the given graph. | AbortHandler | ||
hasCheckFailed():Boolean
Returns true if method check() or check2() were called after a stop or cancel event. | AbortHandler | ||
hasHandler(graph:Graph):Boolean [static]
Determines whether or not an instance of this class is attached to the given graph. | AbortHandler | ||
hashCode():int | YObject | ||
Determines the remaining time (in milliseconds) until an algorithm that checks (check()) this handler is cancelled automatically. | AbortHandler | ||
Determines the remaining time (in milliseconds) until an algorithm that checks (check()) this handler is stopped automatically. | AbortHandler | ||
[static]
Initializes a new AbortHandler instance with the current time (com.yworks.bridge.util.FlexUtils.currentTimeMillis()) to be used as timestamp for determining whether or not an algorithm should be stopped or cancelled automatically. | AbortHandler | ||
removeFromGraph(graph:Graph):void [static]
Removes any attached instance of this class from the given graph. | AbortHandler | ||
reset():void
Resets the state of the handler. | AbortHandler | ||
stop():void
Schedules a stop request. | AbortHandler |
Method | Defined By | ||
---|---|---|---|
initAbortHandler():void
Initializes this object. | AbortHandler |
Constant | Defined By | ||
---|---|---|---|
ABORT_HANDLER_DPKEY : Object = y.algo.AbortHandler.ABORT_HANDLER_DPKEY [static]
com.yworks.yfiles.base.DataProvider key used to attach an com.yworks.yfiles.algo.AbortHandler instance to a graph. | AbortHandler |
cancelDuration | property |
cancelDuration:LongImpl
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.
Note, automatic termination will only occur for positive values.
Default to 0
, i.e. no automatic termination will occur.
public function get cancelDuration():LongImpl
public function set cancelDuration(value:LongImpl):void
See also
DUMMY_HANDLER | property |
DUMMY_HANDLER:AbortHandler
[read-only] public static function get DUMMY_HANDLER():AbortHandler
stopDuration | property |
stopDuration:LongImpl
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.
Note, automatic termination will only occur for positive values.
Default to 0
, i.e. no automatic termination will occur.
public function get stopDuration():LongImpl
public function set stopDuration(value:LongImpl):void
See also
AbortHandler | () | Constructor |
public function AbortHandler(init:Boolean = true)
Initializes a new AbortHandler
instance with the current time (com.yworks.bridge.util.FlexUtils.currentTimeMillis()) to be used as timestamp for determining whether or not an algorithm should be stopped or cancelled automatically.
init:Boolean (default = true ) — An internally used switch to help handle proper instance initialization in inheritance chains where classes can have multiple constructor-like factory methods.
This parameter can safely be ignored/omitted when calling the constructor.
|
See also
cancel | () | method |
public function cancel():void
Schedules a cancel request. Calling check() after a cancel request has been scheduled will trigger an com.yworks.yfiles.algo.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. Furthermore, the state of the used com.yworks.yfiles.layout.Layouter instance may become corrupted. Hence, a new instance has to be created after each cancellation.
See also
check | () | method |
public function check():Boolean
Determines if an algorithm should terminate its work early.
This method returns true
if the algorithm should terminate gracefully and ensures that the processed graph remains in a consistent state. This method throws an com.yworks.yfiles.algo.AlgorithmAbortedException if the algorithm should terminate immediately.
Boolean — true , if the algorithm should stop as soon as possible while still providing some valid result and false if the algorithm should continue normally.
|
AlgorithmAbortedException — if the algorithm should terminate immediately.
|
See also
check2 | () | method |
public static function check2(graph:Graph):Boolean
Determines if an algorithm should terminate its work early.
This method returns true
if the algorithm should terminate gracefully and ensure that the processed graph remains in a consistent state. This method throws an com.yworks.yfiles.algo.AlgorithmAbortedException if the algorithm should terminate immediately.
This convenience method is meant for one-time checks only. For performance critical code that checks repeatedly, it is recommended to retrieve the given graph's attached handler once and only call the handler's check() method repeatedly.
Parameters
graph:Graph |
Boolean — true , if the algorithm should stop as soon as possible while still providing some valid result and false if the algorithm should continue normally.
|
AlgorithmAbortedException — if the algorithm should terminate immediately.
| |
ReferenceError — if the given graph is null .
|
See also
copyHandler | () | method |
public static function copyHandler(source:Graph, target:Graph):void
Attaches the handler instance of the given source graph to the target graph as well.
Note, if there is a handler attached to the given target graph, this method will silently replace said instance with the one attached to the source graph.
Parameters
source:Graph — the graph whose handler is attached to the target graph.
| |
target:Graph — the graph to which the handler of the source graph is attached.
|
ReferenceError — if the given source is null .
|
createForGraph | () | method |
public static function createForGraph(graph:Graph):AbortHandler
Creates an instance of this class and attaches it to the given graph. If the given graph already has an attached handler instance, said instance will be returned and this method will not create a new handler instance.
This method should be called by client code prior to starting a graph algorithm that may be terminated early.
Parameters
graph:Graph — the graph to which the handler will be attached.
|
AbortHandler — the handler instance for the given graph.
|
ReferenceError — if the given graph is null .
|
See also
getClass | () | method |
override public function getClass():Class
ReturnsClass |
getFromGraph | () | method |
public static function getFromGraph(graph:Graph):AbortHandler
Returns an instance of this class for the given graph. If createForGraph() has been used to attach a new handler to the given graph, said instance is returned. Otherwise a non-functional instance is returned whose methods do nothing. Use hasHandler() whether or not a handler has been already attached to the given graph.
Parameters
graph:Graph — the graph for which the handler should be retrieved.
|
AbortHandler — a handler for the given graph. Maybe a non-functional instance if no handler has been previously created.
|
ReferenceError — if the given graph is null .
|
See also
hasCheckFailed | () | method |
public function hasCheckFailed():Boolean
Returns true
if method check() or check2() were called after a stop or cancel event.
More precisely, it returns true
if one of the check methods either threw an com.yworks.yfiles.algo.AlgorithmAbortedException or returned true
to indicate that the calling algorithm should terminate gracefully. Otherwise, this method returns false
.
Boolean — true if the check methods were called after a stop or cancel event and false , otherwise.
|
See also
hasHandler | () | method |
public static function hasHandler(graph:Graph):Boolean
Determines whether or not an instance of this class is attached to the given graph.
Parameters
graph:Graph — the graph which to check for a handler.
|
Boolean — true if a handler is attached to the given graph; false otherwise.
|
ReferenceError — if the given graph is null .
|
initAbortHandler | () | method |
protected final function initAbortHandler():void
Initializes this object. See the documentation of the corresponding factory method newAbortHandler()
for details.
See also
millisToCancel | () | method |
public function millisToCancel():LongImpl
Determines the remaining time (in milliseconds) until an algorithm that checks (check()) this handler is cancelled automatically.
ReturnsLongImpl — the remaining time (in milliseconds) until the algorithm is cancelled automatically.
|
See also
millisToStop | () | method |
public function millisToStop():LongImpl
Determines the remaining time (in milliseconds) until an algorithm that checks (check()) this handler is stopped automatically.
ReturnsLongImpl — the remaining time (in milliseconds) until the algorithm is stopped automatically.
|
See also
newAbortHandler | () | method |
public static function newAbortHandler():AbortHandler
Initializes a new AbortHandler
instance with the current time (com.yworks.bridge.util.FlexUtils.currentTimeMillis()) to be used as timestamp for determining whether or not an algorithm should be stopped or cancelled automatically.
AbortHandler |
See also
removeFromGraph | () | method |
public static function removeFromGraph(graph:Graph):void
Removes any attached instance of this class from the given graph.
Parameters
graph:Graph — the graph from which the handler will be removed.
|
ReferenceError — if the given graph is null .
|
reset | () | method |
public function reset():void
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 to determine whether or not an algorithm should be stopped or cancelled automatically is updated to the current time (com.yworks.bridge.util.FlexUtils.currentTimeMillis()) 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
stop | () | method |
public function stop():void
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 schedule for this handler, the stop request is ignore. If a cancel() request is schedule later on, the stop request is overwritten.
See also
ABORT_HANDLER_DPKEY | Constant |
public static const ABORT_HANDLER_DPKEY:Object = y.algo.AbortHandler.ABORT_HANDLER_DPKEY
com.yworks.yfiles.base.DataProvider key used to attach an com.yworks.yfiles.algo.AbortHandler instance to a graph. Only instances of com.yworks.yfiles.algo.AbortHandler should be assigned to this data provider, otherwise a TypeError will occur. Layout algorithms will use the attached handler to check for requests to cancel or stop the layout process.
See also