Acme-Parataxis
view release on metacpan or search on metacpan
lib/Acme/Parataxis/Error.pod view on Meta::CPAN
die $err; # real runtime bug; not an interruption
}
};
=head1 DESCRIPTION
Parataxis throws specialized error objects whenever a parked wait is interrupted by a deadline, an explicit
cancellation token, or a nursery sibling failure. All such errors descend from C<Acme::Parataxis::Error>.
A single C<< $err->isa('Acme::Parataxis::Error') >> check cleanly separates expected flow-control cancellations from
real application bugs. Standard runtime errors (plain string C<die>s or non-Parataxis exception objects) are never
swallowed or converted; they propagate unmodified.
Key characteristics:
=over
=item *
B<Clean interruption point>: The exception is thrown at the exact re-entry point of the interrupted wait. The operation
being waited on does not half-executeâit is aborted cleanly.
=item *
B<Transparent stringification>: All error subclasses overload C<""> to return C<message()>, allowing them to
interpolate naturally in logs, test assertions, and diagnostic warnings.
=item *
B<Rich wait metadata>: The C<wait_reason()> accessor exposes where and why the fiber was parked when interrupted,
including call-site file, line, and execution backtraces.
=back
The base class is an abstract parent and cannot be instantiated directly. All subclasses reside within this package
file; there are no separate F<.pm> files to load.
=head1 METHODS
=head2 C<message( )>
say $err->message;
# "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) {
die "Unexpected application failure: $err";
}
};
=head2 Extracting root failures from a broken nursery
my $err = do {
eval {
nursery( sub ($n) {
$n->spawn( sub { query_db() } );
$n->spawn( sub { ping_peer() } );
} );
};
$@;
};
if ( ref $err && $err->isa('Acme::Parataxis::Error::Nursery') ) {
my $cause = $err->primary; # the real culprit, skipping sibling cancellations
warn "Nursery failed due to: " . ( ref $cause ? $cause->message : $cause );
# Detailed breakdown of all children:
for my $child_err ( $err->failures ) {
warn " Child error: " . ( ref $child_err ? $child_err->message : $child_err );
}
}
=head1 Behavior Notes
=head2 C<__DIE__> hooks fire at every unwinding scope
Parataxis rethrows exceptions across scope boundaries (e.g. from the park re-entry, through the fiber envelope, across
C<await>, and out of C<with_timeout>). If a global C<$SIG{__DIE__}> handler is installed, it will fire on B<each>
( run in 0.981 second using v1.01-cache-2.11-cpan-234fa220139 )