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 )