Acme-Parataxis
view release on metacpan or search on metacpan
lib/Acme/Parataxis/Generator.pod view on Meta::CPAN
=head2 C<is_done( )>
while ( !$gen->is_done ) {
my $v = $gen->next;
process($v) if defined $v;
}
Returns true if the generator has finished execution (whether it returned normally or threw an exception), and false if
it is still suspended awaiting the next pull.
=head2 C<fiber( )>
Returns the underlying private C<Acme::Parataxis> fiber object. Intended for debugging and ID inspection.
=head1 Recipes
=head2 Safely consuming sequences that contain C<undef>
The idiom C<< while ( defined(my $v = $gen->next) ) >> halts prematurely if the sequence legitimately yields C<undef>.
Test C<is_done()> instead:
sub drain ($gen) {
my @items;
while (1) {
my $val = $gen->next;
last if $gen->is_done;
push @items, $val;
}
return @items;
}
my $gen = Acme::Parataxis::Generator->new( sub ($y) {
$y->('alpha');
$y->(undef);
$y->('omega');
} );
my @values = drain($gen); # [ 'alpha', undef, 'omega' ]
=head2 Composing lazy generator pipelines
my $cubes = Acme::Parataxis::Generator->new( sub ($y) {
my $ints = Acme::Parataxis::Generator->new( sub ($z) {
my $i = 1;
while (1) { $z->($i++) }
} );
while ( defined( my $n = $ints->next ) ) {
$y->( $n ** 3 );
}
} );
say $cubes->next for 1 .. 4; # 1, 8, 27, 64
=head2 Exception propagation preserving error objects
use Acme::Parataxis::Error;
my $gen = Acme::Parataxis::Generator->new( sub ($y) {
$y->(1);
Acme::Parataxis::Error::Timeout->throw( seconds => 5 );
} );
say $gen->next; # 1
eval { $gen->next };
if ( my $err = $@ ) {
say "Caught typed error: " . $err->kind; # 'timeout'
}
=head1 Behavior Notes
=over
=item * Body return values are discarded
A generator's output must be produced via C<< $y->(...) >>. If a body terminates via C<return $val>, that final return
value is ignored, and the next C<next()> returns C<undef>. Always yield the final value before returning.
=item * Do not park inside a generator body
Generators run outside the cooperative scheduler queue. Calling cooperative parking primitives (C<await_sleep>,
C<await_read>, or channel C<get>) inside a generator injects scheduler control tokens (such as C<'WAITING'>) into the
sequence as yielded values. Keep the generator body synchronous; perform async I/O on the consumer side.
=item * Abandoned generators drain on destruction
If a generator goes out of scope while suspended at a yield point, its C<DESTROY> handler resumes the private fiber
with an internal drain sentinel. This causes the yield call to throw internally, allowing enclosing scopes,
destructors, and C<finally> blocks in the generator to execute cleanups.
=item * Reserved fiber 0 on Windows
On Windows, longjmp-based unwinding across the very first fiber in a process (ID 0) can bypass anchored exception
traps. To guarantee stability, the first generator allocated at the mainline permanently reserves fiber ID 0, ensuring
generators always execute on fiber ID 1 or higher. Inside a scheduled C<run()> block, the root fiber already holds ID
0, so no extra reservation is created.
=back
=head1 SEE ALSO
L<Acme::Parataxis>, L<Acme::Parataxis::Channel>, L<Acme::Parataxis::Stream>
=head1 AUTHOR
Sanko Robinson L<https://github.com/sanko>
=head1 LICENSE
Copyright (C) Sanko Robinson.
This library is free software; you can redistribute it and/or modify it under the terms found in the Artistic License
2.
=cut
( run in 0.798 second using v1.01-cache-2.11-cpan-234fa220139 )