third_party/rust/runloop/README.md

   1 # 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)
   2
   3 This crate provides a cancelable `RunLoop` to simplify writing non-blocking
   4 polling threads.
   5
   6 ## Usage
   7
   8 The closure passed to `RunLoop::new()` or `RunLoop::new_with_timeout()` will be
   9 called once and is executed in the newly spawned thread. It should periodically
  10 check, via the given callback argument named `alive` in the below examples,
  11 whether the runloop was requested to terminate.
  12
  13 `RunLoop::alive()` allows the owning thread to check whether the runloop is
  14 still alive. This can be useful for debugging (e.g. assertions) or early
  15 returns on failure in the passed closure.
  16
  17 `RunLoop::cancel()` will request the runloop to terminate. If the runloop is
  18 still active it will join the thread and block. If the runloop already
  19 terminated on its own this will be a no-op.
  20
  21 ### Example: An endless runloop
  22
  23 A runloop does not have to terminate on its own, it can wait until the
  24 `cancel()` method is called.
  25
  26 ```rust
  27 // This runloop runs until we stop it.
  28 let rloop = RunLoop::new(|alive| {
  29     while alive() { /* endless loop */ }
  30 })?;
  31
  32 // Loop a few times.
  33 thread::sleep_ms(500);
  34 assert!(rloop.alive());
  35
  36 // This will cause `alive()` to return false
  37 // and block until the thread was joined.
  38 rloop.cancel();
  39 ```
  40
  41 ### Example: A runloop with a timeout
  42
  43 Creating a runloop via `new_with_timeout()` ensures that `alive()` returns
  44 `false` after the given duration.
  45
  46 ```rust
  47 // This runloop will time out after 10ms.
  48 let rloop = RunLoop::new_with_timeout(|alive| {
  49     while alive() { /* endless loop */ }
  50 }, 10)?;
  51
  52 // Wait for the timeout.
  53 while rloop.alive() { /* loop */ }
  54
  55 // This won't block anymore, it's a no-op.
  56 // The runloop has already terminated.
  57 rloop.cancel();
  58 ```
  59
  60 ### Example: A runloop with channels
  61
  62 As a runloop will run the given closure in a newly spawned thread it requires
  63 channels and similar utilities to communicate back to the owning thread.
  64
  65 ```rust
  66 let (tx, rx) = channel();
  67
  68 // This runloop will send a lot of numbers.
  69 let rloop = RunLoop::new(move |alive| {
  70     let mut counter = 0u64;
  71     while alive() {
  72         tx.send(counter).unwrap();
  73         counter += 1;
  74     }
  75 })?;
  76
  77 // Wait until we receive a specific number.
  78 while rx.recv().unwrap() < 50 { /* loop */ }
  79
  80 // We've seen enough.
  81 rloop.cancel();
  82 ```
  83
  84 ## License
  85
  86 `runloop` is distributed under the terms of the Mozilla Public License, v. 2.0.
  87
  88 See [LICENSE](LICENSE) for details.