This class provides a means for early termination of graph algorithms.
Remarks
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. The handler's stopDuration and cancelDuration methods can be used to automatically stop or cancel an algorithm after a specified period of time has elapsed. 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 ILayoutAlgorithm 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.
Usage in Algorithms
Algorithms have to retrieve an instance of this class from the graph that is processed using method getFromGraph. Then, the algorithm needs to query the retrieved instance of this class for stop or cancel requests using method check.
Alternatively, convenience method check 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.
Default Values of Properties
| cancelDuration | ZERO | No automatic termination will occur. |
| stopDuration | ZERO | No automatic termination will occur. |
Type Details
- yfiles module
- algorithms
- yfiles-umd modules
- All layout modules, view-layout-bridge
- Legacy UMD name
- yfiles.algorithms.AbortHandler
See Also
Constructors
Creates a new AbortHandler instance.
Properties
Gets or sets the duration an algorithm may run before being cancelled automatically.
Gets whether or not methods check or check were called after a stop or cancel event.
Remarks
true if one of the check methods either threw an AlgorithmAbortedError or returned true to indicate that the calling algorithm should terminate gracefully. Otherwise, this method returns false.See Also
Gets or sets the duration an algorithm may run before being stopped automatically.
Returns whether or not a stop request was scheduled explicitly with the stop method.
Methods
Determines whether or not an algorithm should terminate immediately.
Remarks
true if the algorithm should terminate gracefully and ensures that the processed graph remains in a consistent state.Returns
- ↪boolean
true, if the algorithm should terminate immediately,falseotherwise
Throws
- Exception({ name: 'AlgorithmAbortedError' })
- if the algorithm should terminate immediately
See Also
Resets the state of the handler.
Remarks
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
Schedules a stop request.
Remarks
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
Determines the remaining time until an algorithm that checks this handler is stopped automatically.
Remarks
-1 will be returned which means that the algorithm may run unrestricted.Returns
- ↪TimeSpan
- the remaining time until the algorithm is stopped automatically or
-1if the algorithm may run unrestricted
See Also
Constants
A data provider key for attaching an AbortHandler instance to a graph.
Remarks
| Domain | Graph | the given graph |
| Values | AbortHandler | a handler that receives requests for stopping and canceling an algorithm or null if no handler is attached |
See Also
Static Methods
Determines whether or not an algorithm should terminate immediately.
Remarks
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
- ↪boolean
true, if the algorithm should stop immediately while still providing some valid result,falseotherwise
Throws
- Exception({ name: 'AlgorithmAbortedError' })
- if the algorithm should terminate immediately
- Exception({ name: 'NullReferenceError' })
- if the given graph is
null
See Also
Attaches the AbortHandler instance of the given source graph to the target graph as well.
Parameters
A map of options to pass to the method.
- 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
Throws
- Exception({ name: 'NullReferenceError' })
- if the given source is
null
Creates an handler instance and attaches it to the given graph.
Remarks
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
A map of options to pass to the method.
- graph - Graph
- the graph to which the handler will be attached
Returns
- ↪AbortHandler
- the AbortHandler instance for the given graph
Throws
- Exception({ name: 'NullReferenceError' })
- if the given graph is
null.
See Also
Returns an AbortHandler instance for the given graph.
Remarks
Parameters
A map of options to pass to the method.
- graph - Graph
- the given graph
Returns
- ↪AbortHandler
- an AbortHandler for the given graph or a non-functional instance if no handler has been previously created
Throws
- Exception({ name: 'NullReferenceError' })
- if the given graph is
null
See Also
Determines whether or not an AbortHandler instance is attached to the given graph.
Removes any attached AbortHandler instance from the given graph.