diff options
Diffstat (limited to 'third_party/rust/runloop/README.md')
| -rw-r--r-- | third_party/rust/runloop/README.md | 88 |
1 files changed, 88 insertions, 0 deletions
diff --git a/third_party/rust/runloop/README.md b/third_party/rust/runloop/README.md new file mode 100644 index 0000000000..8b9508b93b --- /dev/null +++ b/third_party/rust/runloop/README.md @@ -0,0 +1,88 @@ +# runloop [](https://crates.io/crates/runloop) [](https://travis-ci.org/ttaubert/rust-runloop) [](LICENSE) + +This crate provides a cancelable `RunLoop` to simplify writing non-blocking +polling threads. + +## Usage + +The closure passed to `RunLoop::new()` or `RunLoop::new_with_timeout()` will be +called once and is executed in the newly spawned thread. It should periodically +check, via the given callback argument named `alive` in the below examples, +whether the runloop was requested to terminate. + +`RunLoop::alive()` allows the owning thread to check whether the runloop is +still alive. This can be useful for debugging (e.g. assertions) or early +returns on failure in the passed closure. + +`RunLoop::cancel()` will request the runloop to terminate. If the runloop is +still active it will join the thread and block. If the runloop already +terminated on its own this will be a no-op. + +### Example: An endless runloop + +A runloop does not have to terminate on its own, it can wait until the +`cancel()` method is called. + +```rust +// This runloop runs until we stop it. +let rloop = RunLoop::new(|alive| { + while alive() { /* endless loop */ } +})?; + +// Loop a few times. +thread::sleep_ms(500); +assert!(rloop.alive()); + +// This will cause `alive()` to return false +// and block until the thread was joined. +rloop.cancel(); +``` + +### Example: A runloop with a timeout + +Creating a runloop via `new_with_timeout()` ensures that `alive()` returns +`false` after the given duration. + +```rust +// This runloop will time out after 10ms. +let rloop = RunLoop::new_with_timeout(|alive| { + while alive() { /* endless loop */ } +}, 10)?; + +// Wait for the timeout. +while rloop.alive() { /* loop */ } + +// This won't block anymore, it's a no-op. +// The runloop has already terminated. +rloop.cancel(); +``` + +### Example: A runloop with channels + +As a runloop will run the given closure in a newly spawned thread it requires +channels and similar utilities to communicate back to the owning thread. + +```rust +let (tx, rx) = channel(); + +// This runloop will send a lot of numbers. +let rloop = RunLoop::new(move |alive| { + let mut counter = 0u64; + while alive() { + tx.send(counter).unwrap(); + counter += 1; + } +})?; + +// Wait until we receive a specific number. +while rx.recv().unwrap() < 50 { /* loop */ } + +// We've seen enough. +rloop.cancel(); +``` + +## License + +`runloop` is distributed under the terms of the Mozilla Public License, v. 2.0. + +See [LICENSE](LICENSE) for details. |