Acme-Parataxis

 view release on metacpan or  search on metacpan

lib/Acme/Parataxis/Monitor.pod  view on Meta::CPAN

=pod

=encoding utf8

=head1 NAME

Acme::Parataxis::Monitor - Observe Fiber and Actor Terminations without Ownership

=head1 SYNOPSIS

    use v5.40;
    use Acme::Parataxis qw[async fiber await_sleep];
    use Acme::Parataxis::Monitor;

    async {
        my $worker = fiber {
            await_sleep(50);
            die "Worker failed catastrophically\n";
        };

        # Monitor the worker instead of awaiting it directly:
        my $watch = Acme::Parataxis::Monitor->new($worker);

        # Awaiting the monitor yields the exit error as a value; it does NOT rethrow:
        if ( my $err = $watch->await ) {
            say "Captured worker death: $err";
        }

        say "Scheduler run continues uninterrupted!";
    };

=head1 DESCRIPTION

An L<Acme::Parataxis::Monitor> provides non-intrusive observation of another concurrent entity (a fiber, future, or
actor), modeled after Erlang process monitors. It resolves exactly once when the target terminates: to C<undef> if the
target exited cleanly, or to the target's fatal exception if it crashed.

Crucially, a monitor delivers crashes as B<plain return values>, not rethrown exceptions. Direct awaiting of a failing
fiber (via C<< $fiber->await >>) propagates the exception up the awaiting stack and aborts the scheduler unless wrapped
in an C<eval>. Awaiting a monitor allows a coordinator fiber to inspect crashes safely without risking its own
unwinding.

Key characteristics:

=over

=item *

B<No ownership>: A monitor does not manage or control the target's lifecycle; it has no C<stop()> method and cannot
cancel the target.

=item *

B<Zero scheduler impact>: Monitors attach to existing completion hooks (C<on_ready> on fibers and futures; C<on_death>
on actors).

=item *

B<Safe against race conditions>: Monitoring a target that has already terminated resolves the monitor immediately
during C<new()>.

=item *



( run in 1.038 second using v1.01-cache-2.11-cpan-234fa220139 )