100 lines
3.0 KiB
Markdown
100 lines
3.0 KiB
Markdown
Limiting Run Time
|
|
=================
|
|
|
|
[`Engine::on_progress`]: https://docs.rs/rhai/{{version}}/rhai/struct.Engine.html#method.on_progress
|
|
|
|
|
|
Track Progress and Force-Termination
|
|
------------------------------------
|
|
|
|
{{#include ../links.md}}
|
|
|
|
```admonish info.side "Operations count vs. progress"
|
|
|
|
_Operations count_ does not indicate the _proportion_ of work already done – thus it is not real _progress_ tracking.
|
|
|
|
The real progress can be _estimated_ based on the expected number of operations in a typical run.
|
|
```
|
|
|
|
It is impossible to know when, or even whether, a script run will end
|
|
(a.k.a. the [Halting Problem](http://en.wikipedia.org/wiki/Halting_problem)).
|
|
|
|
When dealing with third-party untrusted scripts that may be malicious, in order to track evaluation
|
|
progress and force-terminate a script prematurely (for any reason), provide a closure to the
|
|
[`Engine`] via [`Engine::on_progress`].
|
|
|
|
The closure passed to [`Engine::on_progress`] will be called once for every operation.
|
|
|
|
Progress tracking is disabled with the [`unchecked`] feature.
|
|
|
|
|
|
Examples
|
|
--------
|
|
|
|
### Periodic Logging
|
|
|
|
```rust
|
|
let mut engine = Engine::new();
|
|
|
|
engine.on_progress(|count| { // parameter is number of operations already performed
|
|
if count % 1000 == 0 {
|
|
println!("{count}"); // print out a progress log every 1,000 operations
|
|
}
|
|
None // return 'None' to continue running the script
|
|
// return 'Some(token)' to immediately terminate the script
|
|
});
|
|
```
|
|
|
|
### Limit running time
|
|
|
|
```rust
|
|
let mut engine = Engine::new();
|
|
|
|
let start = get_time(); // get the current system time
|
|
|
|
engine.on_progress(move |_| {
|
|
let now = get_time();
|
|
|
|
if now.duration_since(start).as_secs() > 60 {
|
|
// Return a dummy token just to force-terminate the script
|
|
// after running for more than 60 seconds!
|
|
Some(Dynamic::UNIT)
|
|
} else {
|
|
// Continue
|
|
None
|
|
}
|
|
});
|
|
```
|
|
|
|
|
|
Function Signature of Callback
|
|
------------------------------
|
|
|
|
The signature of the closure to pass to [`Engine::on_progress`] is as follows.
|
|
|
|
> ```rust
|
|
> Fn(operations: u64) -> Option<Dynamic>
|
|
> ```
|
|
|
|
### Return value
|
|
|
|
| Value | Effect |
|
|
| :-----------: | -------------------------------------------------------------------------------- |
|
|
| `Some(token)` | terminate immediately, with `token` (a [`Dynamic`] value) as _termination token_ |
|
|
| `None` | continue script evaluation |
|
|
|
|
### Termination Token
|
|
|
|
```admonish info.side "Token"
|
|
|
|
The termination token is commonly used to provide information on the _reason_ behind the termination decision.
|
|
```
|
|
|
|
The [`Dynamic`] value returned is a _termination token_.
|
|
|
|
A script that is manually terminated returns with the error `EvalAltResult::ErrorTerminated(token, position)`
|
|
wrapping this value.
|
|
|
|
If the termination token is not needed, simply return `Some(Dynamic::UNIT)` to terminate the script
|
|
run with [`()`] as the token.
|