#generator #async-await #yield #await #async #future

gen-z

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

1 unstable release

0.1.0 Oct 23, 2020

#1826 in Asynchronous

Download history 789/week @ 2023-12-01 909/week @ 2023-12-08 852/week @ 2023-12-15 795/week @ 2023-12-22 622/week @ 2023-12-29 711/week @ 2024-01-05 953/week @ 2024-01-12 962/week @ 2024-01-19 1150/week @ 2024-01-26 1121/week @ 2024-02-02 1089/week @ 2024-02-09 1606/week @ 2024-02-16 1246/week @ 2024-02-23 1118/week @ 2024-03-01 1040/week @ 2024-03-08 1079/week @ 2024-03-15

4,719 downloads per month
Used in 4 crates (3 directly)

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