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 )