Crate event_iterator

Expand description

§Asynchronous lending iterator

A modified AsyncIterator or Stream using GATs to enable lending.

The primary trait provided by this crate is EventIterator.

§Getting Started

The following example shows how to implement and use an event iterator to print to stdout:

Hello, world!
Hello, again!

§Example

use core::{
    cell::Cell,
    pin::{pin, Pin},
    task::{Context, Poll},
};

use event_iterator::EventIterator;

/// An event iterator, for printing to stdout
#[derive(Default)]
pub struct Stdout {
    buffer: Cell<Option<String>>,
}

impl EventIterator for Stdout {
    type Event<'me> = Buffer<'me>;

    fn poll_next(
        self: Pin<&Self>,
        _cx: &mut Context<'_>,
    ) -> Poll<Option<Self::Event<'_>>> {
        let this = self.get_ref();

        // Print last buffer contents if set, set if unset
        this.buffer.set(if let Some(buffer) = this.buffer.take() {
            // This could be an asynchronous operation
            // Left synchronous for example simplicity
            println!("{buffer}");
            // Reuse buffer
            Some(buffer)
        } else {
            Some(String::new())
        });
        Poll::Ready(Some(Buffer(&this.buffer)))
    }
}

pub struct Buffer<'a>(&'a Cell<Option<String>>);

impl Buffer<'_> {
    pub fn write(&self, text: &str) {
        self.0.set(self.0.take().map(|mut buf| {
            buf.replace_range(.., text);
            buf
        }));
    }
}

#[async_main::async_main]
async fn main(_spawner: async_main::LocalSpawner) {
    let stdout = Stdout::default();

    // Overwrite buffer with text to print
    stdout.next_unpinned().await.unwrap().write("Hello, world!");
    stdout.next_unpinned().await.unwrap().write("Hello, again!");

    // Once more, to use the previous buffer contents
    let flush = pin!(stdout);

    flush.as_ref().next().await.unwrap();
}

Structs§

AsEventIter: Event iterator returned from AsEventIterator::as_event_iter()
Empty: Event iterator that yields nothing
Enumerate: Event iterator that yields the current count and event during iteration
Filter: Event iterator that filters the events of an event iterator with a predicate
FilterMap: Event iterator that uses a closure to both filter and map events
FromFn: Event iterator where each iteration calls the provided closure
FromIter: Event iterator that was created from an iterator
Fuse: Event iterator that returns Ready(None) forever after it’s finished
Inspect: Event iterator that calls a closure with a reference to each event
Map: Event iterator that maps the events with a closure
Next: Future to get the next event in an EventIterator
Once: Event iterator that yields a single event
OnceWith: Event iterator that yields a single event by polling a future
Pending: Event iterator that never produces an event and never finishes
PollFn: Event iterator that wraps a function returning Poll
Ready: Event iterator that is always ready with an event
Repeat: Event iterator that endlessly repeats a single event
RepeatWith: Event iterator where each iteration repeats the provided closure
Take: Event iterator that only yields a specified number of events
TakeWhile: Event iterator that only yields elements while a predicate returns true
Tear: Event iterator that returns Pending forever after it’s finished

Traits§

AsEventIterator: Trait for casting as an EventIterator
EventIterator: Asynchronous lending iterator

Functions§

empty: Create an event iterator that yields nothing.
from_fn: Create an event iterator where each iteration calls the provided closure.
from_iter: Convert an iterator into an event iterator.
once: Create an event iterator that yields a single event.
once_with: Create an event iterator that yields a single event by polling a future.
pending: Create an event iterator that never produces an event and never finishes.
poll_fn: Create an event iterator that wraps a function returning Poll.
ready: Create an event iterator that is always ready with an event.
repeat: Create an event iterator that endlessly repeats a single event.
repeat_with: Create an event iterator where each iteration repeats the provided closure.