Acme-Parataxis

 view release on metacpan or  search on metacpan

lib/Acme/Parataxis/Error.pod  view on Meta::CPAN

    # "The operation timed out at Semaphore down (t/worker.pl line 42)"

Returns the formatted diagnostic message containing the failure label and the wait site where the fiber was parked.

=head2 C<kind( )>

    if ( $err->kind eq 'timeout' ) { ... }

Machine-readable discriminator. Returns one of:

=over

=item * C<'cancelled'> - explicit cancellation token was triggered.

=item * C<'timeout'> - a C<with_timeout> deadline expired.

=item * C<'nursery'> - one or more sibling fibers died inside a nursery.

=item * C<'supervisor'> - a supervisor tree exhausted its restart budget.

=item * C<'stm_retry'> - internal control-flow signal used by STM transactions (never escapes C<atomically>).

=back

=head2 C<wait_reason( )>

    my ( $reason, $file, $line, $backtrace ) = @{ $err->wait_reason };

Returns the wait metadata recorded when the fiber parked:

=over

=item * C<$reason> - descriptive string (e.g. C<'await_sleep'>, C<'Channel get'>, C<'Semaphore down'>).

=item * C<$file> - filename where the wait was entered.

=item * C<$line> - source line number.

=item * C<$backtrace> - arrayref of C<[ $pkg, $file, $line, $sub ]> caller frames leading back to the fiber body.

=back

May be C<undef> for errors that did not originate from a parked wait (e.g. nursery aggregate errors).

=head1 SUBCLASSES

=head2 Acme::Parataxis::Error::Cancelled

Thrown when an explicit L<Acme::Parataxis::CancellationToken> is cancelled while a fiber is waiting.

=over

=item * C<< ->kind >> returns C<'cancelled'>.

=item * Message format: C<"The operation was cancelled at <site>">.

=item * Supports C<< ->new( wait_reason => $reason ) >> and C<< ->throw( ... ) >>.

=back

=head2 Acme::Parataxis::Error::Timeout

Thrown when a L<with_timeout|Acme::Parataxis/with_timeout> deadline expires before the enclosed block completes.

=over

=item * C<< ->kind >> returns C<'timeout'>.

=item * Message format: C<"The operation timed out at <site>">.

=item * C<Error::Timeout> is a B<sibling> of C<Error::Cancelled>, not a subclass. Do not use C<isa> to tell them apart;
switch on C<< ->kind >>.

=back

=head2 Acme::Parataxis::Error::Nursery

Thrown by L<nursery|Acme::Parataxis/nursery> when one or more enrolled child fibers die.

=over

=item * C<< ->kind >> returns C<'nursery'>.

=item * C<< ->primary >>: Returns the first I<natural> failure (the non-cancellation exception that caused the nursery
to abort, rather than the cancelled sibling unwinds).

=item * C<< ->failures >>: Returns the list of every child exception in enrollment order.

=back

=head2 Acme::Parataxis::Error::Supervisor

Thrown by an L<Acme::Parataxis::Supervisor> when a supervised subtree exhausts its allocated restart budget.

=over

=item * C<< ->kind >> returns C<'supervisor'>.

=item * C<< ->child >>: Returns the name of the child whose death exhausted the budget.

=item * C<< ->primary >>: Returns the exception that triggered the final failed restart.

=item * C<< ->failures >>: Returns every error that counted against the restart budget during the tracking window.

=back

=head2 Acme::Parataxis::Error::STM_Retry

Internal control-flow exception thrown by C<retry()> inside an C<atomically> block. Caught internally by the STM engine
to roll back speculative writes, park on the transaction's read set, and retry. Never escapes C<atomically>.

=head1 Recipes

=head2 Differentiating cancellations from timeouts and runtime errors

    use v5.40;
    use Acme::Parataxis qw[async with_timeout];

    async {
        my $res = eval {
            with_timeout( 5000, $cancel_token, sub {
                fetch_remote_resource();
            } );
        };
        my $err = $@;

        if ( ref $err && $err->isa('Acme::Parataxis::Error') ) {
            if    ( $err->kind eq 'timeout' )   { warn "Request timed out after 5s; retrying..." }
            elsif ( $err->kind eq 'cancelled' ) { warn "Request explicitly cancelled by caller" }
        }
        elsif ($err) {



( run in 0.921 second using v1.01-cache-2.11-cpan-234fa220139 )