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 )