Crate strawpoll

A wrapper to avoid spurious polling.

Sometimes, you have a future that itself contains smaller futures. When the larger future is polled, it polls those child futures to see if any of them have made progress. This can be inefficient if polling such a future is expensive; when the big future is woken up, it is usually because one of its child futures was notified, and ideally only that one future should be polled. Polling the other child futures that were not notified is wasting precious cycles.

This crate provides a wrapper for Future types, and other types that you may wish to call poll-like methods on. When you poll the inner Future through Strawpoll (or using Strawpoll::poll_fn), that poll call will immediately return with Poll::Pending if the contained future was not actually notified. In that case it will not poll the inner future.

Consider the following example where TrackPolls is some wrapper type that lets you measure how many times poll was called on it, and spawn is a method that lets you poll a Future without constructing a Context yourself.

use strawpoll::Strawpoll;

let (tx, rx) = oneshot::channel();
let mut rx = spawn(Strawpoll::new(TrackPolls::new(rx)));
assert_pending!(rx.poll());
assert_pending!(rx.poll());
assert_pending!(rx.poll());
// one poll must go through to register the underlying future
// but the _other_ calls to poll should do nothing, since no notify has happened
assert_eq!(rx.npolls, 1);
tx.send(()).unwrap();
assert_ready!(rx.poll()).unwrap();
// now there _was_ a notify, so the inner poll _should_ be called
assert_eq!(rx.npolls, 2);

Feature flags

• stream: Implements futures::Stream trait for Strawpoll.

Structs

Strawpoll

Polling wrapper that avoids spurious calls to poll on F.