Crate suspend

Expand description

This crate provides various utilities for moving between async and synchronous contexts.

§Examples

The Task structure allows a Future or a polling function to be evaluated in a blocking manner:

use suspend::Task;
use std::time::Duration;

let task = Task::from_future(async { 100 }).map(|val| val * 2);
assert_eq!(task.wait_timeout(Duration::from_secs(1)), Ok(200));

Similarly, the Iter structure allows a Stream instance to be consumed in an async or blocking manner:

use suspend::{Iter, block_on};

let mut values = Iter::from_iterator(1..);
assert_eq!(block_on(async { values.next().await }), Some(1));
assert_eq!(values.take(3).collect::<Vec<_>>(), vec![2, 3, 4]);

The Suspend structure may be used to coordinate between threads and Futures, allowing either to act as a waiter or notifier:

use std::time::Duration;
use suspend::{Suspend, block_on};

let mut susp = Suspend::new();
let notifier = susp.notifier();

// start listening for notifications
let mut listener = susp.listen();
// send a notification (satisfies the current listener)
notifier.notify();
// wait for notification (already sent) with a timeout
assert_eq!(listener.wait_timeout(Duration::from_secs(1)), true);
drop(listener);

let mut listener = susp.listen();
notifier.notify();
// the listener is also a Future
block_on(async { listener.await });

Re-exports§

pub use oneshot_rs as oneshot;

Structs§

Iter: A stream which may be polled asynchronously, or by using blocking operations with an optional timeout.
Listener: The result of acquiring a Suspend using either Suspend::listen or Suspend::try_listen. It may be used to wait for a notification with .await or by parking the current thread.
Next: A Future representing the next item in an Iter stream.
Notifier: An instance of a notifier for a Suspend instance. When notified, the associated thread or Future will be woken if currently suspended.
RecvError: An error returned if the associated oneshot::Sender is dropped. Requires the oneshot feature. An error returned from the indefinitely blocking recv functions on a [Receiver].
Sender: A oneshot::Sender used to provide a single asynchronous result. Requires the oneshot feature.
Suspend: A structure which may be used to suspend a thread or Future pending a notification.
Task: An asynchronous result which may be evaluated with .await, or by using blocking operations with an optional timeout.
TimeoutError: A timeout error which may be returned when waiting for a Suspend or Iter with a given timeout.

Functions§

block_on: A convenience method to evaluate a Future, blocking the current thread until it is resolved.
iter_stream: A convenience method to turn a Stream into an Iterator which parks the current thread until items are available.
notify_once: Create a new single-use Notifier and a corresponding Task. Once notified, the Task will resolve to ().
ready: A convenience method to create a new Task from a result value.
sender_task: Create a new oneshot message pair consisting of a Sender and a Task<T>. Once Sender::send is called or the Sender is dropped, the Task will resolve to the sent message or a RecvError. Requires the oneshot feature.

Type Aliases§