Note that while you can also make a generator run or be waitable
in parallel using e.g. start(), the critical difference is in when resource
cleanup happens. If you start() the generator (or wrap the generator
function with task), its resources will be cleaned up when the generator
function exits.
With yield*, however (with or without fork), the resources are cleaned up
when the original calling job ends. And this is what you want when the
generator's return value is some kind of resource using other active
resources (such as event listeners rules, etc.) that need to remain active
for the caller.
(If you're familiar with the Effection framework, you may recognize this as
the difference between "actions" and "resources": in Uneventful we use
start() or task() for generators that return the result of an action, and
fork for generators that return a resource that will be owned by the
calling job.)
Wrap a generator, generator function, or generator method to run in parallel and have a result that can be waited on in parallel as well.
Normally, when you yield * to a generator in a job function, you're
pausing the current function until that generator is finished. And
normally, this is what you want, because you're not trying to do things in
parallel. But if you do want to do things in parallel, you need fork.
Generators also can't normally be waited on in parallel either: if multiple
jobs try to wait on an unfinished generator, the most likely result is an
error or data corruption. (Because the extra yield * operations will make
the generator think it's received data it was waiting for, causing all kinds
of havoc.)
So if you want a generator to either run in parallel or be waited on in
parallel (or both), you need to fork it: either on the consuming side by
wrapping a generator with fork(), or on the producing side by wrapping a
generator function (or decorating a generator method).
When called with a generator, fork returns a wrapped generator; when called
with a function, it returns a wrapped version of the function that will fork
its results. And when used as a decorator (@fork, compatible with both
TC39 and legacy decorator protocols), it wraps a method to fork its result as
well.
It is safe to call fork() more than once on the same generator, or to
fork() an already-forked generator: the result will always be the same as
the original fork.
Note that while you can also make a generator run or be waitable
in parallel using e.g. start(), the critical difference is in when resource
cleanup happens. If you start() the generator (or wrap the generator
function with task), its resources will be cleaned up when the generator
function exits.
With yield*, however (with or without fork), the resources are cleaned up
when the original calling job ends. And this is what you want when the
generator's return value is some kind of resource using other active
resources (such as event listeners rules, etc.) that need to remain active
for the caller.
(If you're familiar with the Effection framework, you may recognize this as
the difference between "actions" and "resources": in Uneventful we use
start() or task() for generators that return the result of an action, and
fork for generators that return a resource that will be owned by the
calling job.)
Wrap a generator, generator function, or generator method to run in parallel and have a result that can be waited on in parallel as well.
Normally, when you
yield *to a generator in a job function, you're pausing the current function until that generator is finished. And normally, this is what you want, because you're not trying to do things in parallel. But if you do want to do things in parallel, you needfork.Generators also can't normally be waited on in parallel either: if multiple jobs try to wait on an unfinished generator, the most likely result is an error or data corruption. (Because the extra
yield *operations will make the generator think it's received data it was waiting for, causing all kinds of havoc.)So if you want a generator to either run in parallel or be waited on in parallel (or both), you need to
forkit: either on the consuming side by wrapping a generator withfork(), or on the producing side by wrapping a generator function (or decorating a generator method).When called with a generator,
forkreturns a wrapped generator; when called with a function, it returns a wrapped version of the function that will fork its results. And when used as a decorator (@fork, compatible with both TC39 and legacy decorator protocols), it wraps a method to fork its result as well.It is safe to call
fork()more than once on the same generator, or tofork()an already-forked generator: the result will always be the same as the original fork.