Adding upstream version 124.0.1.upstream/124.0.1

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

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 [![Crates.io](https://img.shields.io/crates/v/runloop.svg)](https://crates.io/crates/runloop) [![Build Status](https://travis-ci.org/ttaubert/rust-runloop.svg?branch=master)](https://travis-ci.org/ttaubert/rust-runloop) [![License](https://img.shields.io/badge/license-MPL2-blue.svg?style=flat)](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.