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 )