Propane is a thin wrapper around the unstable generator feature, allowing users to create free functions as generators. It implements a particular idea for how generators should be designed; a big part of why generators are still unstable today is that these design questions are still undecided.
The syntax looks like this:
#[propane::generator]
fn foo() -> i32 {
for n in 0i32..10 {
yield n;
}
}Because it is a macro, it does not work as well as a native language feature would, and has worse error messages.
Propane is designed to allow users to write generators for the purpose of implementing iterators. For that reason, its generators are restricted in some important ways. These are the intentional design restrictions of propane (that is, these are not limitations because of bugs, they are not intended to be lifted):
- A propane generator becomes a function that returns an
impl Iterator; the iterator interface is the only interface users can use with the generator's return type. - A propane generator can only return
(), it cannot yield one type and then return another interesting type. The?operator yields the error and then, on the next resumption, returns. - A propane generator implements Unpin, and cannot be self-referential (unlike async functions).
Because of the signature of Iterator::next, it is always safe to move iterators between calls to
next. This makes unboxed, self-referential iterators unsound. We did not have Pin when we
designed the Iterator API.
However, in general, users can push unowned data outside of the iterator in a way they can't with
futures. Futures, usually, ultimately have to be 'static, so they can spawned, but iterators
usually are consumed in a way that does not require them to own all of their data.
Therefore, it is potentially the case that generators restricted to not contain self-references are sufficient for this use case. Propane intends to explore that possibility.