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 )