Acme-Parataxis
view release on metacpan or search on metacpan
lib/Acme/Parataxis/Generator.pod view on Meta::CPAN
=pod
=encoding utf8
=head1 NAME
Acme::Parataxis::Generator - Stackful, Lazily-Pulled Coroutine Iterators
=head1 SYNOPSIS
use v5.40;
use Acme::Parataxis::Generator;
my $fib = Acme::Parataxis::Generator->new( sub ($y) {
my ( $a, $b ) = ( 0, 1 );
while ( $a < 100 ) {
$y->($a);
( $a, $b ) = ( $b, $a + $b );
}
} );
my $total = 0;
while ( defined( my $n = $fib->next ) ) {
$total += $n;
}
say "Sum of Fibonacci numbers < 100: $total"; # 232
=head1 DESCRIPTION
A generator executes its producer body on an isolated, private coroutine fiber and produces values on demand. The body
is plain synchronous Perl: it can loop, return, call functions, and recurse deeply. Calling C<< $y->($value) >> from
any depth suspends the producer immediately, preserving lexical variables, loop states, and call frames intact. The
next invocation of C<< ->next >> resumes execution right where it paused.
Key properties:
=over
=item *
B<Lazy evaluation>: Nothing inside the body executes until the first call to C<next()>. An infinite sequence costs
nothing until pulled, and consumes only as much memory and CPU as needed for the values requested.
=item *
B<Full coroutine ergonomics>: Unlike shallow iterators, yielding is not restricted to the top-level block; helper subs
can accept C<$y> and yield on behalf of the generator.
=item *
B<Safe lifecycle teardown>: Abandoning an unexhausted generator cleanly drains the fiber: the yield site raises an
internal drain sentinel, unwinding lexical scopes and executing object destructors without leaking fibers.
=item *
B<Context independence>: Generators do not enter the scheduler run queue. They can be instantiated and pulled from
top-level mainline scripts, within C<async> blocks, inside spawned fibers, or inside nurseries.
=back
=head1 CONSTRUCTOR
=head2 C<new( sub ($y) { ... } )>
( run in 1.298 second using v1.01-cache-2.11-cpan-234fa220139 )