#future #async #await #generator #yield

gen-z

Macro-free stream construction through asynchronous generators via an awaitable sender

1 unstable release

0.1.0 Oct 23, 2020

#386 in Asynchronous

MIT/Apache

7KB
52 lines

Generators are still unstable, and generating streams requires complicated ownership handling, so this crate aims to enable ad-hoc generation of streams.

Current async implementations attempt to provide yield syntax via macros, but this is not transparent to IDEs at the time of this library's creation, so gen_z attempts to work in a way that IDEs understand.

gen_z(|mut z| async move {
  let awaited = bar().await; // Make awaitable calls in the generator
  z.send(awaited).await; // Streams do not support responses; `yield` has output `()`
  // Share yield helper with calls, allowing them to emit outputs while producing values
  let shared_result = baz(&mut z).await;
  z.send(foo + shared_result).await;
  // Return is infallible; if `Result` is needed, wrap calls to comply with TryStream
}) // => Result is a futures::stream::Stream<Item = T>
  • Send is required for Stream::Item.
    • The stream is Send if the provided future is also Send.
  • Sync is available if Stream::Item and the future are both Sync.
  • The generator only requires FnOnce, so it may close over mutable references.
  • Infinite streams can be generated by looping within the provided future
  • Generators are infallible; the given future must return (), run forever, or panic.
    • To use Result<_, _>, create an inner-future which returns Result and convert an Err return to a type compatible with Stream::Item. TryStream compatibility can be achieved by setting the Stream::Item type to Result<T, TErr>.

Dependencies

~1MB
~16K SLoC