Acme-Parataxis
view release on metacpan or search on metacpan
lib/Acme/Parataxis/Error.pod view on Meta::CPAN
=pod
=encoding utf8
=head1 NAME
Acme::Parataxis::Error - Base Class and Diagnostics for Interrupted Fiber Waits
=head1 SYNOPSIS
use v5.40;
use Acme::Parataxis qw[async with_timeout];
async {
my $err = do {
eval { with_timeout( 250, sub { $slow_task->run } ) };
$@;
};
if ( ref $err && $err->isa('Acme::Parataxis::Error') ) {
say "Kind: " . $err->kind; # 'timeout'
say "Message: " . $err->message; # "The operation timed out at ..."
say "Interrupted: " . $err->wait_reason->[0]; # 'await_sleep', 'Semaphore down', etc.
say "Stringified: $err"; # stringifies to ->message
}
elsif ($err) {
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.
( run in 1.359 second using v1.01-cache-2.11-cpan-234fa220139 )