Acme-Parataxis
view release on metacpan or search on metacpan
lib/Acme/Parataxis/Local.pod view on Meta::CPAN
=pod
=encoding utf8
=head1 NAME
Acme::Parataxis::Local - Per-Fiber Storage Slots and Context Propagation
=head1 SYNOPSIS
use v5.40;
use Acme::Parataxis qw[async fiber];
use Acme::Parataxis::Local;
my $request_id = Acme::Parataxis::Local->new;
my $trace_id = Acme::Parataxis::Local->new( inherit => 1 );
async {
$request_id->set(42);
$trace_id->set('span-100');
fiber {
# Inherited slot carries the parent's value at spawn time:
say "Child trace: " . $trace_id->get; # span-100
# Uninherited slot starts empty (undef):
say "Child request: " . ($request_id->get // 'unset'); # unset
$request_id->set(99);
say "Child modified: " . $request_id->get; # 99
};
# Parent's slot remains untouched:
say "Parent request: " . $request_id->get; # 42
};
=head1 DESCRIPTION
C<Acme::Parataxis::Local> provides fiber-local storage, analogous to thread-local storage in multi-threaded runtimes. A
single C<Local> instance represents a variable that resolves to a private cell for each individual fiber.
Fibers never share or leak cells:
=over
=item * Writing to a C<Local> in a child fiber never overwrites the parent's or siblings' values.
=item * Unlike Perl's dynamic C<local>, the value follows the fiber's execution lifetime rather than the block scope.
It survives any number of C<await> and C<yield> boundaries.
=item * When a fiber terminates and is reaped, its local cells are cleaned up automatically, avoiding memory leaks in
long-running processes.
=back
=head1 Inheritance and Trace Propagation
Constructing a slot with C<inherit =E<gt> 1> enables automatic context propagation. When a fiber spawns a child fiber
via C<fiber { ... }>, C<spawn()>, an actor, or a nursery, all active inherited slots are shallow-copied into the
child's cell before its first statement runs.
This is the standard mechanism for passing request IDs, tracing spans, and security contexts down an asynchronous call
tree without manually threading parameters through every helper function. Once copied, the child owns its cell
( run in 0.791 second using v1.01-cache-2.11-cpan-234fa220139 )