Acme-Parataxis

 view release on metacpan or  search on metacpan

CONTRIBUTING.md  view on Meta::CPAN

# Contributing to Acme::Parataxis

Thanks for your interest in contributing! This guide covers how to set up a
development environment, run the test suite, and submit changes.

## Getting started

### Prerequisites

- Perl **5.40+** (the code uses native `class`/`method` syntax)
- A C compiler
- Recommended: `cpanm` (or `cpan`) to install development dependencies

### Install

From a clone of the repository:

Changes.md  view on Meta::CPAN


## [v0.1.1] - 2026-10-25

Borrowing patterns from Rust, Erlang, Java, etc. to bring more familiar concurrency primitives to Parataxis. No real changes to the core this time.

### Added

- `Acme::Parataxis::Blocking`: CPU offloading onto a bounded pool of cloned interpreters via `spawn_blocking` (lazily loads threads/shared modules on first use).
- `spawn_blocking_fork`: Process-based CPU offloading for non-ithreads Perls with IPC via `Storable`, bounded worker pools, and signal-based cancellation via `kill_blocking_fork`.
- `Acme::Parataxis::Actor`: Mailbox-driven actors with bounded queues, backpressure, `ask` (returning a `Future`), `send`, and graceful teardown.
- `Acme::Parataxis::Supervisor`: OTP-style supervision trees supporting `OneForOne`, `OneForAll`, and `RestForOne` restart strategies with configurable restart budgets.
- Synchronization primitives:
  - `Acme::Parataxis::Sync::Mutex`: Non-reentrant lock with strict FIFO hand-off and ownership tracking.
  - `Acme::Parataxis::Sync::RwLock`: Writer-preferring, reentrant read/write lock.
  - `Acme::Parataxis::Sync::WaitGroup`: Fiber job counter (`add`, `done`, `wait`).
  - `Acme::Parataxis::Sync::Barrier`: Reusable phase rendezvous point.
  - `Acme::Parataxis::Sync::Once`: Race-safe, single-execution initializer.
- Structured concurrency & flow control:
  - `nursery( sub ($n) { ... } )`: Structured fiber scopes where child errors cancel siblings and propagate outward.
  - `pmap( { concurrency => $n, }, sub ( $item ) { ... }, @items )`: Parallel list mapping over a bounded fiber pool.
  - `with_timeout( $ms, [ $token, ] $code )` and `with_cancel( $code )`: Cooperative deadline and cancellation scopes.

Changes.md  view on Meta::CPAN

- Fixed `Can't undef active subroutine during global destruction` when multiple fibers park concurrently in the same CV (Pass 1c depth settlement).
- Traversed nested runlevels (`si_prev`/`si_next`) during depth settlement to prevent `cx_popsub_args` assertion failures inside test subtest blocks.

### Changed

- Maximum fiber limits are now dynamic: configurable via `max_fibers()` and `set_max_fibers()`.
- Increased default fiber limit from 1,024 to 65,536.

## [v0.1.0] - 2026-09-21

This started as a silly little diversion in February but I'm using this in actual projects now. I've even used it to shake out bugs in Affix.

I might move it out of the Acme namespace...

Anyway, the major win is that fiber hot path has been moved from Perl into C and roughly tripled context swapping throughput with no change to the public API.

### Added

- `Acme::Parataxis::Channel`: a buffered FIFO message queue for producer/consumer patterns between fibers. Writers block when full, readers when empty; a capacity of `1` makes it a rendezvous point. Built on two semaphores.
- `Acme::Parataxis::Future`: a one-shot placeholder for an eventual computation result. A producer fires `set_result`/`set_error` exactly once; consumers pick it up with `await`/`result` or register an `on_ready` callback.
- `Acme::Parataxis::Semaphore`: a counting semaphore with no ownership: blocked fibers are parked (no busy-wait) and resumed FIFO as permits become available.

Changes.md  view on Meta::CPAN


### Fixed

- Fixed crash (double-free / use-after-free) when fibers call Affix'd functions on non-threaded Perl. The bug was in Affix's `SAVEVPTR`/`SAVEDESTRUCTOR_X` arena pattern, which was not fiber-safe; now fixed upstream in Affix v1.2.5+.
- Fixed SIGSEGV on macOS and FreeBSD caused by fiber stacks being only 512KB (via `posix_memalign`). All POSIX platforms now use a 64MB `mmap`-backed stack with a PROT_NONE guard page, matching the Linux path. The SIGSEGV guard handler is also availa...
- Fixed FreeBSD compilation: added `MAP_ANONYMOUS` w/ `MAP_ANON` fallback.
- Fixed macOS SIGBUS: the guard region size is now derived from `sysconf(_SC_PAGESIZE)` at runtime so it always covers at least one full page (16 KiB on Apple Silicon). Also fixed `cleanup()` to use `munmap()` instead of `free()` on non-Linux POSIX p...
- `is_finished()` now rejects fiber ids of `MAX_FIBERS` or greater instead of reading out of bounds of the fiber table.
- Closed a busy-spin footgun: `wait`, fiber `await`, `Semaphore` waits, and `Signal->wait` now croak instead of burning 100% CPU when called from outside the scheduler, and `->new` croaks when the 1024-slot fiber table is exhausted rather than creati...
- A fiber that yields during its initial run is now re-enqueued by the scheduler instead of being dropped, which previously could hang a regex-heavy workload.
- The scheduler no longer hangs when a fiber object is created but never spawned (`->new` without `spawn`): live-fiber tracking only counts fibers that have actually started, matching Coro's ready-queue semantics.
- `async`/`run` is now re-entrant: a nested `async` inside another `async` or inside a fiber shares the one run loop (like Coro's single global scheduler) and returns the block's value, instead of clobbering the outer scheduler and deadlocking.
- A destroyed fiber's id is kept out of the free list until every job it submitted has been reclaimed, so a stale completion can never be misdelivered to a (or corrupt) fiber that later reuses the id.
- Pending-job tracking now reads the C-side outstanding job count instead of a run-local counter, so jobs left over from a `stop`ped run are drained and handled by the next run instead of tripping `FATAL: deadlock detected` or sitting in the done-que...
- `Semaphore` `up`/`adjust` skip stale (already destroyed) waiters instead of consuming a wake that should go to a live fiber.
- Channel constructors now reject a capacity below 1 instead of deadlocking on it at load time.
- The 1024-slot job queue is no longer fatal on the first try: `_submit_job` yields once and retries before croaking.
- `Future::set_result`/`set_error` wake awaiters exactly once instead of appending a duplicate `_wake_waiters` callback on every `await`.

### Changed

README.md  view on Meta::CPAN


Acme::Parataxis - Lightweight Cooperative Fibers

# SYNOPSIS

```perl
use v5.40;
use Acme::Parataxis qw[:all];
$|++;
async {
    say 'Main task started';
    my $f1 = fiber {
        say '  Task 1: Sleeping...';
        await_sleep(1000);
        say '  Task 1: Waking up';
        return 'Coffee!';
    };
    my $f2 = fiber {
        say '  Task 2: Calculating... (simulated CPU work)';
        my $sum = 0;
        for ( 1 .. 100 ) {

README.md  view on Meta::CPAN

        }
        say '  Task 2: Complete. Will return ' . $sum;
        return $sum;
    };

    # await works on fibers and futures
    say 'Result 1: ' . await($f1);
    say 'Result 2: ' . await($f2);
};
# Output:
# Main task started
#   Task 1: Sleeping...
#   Task 2: Calculating... (simulated CPU work)
#   Task 2: Complete. Will return 5050
#   Task 1: Waking up
# Result 1: Coffee!
# Result 2: 5050
```

# DESCRIPTION

README.md  view on Meta::CPAN

and nothing requires more fiddling than picking up the full context and swapping it around at runtime.

# FUNCTIONS

Importable individually or with the `:all` tag.

## `async { ... }`

```
async {
    # scheduler starts, executes block as the root fiber, and stops when finished
};
```

Convenience wrapper around `run()`. Executes the provided code block as the initial root fiber of a new scheduler
session and stops the scheduler once the block returns or dies.

## `fiber { ... }`

```perl
my $f = fiber {

eg/basic.pl  view on Meta::CPAN

use v5.40;
use blib;
use Acme::Parataxis;
#
say 'Main thread (TID: ' . Acme::Parataxis->tid . ')';

# Create a worker parataxis
my $worker = Acme::Parataxis->new(
    code => sub ($name) {
        say "---> Worker '$name' started (FID: " . Acme::Parataxis->current_fid . ")";
        for my $i ( 1 .. 3 ) {
            say "---> Worker '$name' processing step $i";
            my $input = Acme::Parataxis->yield( 'Result from step ' . $i );
            say "---> Worker '$name' received: $input";
        }
        return 'Final success';
    }
);

# Drive the worker

eg/bench_offload.pl  view on Meta::CPAN

#     inline (1 fiber)      1222.5 ms   1.00x     <- the thing you already have
#     fibers x2             1223.3 ms   1.00x
#     fibers x4             1223.2 ms   1.00x
#     fibers x8             1200.9 ms   0.98x
#     fibers x15            1210.1 ms   0.99x
#     pmap concurrency 4    1191.7 ms   0.97x     <- the dist's own helper; same story
#     processes x4           332.5 ms   0.27x
#     processes x8           254.8 ms   0.21x
#     processes x15          191.8 ms   0.16x     <- 6.2x, and not 15x
#
#   Wait-bound - 8 independent services, 40ms each, latency starting when the request is sent:
#
#     blocking serial        327.4 ms   1.00x
#     fibers + await_read     45.0 ms   0.14x     <- 7.3x
#     processes x8             51.2 ms   0.16x
#
# Three things to take from it:
#
#   1. Fibers are not parallelism. A fiber is a coroutine on the same OS thread, so adding more
#      of them cannot reach a second core - the x2/x4/x8/x15 rows are flat to within a percent
#      because they are the same thread, not a slower one. pmap is flat for the same reason.

eg/bench_offload.pl  view on Meta::CPAN

#     spawn_blocking x15     253.8 ms   0.21x    <- 4.9x
#
# So a thread does buy the second core, and the process rows above remain the right upper bound.
# Three caveats matter more than that 4.9x, though:
#
#   * It is 1.19x SLOWER at one thread, because a call costs 9.8ms end to end here, which puts
#     the crossover at roughly 10ms of work per item. 6.7ms of that 9.8ms is threads->create
#     cloning the parent interpreter; only 2.4ms is the Blocking layer around it. The clone is
#     the expensive part and it scales with what the parent has loaded - the same create+join
#     costs 0.65ms in a bare interpreter and 6.7ms with this distribution loaded. One thread per
#     small item spends 10x the work before it starts.
#   * A fiber round trip is 0.003ms. One spawn_blocking is about 3300 of them.
#   * The 4.9x is Digest::SHA releasing the GIL, not threads being magic. The same pure-perl
#     closure through spawn_blocking gains nothing (0.96x), and 8 plain threads on a pure-perl
#     loop are 1.48x SLOWER than a single thread. A thread helps exactly where the XS underneath
#     the closure drops the GIL - I/O and some CPU - and not at all for work computed in perl.
#
# Run it: perl -Mblib eg/bench_offload.pl
# Slow machine, or a shared one? Scale the work down; the ratios are what matter, not the ms:
#   perl -Mblib eg/bench_offload.pl 3 8 65536 20
use v5.40;

eg/bench_offload.pl  view on Meta::CPAN

for my $k ( 4, 8, $cores ) {
    next if $seen{"p$k"}++ || $k > $TREE || !$REAL_FORK;
    push @cpu, [
        "processes x$k",
        sub {
            my @pid;
            for my $i ( 0 .. $k - 1 ) {
                my $pid = fork();
                die "fork: $!" if !defined $pid;

                # POSIX::_exit, never exit. An earlier variant in this file has already started
                # the worker thread pool, and a forked child inherits whatever mutex one of the
                # parent's threads was holding. Let the child reach exit and it runs global
                # destruction against that held lock, so it hangs - and the parent hangs in
                # waitpid waiting for it. The result is not a slow benchmark but a deadlock, and
                # from the outside the two look identical.
                if ( !$pid ) { hash_subset( subset( $i, $k ) ); POSIX::_exit(0) }
                push @pid, $pid;
            }
            waitpid $_, 0 for @pid;
        }

eg/bench_offload.pl  view on Meta::CPAN

            }
            waitpid $_,      0 for @kid;
            waitpid $_->[2], 0 for @svc;
        }
    ];
}
if ( !@wait ) {
    print "\n=== Wait-bound: $N services, $RTT ms each -- skipped on $^O: the fixture is one forked service per pipe ===\n";
}
else {
    printf "\n=== Wait-bound: %d services, %dms each, latency starts at the request ===\n", $N, $RTT;
    printf "  %-20s %10s %9s   %s\n", 'variant', 'min ms', 'ratio', 'spread ms';
    my $wbase;
    for my $w (@wait) {
        my ( $name, $code )   = @$w;
        my ( $min,  $spread ) = timed($code);
        $wbase //= $min;
        printf "  %-20s %10.1f %8.2fx   %.1f\n", $name, $min, $min / $wbase, $spread;
    }
}
print <<'REPORT';

eg/db_driver.pl  view on Meta::CPAN

close $pfh;

# The database program goes in a file, not on a -e. Handing a multi-line program
# to the child as one command-line argument means trusting the platform to keep
# the newlines through the round trip, and it does not: on Windows the argument
# is re-split and the child was handed "use" as its whole program, dying with
# "syntax error at -e line 1, at EOF". A file path cannot be mangled that way.
my ( $sfh, $spath ) = tempfile( 'parataxis-db-server-XXXXXX', TMPDIR => 1, UNLINK => 1 );
print $sfh $SERVER or die "cannot write the database program: $!";
close $sfh         or die "cannot write the database program: $!";
open my $child, '-|', $^X, $spath, $ppath, $QUERY_LATENCY_MS or die "cannot start the database: $!";
for ( 1 .. 200 ) {
    if ( open my $rfh, '<', $ppath ) {
        chomp( my $l = <$rfh> // '' );
        close $rfh;
        if ( $l && $l =~ /\A([0-9]+)\z/ ) { $PORT = $1; last }
    }
    select undef, undef, undef, 0.05;
}
die "the database never reported a port\n" if !$PORT;
say "parataxis database driver: talking to a blocking server on 127.0.0.1:$PORT";

eg/fork_offload.pl  view on Meta::CPAN

        else                       { die "unknown option '$arg'\n" }
    }
}
die "--pool must be >= 1\n" if $POOL < 1;
die "--jobs must be >= 1\n" if $JOBS < 1;

# Any pure-Perl number crunch the scheduler should not have to babysit. The
# wall-clock loop is used (not sleep) so the work is visible to the scheduler
# AND to with_timeout, exactly as a real heavy routine would be. The sum folds
# the tag in, so every result is individually checkable after it crosses back.
# $start/$end come back too: a child cannot increment a counter in its parent
# (that would be writing to memory it does not own), so concurrency is measured
# from the windows the children actually ran in, and the cap is checked against
# those rather than against a shared tally that would always read zero.
sub churn ( $tag, $ms ) {
    my $start = time();                # not $^T: that is the parent's, and every child inherits it
    my $end   = $start + $ms / 1000;
    my $sum   = 0;
    1 while time() < $end && ( $sum = ( $sum * 31 + $tag ) % 2147483647 );
    return { tag => $tag, sum => $sum, pid => $$, start => $start, end => time() };
}
my $cap = set_max_blocking_forks($POOL);
die "set_max_blocking_forks($POOL) reported $cap" unless $cap == $POOL;
my $ticks = 0;
my $done  = 0;
my $rv    = run(
    sub {
        # $JOBS closures out, only $POOL children at home: the pool is a
        # Semaphore, so the callers that oversubscribe it park at spawn and the
        # bound is a real concurrency cap, not an admission plea.

eg/fork_offload.pl  view on Meta::CPAN

            delivered  => $delivered,
            killed     => $killed,
            kill_took  => $kill_took,
            kill_err   => $err,
            after_kill => $after_kill,
        };
    }
);

# The concurrency cap, reconstructed from the windows each child reported. Walk
# the start/stop endpoints and take the deepest overlap; with $POOL children
# allowed it must never exceed $POOL, and it must exceed zero or the closures
# did not really overlap at all.
my $high = 0;
{
    my @events = map { ( [ $_->{start}, +1 ], [ $_->{end}, -1 ] ) } @{ $rv->{out} };
    my $depth  = 0;
    for my $e ( sort { $a->[0] <=> $b->[0] || $a->[1] <=> $b->[1] } @events ) {
        $depth += $e->[1];
        $high = $depth if $depth > $high;
    }
}
my $fail = 0;
sub problem ($msg) { print "verify FAIL: $msg\n"; ++$fail }
my @out = @{ $rv->{out} };
problem "expected $JOBS results, got " . scalar @out unless @out == $JOBS;

eg/future.pl  view on Meta::CPAN

use v5.40;
use lib 'lib';
use blib;
use Acme::Parataxis qw[:all];
use Acme::Parataxis::Future;
$|++;
async {
    say 'Main: starting...';

    # A future produced by a background fiber...
    my $fetch = Acme::Parataxis::Future->new;

    # ...and registered for a side effect when it lands.
    $fetch->on_ready( sub ($f) { say '  on_ready: future resolved with ' . $f->result } );
    fiber {
        say '  Producer: doing slow work elsewhere...';
        await_sleep(200);
        $fetch->set_result('fresh data');

eg/http_tiny.pl  view on Meta::CPAN

    }
}
#
package My::HTTP::Handle {
    use parent -norequire, 'HTTP::Tiny::Handle';
    use Time::HiRes     qw[time];
    use Acme::Parataxis qw[await_read await_write];

    sub _do_timeout ( $self, $type, $timeout //= $self->{timeout} // 60 ) {
        if ( $self->{fh} ) {
            my $start = time;
            while (1) {

                # Check for readiness NOW (0 timeout)
                return 1 if $self->SUPER::_do_timeout( $type, 0 );

                # Check for overall timeout
                my $elapsed = time() - $start;
                return 0 if $elapsed > $timeout;

                # Suspend fiber and wait for background I/O check.
                # This is where the magic happens: the fiber yields control back
                # to the scheduler while waiting for the socket to be ready.
                my $wait = ( $timeout - $elapsed ) > 0.5 ? 0.5 : ( $timeout - $elapsed );
                if ( $type eq 'read' ) {
                    await_read( $self->{fh}, int( $wait * 1000 ) );
                }
                else {

eg/http_tiny.pl  view on Meta::CPAN

    my @urls = qw[
        http://www.google.com
        http://www.example.com
        https://www.perl.org
        https://metacpan.org
    ];
    my @futures;

    for my $url (@urls) {
        push @futures, fiber {
            my $start = time();
            say sprintf '  [Fiber %d] Fetching %s...', current_fid(), $url;
            my $res     = $http->get($url);
            my $elapsed = time() - $start;
            say sprintf '  [Fiber %d] Done %s (Status: %d) in %.2fs', current_fid(), $url, $res->{status}, $elapsed;
            return $res;
        };
    }

    # Wait for all fibers to complete and collect results
    for my $i ( 0 .. $#urls ) {
        my $res = await $futures[$i];
        say sprintf 'Final Result for %s: %d %s', $urls[$i], $res->{status}, $res->{reason};
    }

eg/modern.pl  view on Meta::CPAN

use v5.40;
use blib;
use Acme::Parataxis qw[:all];
#
async {
    say 'Main fiber started';
    my $f1 = fiber {    # spawn a new OS fiber
        say '  Fiber 1: Sleeping...';
        await_sleep(1000);
        say '  Fiber 1: Woke up!';
        return 42;
    };
    my $res1 = await $f1;    # wait for results
    say 'Main: Fiber 1 returned ' . $res1;
    say 'Creating a manual fiber for bidirectional communication...';

eg/multi_tail.pl  view on Meta::CPAN

my $dir   = tempdir( 'parataxis-mtail-XXXXXX', CLEANUP => 0, TMPDIR => 1 );
my @NAMES = qw[app.log web.log err.log];
my @paths = map { File::Spec->catfile( $dir, $_ ) } @NAMES;
for my $p (@paths) {    # loggers pre-exist: a tail must never race their creation
    open my $fh, '>', $p or die "cannot seed $p: $!\n";
    close $fh;
}
my @TAGS        = qw[conn http err];
my $out         = Acme::Parataxis::Channel->new( capacity => 1024 );
my $writer_done = 0;
my $start       = time();

sub writer_fiber {
    my @done    = ( 0, 0, 0 );
    my $rotated = 0;
    while ( $done[0] + $done[1] + $done[2] < 3 * $LINES ) {
        my $slot = int rand 3;
        next if $done[$slot] >= $LINES;
        $done[$slot]++;
        my $text = sprintf '%s.%d', $TAGS[$slot], $done[$slot];
        open my $fh, '>>', $paths[$slot] or die "cannot append $paths[$slot]: $!\n";

eg/multi_tail.pl  view on Meta::CPAN

        spawn( sub { $_->await for @tails; $out->shutdown; 1 } );    # reaper: close the stream
        my $seen  = 0;                                               # lines on the channel = filter/annotate stage input
        my $shown = 0;
        while ( defined( my $ent = $out->get ) ) {
            $seen++;
            next if defined $MATCH && $ent->{text} !~ $MATCH;
            $shown++;
            printf "%-4d %-20s %s\n", $seen, $ent->{file}, $ent->{text};
        }
        $_->await for @tails;
        my $elapsed = time() - $start;
        say sprintf "\n%d line(s) streamed through %d tail fiber(s) in %.2fs", $seen, scalar @NAMES, $elapsed;
        say "$shown shown" if defined $MATCH;
        say "(scheduler: 1 OS thread, ", Acme::Parataxis::get_live_fiber_count(), " live fiber(s) at the end)";
        stop();
    }
);
for my $p ( @paths, map {"$_.old"} @paths ) {    # everything closed: clear the temp dir
    unlink $p;
}
rmdir $dir;

eg/port_scanner.pl  view on Meta::CPAN

use Errno       qw[EINPROGRESS EWOULDBLOCK];
use Time::HiRes qw[time];
$|++;

# This demonstrates how fibers can be used to perform concurrent
# network operations using standard Perl modules (IO::Socket) and the
# Parataxis non-blocking I/O scheduler.
my $target = '127.0.0.1';
my @ports  = ( 22, 80, 443, 3306, 3389, 5432, 8080, 9999 );    # Common ports + our demo server

# To make the test interesting, let's start a tiny listener on 9999 in a fiber
Acme::Parataxis::run(
    sub {
        say "Main: Starting parallel scan of $target...";
        my $start_time = time;

        # Start a dummy listener so we have at least one open port to find
        my $server = IO::Socket::INET->new( LocalAddr => $target, LocalPort => 9999, Listen => 5, Reuse => 1, Blocking => 0 );
        say 'Main: Local dummy server started on 9999' if $server;
        my @results;
        my @futures;

        # Spawn a fiber for each port we want to scan
        for my $port (@ports) {
            push @futures, Acme::Parataxis->spawn(
                sub {
                    my $s = IO::Socket::INET->new( PeerAddr => $target, PeerPort => $port, Proto => 'tcp', Blocking => 0 );

                    # If the socket failed immediately (e.g. invalid target)

eg/port_scanner.pl  view on Meta::CPAN

        }

        # Wait for all scanners to finish
        for my $f (@futures) {
            my $r = $f->await();
            push @results, $r;
            if ( $r->{status} eq 'OPEN' ) {
                say "  [!] Port $r->{port} is OPEN";
            }
        }
        my $elapsed = time() - $start_time;
        say 'Main: Scan complete.';
        say 'Summary:';
        for my $r ( sort { $a->{port} <=> $b->{port} } @results ) {
            say sprintf '  Port %-5d: %s', $r->{port}, $r->{status};
        }
        say sprintf 'Total scan time: %.2fs', $elapsed;
        $server->close() if $server;
        Acme::Parataxis::stop();
    }
);

eg/sha_walk.pl  view on Meta::CPAN

#!/usr/bin/perl
# Hashing a directory tree: File::Find + Digest::SHA, made cooperative.
#
# The reflex when a task is slow is to reach for async, and then spend a day making a synchronous walk yield and a
# synchronous hasher cooperate, and end up with a program that is not measurably faster than the one you started with.
# This file is the worked version of that, and the punchline is in the diagnosis near the end: the hasher was never
# I/O-bound. It is CPU-bound, and no amount of scheduling changes a CPU-bound program that has one thread.
#
# Five things get measured, each against a heartbeat fiber that ticks every 10ms so "did it cooperate" is a number:
#
#   1. File::Find. A synchronous recursive walk. What actually makes it hand the thread back is yield(), and
#      maybe_yield() does not - it is a preemption counter, and at the default threshold of 0 it is a no-op. That is
#      the single most common mistake in this file's genre, so it gets its own section and its own numbers.
#   2. Digest::SHA->addfile. XS. It does its own reading in C, where a Perl-level override cannot reach, so Compat
#      cannot help it at all. Measured, not assumed.

eg/socket.pl  view on Meta::CPAN

Acme::Parataxis::run(
    sub {
        my $server = IO::Socket::INET->new( LocalAddr => '127.0.0.1', LocalPort => 9999, Proto => 'tcp', Listen => 5, Reuse => 1 ) or
            die 'Could not create server: ' . $!;
        $server->blocking(0);
        $server->autoflush(1);
        say 'Server listening on 127.0.0.1:9999';
        my $client_done = 0;
        Acme::Parataxis->spawn(
            sub {
                say 'Client starting...';
                my $client = IO::Socket::INET->new( PeerAddr => '127.0.0.1', PeerPort => 9999, Proto => 'tcp' ) or
                    die 'Could not create client: ' . $!;
                $client->blocking(0);
                $client->autoflush(1);
                say 'Client connected, waiting to write...';
                Acme::Parataxis->await_write($client);
                $client->print("Hello from Parataxis!\n");
                say 'Client waiting for response...';
                Acme::Parataxis->await_read($client);
                my $line = <$client>;

eg/socket.pl  view on Meta::CPAN

            my $res = Acme::Parataxis->await_read($server);
            last if $client_done;    # Check immediately after waking up
            if ( $res > 0 ) {
                my $conn = $server->accept();
                if ($conn) {
                    say 'Server accepted connection!';
                    Acme::Parataxis->spawn(
                        sub {
                            $conn->blocking(0);
                            $conn->autoflush(1);
                            say '  Handler started for ' . fileno($conn);
                            Acme::Parataxis->await_read($conn);
                            my $line = <$conn>;
                            if ( defined $line ) {
                                chomp $line;
                                say '  Server echoing: ' . $line;
                                Acme::Parataxis->await_write($conn);
                                $conn->print("Echo: $line\n");
                            }
                            else {
                                say '  Server got EOF';

eg/stress_fibers.pl  view on Meta::CPAN

use blib;
use Acme::Parataxis qw[:all];
use Time::HiRes     qw[time];

# Stress Test 1: High Fiber Count & Rapid Lifecycle
# This tests the scheduler's ability to handle many short-lived fibers.
async {
    my $total_fibers = 1000;    # We increased MAX_FIBERS in the C code to 1024
    my $iterations   = 5;
    say "Starting Stress Test: $total_fibers fibers, $iterations iterations...";
    my $start_time = time();
    for my $iter ( 1 .. $iterations ) {
        my $iter_start = time();
        my @futures;

        # Spawn a batch of fibers
        for my $i ( 1 .. $total_fibers ) {
            push @futures, fiber {

                # Do a tiny bit of work
                my $val = 0;
                $val += $_ for 1 .. 100;
                no warnings 'recursion';
                yield() if $i % 2 == 0;    # Mix in some yields
                return $val;
            };
        }

        # Wait for all to finish
        for my $f (@futures) {
            await $f;
        }
        my $elapsed = time() - $iter_start;
        say sprintf '  Iteration %2d completed in %.4fs', $iter, $elapsed;
    }
    my $total_elapsed = time() - $start_time;
    say sprintf 'Total time for %d fibers across %d iterations: %.4fs', $total_fibers, $iterations, $total_elapsed;
    say 'Average time per fiber lifecycle: ' . ( $total_elapsed / ( $total_fibers * $iterations ) ) . 's';
};

eg/stress_io.pl  view on Meta::CPAN

use Time::HiRes     qw[time];
$|++;

# Stress Test 2: Concurrent I/O (Background Thread Pool)
# This tests the ability to handle many simultaneous blocking background tasks.
async {
    my $concurrency = 64;    # Half of MAX_FIBERS
    my $iterations  = 5;
    my $sleep_ms    = 500;
    say "Starting I/O Stress Test: $concurrency concurrent sleeps of ${sleep_ms}ms...";
    my $start_time = time();
    for my $iter ( 1 .. $iterations ) {
        my $iter_start = time();
        my @futures;

        # Spawn concurrent sleep fibers
        for my $i ( 1 .. $concurrency ) {
            push @futures, fiber {
                no warnings 'recursion';

                # This offloads to the C-level background thread pool
                await_sleep($sleep_ms);
                return "Worker $i done";
            };
        }

        # Wait for all to finish
        for my $f (@futures) {
            await $f;
        }
        my $elapsed = time() - $iter_start;

        # Since they are concurrent and $concurrency > CPU count (usually),
        # it should take roughly (ceil(concurrency / num_cpus) * sleep_ms)
        say sprintf '  Iteration %2d completed in %.4fs', $iter, $elapsed;
    }
    my $total_elapsed = time() - $start_time;
    say sprintf 'Total time for %d concurrent sleeps across %d iterations: %.4fs', $concurrency, $iterations, $total_elapsed;
};

eg/stress_preempt.pl  view on Meta::CPAN

# This tests the integrity of the stack teleportation during deep recursion
# and the effectiveness of the preemption threshold.
# Configuration
my $recursion_depth = 50;     # Not too deep to overflow 4MB C-stack, but deep enough to test pads
my $preempt_at      = 100;    # Operations before forced yield
my $num_fibers      = 10;     # Number of competing CPU-bound fibers
Acme::Parataxis::set_preempt_threshold($preempt_at);
async {
    say 'Starting Preemption Stress Test...';
    say "Recursion depth: $recursion_depth, Preempt threshold: $preempt_at, Fibers: $num_fibers";
    my $start_time = time();
    my @futures;

    # Recursive function to stress pads and preemption
    sub recursive_math( $depth_in, $fiber_id ) {
        no warnings 'uninitialized';
        my $depth = $depth_in;    # Localize
        return 1 if $depth <= 0;

        # Do some CPU work and potential preemption
        my $acc = 0;

eg/stress_preempt.pl  view on Meta::CPAN

            my $val = recursive_math( $recursion_depth, $i );
            say "  [Fiber $i] Done with result: $val";
            return $val;
        };
    }

    # Wait for all to finish
    for my $f (@futures) {
        await $f;
    }
    my $total_elapsed = time() - $start_time;
    say sprintf 'Total time for %d competing recursive fibers: %.4fs', $num_fibers, $total_elapsed;

    # Reset preemption threshold for the rest of the script/environment
    Acme::Parataxis::set_preempt_threshold(0);
};

eg/symmetric.pl  view on Meta::CPAN

        }
        say '  Consumer: Shutting down.';
        Acme::Parataxis->root->transfer();    # Return to main
    }
);
say 'Main: Starting the dance...';

# We need to prime the consumer so it hits its yield()
$consumer->call();

# Now start the producer
$producer->call();
say 'Main: The dance is over.';

eg/synopsis.pl  view on Meta::CPAN

use blib;
{
    use v5.40;
    use Acme::Parataxis qw[:all];
    $|++;
    async {
        say 'Main task started';
        my $f1 = fiber {
            say '  Task 1: Sleeping...';
            await_sleep(1000);
            say '  Task 1: Waking up';
            return 'Coffee!';
        };
        my $f2 = fiber {
            say '  Task 2: Calculating... (simulated CPU work)';
            my $sum = 0;
            for ( 1 .. 100 ) {

eg/tar_pack.pl  view on Meta::CPAN

    printf "  %-34s %s\n",       'archive written', ( -e $out ? 'yes' : 'no' );
    say '';
    say sprintf( '  The cancel landed on the %dth boundary, inside a file that was %d chunks long,', $seen, $CHUNKS_PER_FILE );
    say '  and the cost of the signal was the work in flight for that one chunk. Change the chunk size';
    say '  at the top of this file and the granularity moves with it: that is the whole design';
    say "  decision, and it is yours to make, not the scheduler's.";
    say '';
    say '  Note also what is *not* on disk. The reads never reached the build stage, so there is no';
    say '  output file at all - not a zero-length one, not an empty archive. A cooperative cancel';
    say '  cannot leave you a half-written archive, because the only code that writes the destination';
    say '  is code the cancel can stop before it starts. Section 3 is about the case where that is';
    say '  not true.';
}

# What a half-written archive actually does, measured rather than asserted.
say '';
say '3. A half-written archive, and what the standard tools make of it.';
say '';
{
    # A cooperative cancel can never produce one, which is worth being precise about. write() is a
    # single call into C, so the scheduler has no boundary inside it, and section 2's cancel lands

eg/tar_pack.pl  view on Meta::CPAN

    printf "    %-38s %s\n", 'Blocking installed:',        ( $have_blocking               ? 'yes'                            : 'no' );
    printf "    %-38s %s\n", 'an ithreads perl to clone:', ( $ithreads                    ? 'yes'                            : 'no' );
    printf "    %-38s %s\n", '$Config{useithreads}',       ( defined $Config{useithreads} ? "'" . $Config{useithreads} . "'" : 'undef' );
    say '';
    say '  The trap still applies, it is just not demonstrable without the thread, and it is worth';
    say '  knowing before you reach for spawn_blocking on a long job: a cancelled await withdraws the';
    say '  waiter and nothing else. The closure runs to completion. Do not clean up its output on the';
    say '  strength of a cancellation alone.';
    say '';
    say '  Compare the inline numbers: the build above took ' . sprintf( '%.1f ms', $ok_ms ) . ' for ' . sprintf( '%.1f MB', $mb ) . '.';
    say '  A spawn_blocking call costs on the order of 10ms before it starts, so for a job this size';
    say '  the thread is not worth reaching for on speed grounds - only because you want the bytes';
    say '  moving while this thread does something else.';
}

# Two features in this distribution that must not be used in the same program.
#
# This section is a bug report, not a demonstration, and the numbers in it were measured on the
# threaded 5.44.0 build. It is here because the combination is easy to reach by accident: a program
# that turns on transparent unblocking to stop writing await_sleep(0) by hand, and then reaches for
# spawn_blocking for one long job.

eg/thread_pool.pl  view on Meta::CPAN


# Demonstrate dynamic thread pool growth and modern API
async {
    say 'Main: Initial thread pool size is ' . Acme::Parataxis::get_thread_pool_size();
    my @futures;
    for my $id ( 1 .. 5 ) {
        push @futures, fiber {
            my $fid        = current_fid();
            my $sleep_time = int( rand(1000) ) + 500;
            say "  [Worker $id] Fiber #$fid will sleep for ${sleep_time}ms in background pool";
            my $start = time();

            # This yields to main, background thread sleeps, scheduler resumes us
            await_sleep($sleep_time);
            my $elapsed = int( ( time() - $start ) * 1000 );
            say "  [Worker $id] Fiber #$fid woke up after ${elapsed}ms!";
            return "Done $id";
        };
    }
    say 'Main: All workers spawned. Waiting for completion...';
    say 'Main: Thread pool size during load: ' . Acme::Parataxis::get_thread_pool_size();
    my $start_time = time();

    # Wait for all workers to finish via futures using modern 'await'
    await $_ for @futures;
    say 'Main: All workers finished!';
    printf "Total wallclock time: %.2fs\n", time() - $start_time;
    say 'Main: Final thread pool size: ' . Acme::Parataxis::get_thread_pool_size();
};

eg/worker_pool.pl  view on Meta::CPAN

    sub {
        my @jobs = (
            { id => 1, task => 'Fetch User Data',  delay => 800 },
            { id => 2, task => 'Process Payment',  delay => 1200 },
            { id => 3, task => 'Send Email',       delay => 500 },
            { id => 4, task => 'Update Inventory', delay => 1500 },
            { id => 5, task => 'Generate Report',  delay => 900 },
            { id => 6, task => 'Sync Analytics',   delay => 1100 }
        );
        say 'Main: Starting worker pool with 3 fibers...';
        my $start_time = time;

        # Simple shared queue
        my @queue = @jobs;
        my @results;

        # Spawn 3 worker fibers
        my @workers;
        for my $w_id ( 1 .. 3 ) {
            push @workers, Acme::Parataxis->spawn(
                sub {
                    say "  [Worker $w_id] Fiber started.";
                    while ( my $job = shift @queue ) {
                        say "  [Worker $w_id] Processing Job $job->{id}: $job->{task}...";

                        # Simulate a blocking I/O call (DB query, API request, idk...)
                        # This yields to the scheduler while the native thread pool sleeps.
                        Acme::Parataxis->await_sleep( $job->{delay} );
                        say "  [Worker $w_id] Finished Job $job->{id}.";
                        push @results, "Job $job->{id} complete";
                    }
                    return "Worker $w_id finished.";
                }
            );
        }

        # Wait for all workers to complete
        say 'Main: Waiting for pool to drain...';
        $_->await for @workers;
        my $elapsed    = time() - $start_time;
        my $sum_delays = 0;
        $sum_delays += $_->{delay} for @jobs;
        say 'Main: All tasks finished!';
        say 'Total Results: ' . scalar(@results);
        say sprintf 'Total Wallclock Time: %.2fs',     $elapsed;
        say sprintf 'Sum of individual delays: %.2fs', $sum_delays / 1000;
        say sprintf 'Speedup: ~%.2fx', ( $sum_delays / 1000 ) / $elapsed;
    }
);

lib/Acme/Parataxis.c  view on Meta::CPAN

 * absolute reference to a default-visibility global has to process that relocation at load time, and link editors
 * that refuse relocations against non-writable sections (Solaris and OmniOS ld: "relocations remain against
 * allocatable but non-writable sections") reject the object outright. Hidden symbols resolve at link time instead.
 */
#if defined(__GNUC__) && !defined(_WIN32)
#define PARA_HIDDEN __attribute__((visibility("hidden")))
#else
#define PARA_HIDDEN
#endif

/* C-level entry point invoked when a freshly created fiber starts running. */
PARA_HIDDEN void para_entry_point(para_fiber_t * c);

#if defined(USE_ASM_CORO)
/**
 * @brief Raw register-only context switch.
 *
 * Saves the callee-saved registers and the current stack pointer into *from, restores them from *to, then returns
 * (popping the return address off the target stack). A freshly created fiber's stack is pre-arranged so that the return
 * address lands in para_trampoline.
 *

lib/Acme/Parataxis.c  view on Meta::CPAN


    /*
     * Perl Interpreter State Pointers.
     * These must be saved and restored during every context switch.
     */
    PERL_SI * si;            /**< Current Stack Info (tracks recursion and eval frames) */
    AV * curstack;           /**< The active Argument Stack (AV*) */
    AV * mainstack;          /**< Main argument stack target for exit()/POPSTACK_TO (per-fiber) */
    SSize_t stack_sp_offset; /**< Stack Pointer offset from stack base */

    I32 * markstack;     /**< Base of the Mark Stack (tracks list start points) */
    I32 * markstack_ptr; /**< Current pointer into the Mark Stack */
    I32 * markstack_max; /**< Limit of the Mark Stack */

    I32 * scopestack;   /**< Base of the Scope Stack (tracks block nesting) */
    I32 scopestack_ix;  /**< Current index in the Scope Stack */
    I32 scopestack_max; /**< Limit of the Scope Stack */
#ifdef DEBUGGING
    const char ** scopestack_name; /**< DEBUGGING-only names parallel to scopestack */
#endif

lib/Acme/Parataxis.c  view on Meta::CPAN


    SV * user_cv;  /**< The Perl sub/coderef this fiber is running */
    SV * self_ref; /**< The Acme::Parataxis Perl object wrapper */

    SV * transfer_data; /**< Arguments or return values passed during yield/transfer */

    void * owner;       /**< PerlInterpreter that allocated this record (arena ownership); NULL never matches */

    int id;          /**< Numeric ID of this fiber */
    int finished;    /**< Flag: 1 if the fiber has completed its entry_point */
    int started;     /**< Flag: 1 once the fiber has actually begun running */
    int parent_id;   /**< ID of the fiber that 'called' this one (asymmetric) */
    int last_sender; /**< ID of the fiber that last switched control to this one */

    /* exit() interception. perl's exit() longjmps up the JMPENV chain. The coro_call guard lives on the
     * caller's (parent) stack and is popped after every resume, so a fiber resumed a second time runs with a
     * stale top_env pointing at the popped guard: an exit() then longjmps to freed stack memory and dies in
     * __longjmp (unreadable jump target). It must be captured on the fiber's own stack and re-raised on the
     * caller's stack instead (see parataxis_pp_exit / para_entry_point / coro_call). exit_pending is set when
     * exit() was called by this fiber or a fiber it called; exit_status carries the requested exit code.
     * (On x64 Windows there is the extra constraint that the CRT longjmp cannot cross stacks at all.) */

lib/Acme/Parataxis.c  view on Meta::CPAN

        return;
    max_fibers = max > HARD_FIBER_LIMIT ? HARD_FIBER_LIMIT : max;
}

/** @brief Returns how many fibers may exist at once. */
DLLEXPORT int get_max_fibers(void) { return max_fibers; }

/**
 * @brief Grows the fiber table to at least `want` entries, doubling so allocation stays amortized O(1).
 *
 * New slots start empty and join the tail of the free list in descending order, so popping still hands out ascending
 * ids: the first allocation on an empty table reproduces the old static seeding exactly (ids 0, 1, 2, ...). Growth is
 * bounded by HARD_FIBER_LIMIT and deliberately ignores max_fibers - the table may outlive the live-fiber limit, which
 * costs only a few tens of kilobytes and lets set_max_fibers be raised again without reallocating anything.
 *
 * @param want Minimum number of entries wanted.
 * @return 1 if the table now holds at least `want` entries, 0 if an allocation was refused.
 */
static int _fiber_table_grow(int want) {
    if (want <= fiber_capacity)
        return 1;

lib/Acme/Parataxis.c  view on Meta::CPAN

            }
            else if (job->type == TASK_GET_CPU) {
                int cpu = get_current_cpu();
                job->output.i = cpu;
            }
            else if (job->type == TASK_READ || job->type == TASK_WRITE) {
                fd_set read_fds, write_fds;
                FD_ZERO(&read_fds);
                FD_ZERO(&write_fds);
                int nfds = 0;
                int res = -1;    /* an unrepresentable descriptor can never become ready, so -1 from the start */
#ifdef _WIN32
                SOCKET s = (SOCKET)job->input.i;
                if (job->type == TASK_READ) FD_SET(s, &read_fds);
                else                        FD_SET(s, &write_fds);
                nfds = 0;
                int timeout = job->timeout_ms > 0 ? job->timeout_ms : 5000;
                struct timeval tv;
                tv.tv_sec = timeout / 1000;
                tv.tv_usec = (timeout % 1000) * 1000;

lib/Acme/Parataxis.c  view on Meta::CPAN

        if (job_refcount[owner] == 0 && fiber_destroyed[owner]) {
            fiber_destroyed[owner] = 0;
            _release_slot(owner);
        }
    }
}

/**
 * @brief Resets the call depth of a Perl CV to zero.
 *
 * Used to ensure that a newly created fiber starts its coderef with a clean execution state.
 *
 * @param cv_ref SV reference to the coderef.
 */
DLLEXPORT void force_depth_zero(SV * cv_ref) {
    dTHX;
    CV * cv = NULL;
    if (SvROK(cv_ref))
        cv = (CV *)SvRV(cv_ref);
    else if (SvTYPE(cv_ref) == SVt_PVCV)
        cv = (CV *)cv_ref;

lib/Acme/Parataxis.c  view on Meta::CPAN

        PERL_CONTEXT * cx = &(si->si_cxstack[i]);
        if ((CxTYPE(cx) == CXt_SUB || CxTYPE(cx) == CXt_FORMAT) && cx->blk_sub.cv == cv)
            return 1;
    }
    return 0;
}

/** @brief TRUE if a live CXt_SUB/CXt_FORMAT frame for cv sits anywhere in this si's runlevel chain.
 *
 * A runlevel chain is not one context stack. push_scope()/new_stackinfo_flags() hands each nested
 * runlevel its own si with a fresh cxstack whose si_cxix starts at -1, and links it into the current
 * chain with si_prev/si_next. Frames created inside the nested runlevel therefore live in *its*
 * cxstack and are absent from the outer one, so a scan of si->si_cxstack alone reports "not live"
 * for a CV whose frame is live two runlevels down. Test2's subtest buffer is exactly such a runlevel:
 * subtest_buffered()/run_subtest() frames sit in a nested si of the main context, which is why the
 * settle pass used to zero CvDEPTH for a CV that had a live frame. */
static int para_si_has_frame(PERL_SI * si, CV * cv) {
    for (PERL_SI * s = si; s; s = s->si_prev)
        if (para_si_cx_has_frame(s, cv))
            return 1;
    for (PERL_SI * s = si ? si->si_next : NULL; s; s = s->si_next)

lib/Acme/Parataxis.c  view on Meta::CPAN

        }
    }

    /* Pass 1b: CVs parked somewhere but absent from the resuming stack: pin CvDEPTH to the
     * deepest parked frame so the next ++CvDEPTH() lands at max + 1, above every parked pad,
     * and clean that landing pad.
     *
     * Pinning is a loan, not a gift: the pads it reserves are released only by the pops of the frames
     * that occupy them, and a pop restores CvDEPTH to that frame's own olddepth. So the second parker of
     * a CV enters at 2 rather than 1 and pops back to 1, the third enters at 3 and pops back to 2 -- each
     * pop entirely correct, yet the counter settles one level above where it started, once per parker.
     * Pass 1c below -- run on every swap, never on a sub-return path -- is the repayment. */
    for (U32 k = 0; k < para_cvreg_active_n; k++) {
        para_cvreg_entry_t * e = &para_cvreg[para_cvreg_active[k]];
        int was_on_stack = e->on_stack;
        if (was_on_stack)
            continue; /* Pass 1 set this CV to its exact value; a pin here would gift a level.
                       * Keep on_stack set so Pass 1c knows a live frame is being resumed. */
        e->on_stack = 0;
        CvDEPTH(e->cv) = e->max_depth;
        _clean_landing_pad(aTHX_ e->cv, e->max_depth + 1);

lib/Acme/Parataxis.c  view on Meta::CPAN

        si->si_prev = root;
    }
    //
    c->si = si;
}

/**
 * @brief Resets a fiber's Perl control stacks back to their initial state.
 *
 * Called when a fiber is destroyed and its memory parked in the reuse cache. The stacks keep whatever size they grew to
 * and are simply re-initialized; resetting the bounds conservatively back to the starting size just means perl grows
 * them again if a new fiber recurses deep.
 *
 * @param c The fiber context to reset.
 */
static void reset_perl_stacks(pTHX_ para_fiber_t * c) {
    I32 sz = FIBER_STACK_DEPTH;
    PERL_SI * si = c->si;

    /* Release any mortal SVs still parked on the tmps stack */
    if (c->tmps_stack) {

lib/Acme/Parataxis.c  view on Meta::CPAN

        sv_2mortal(res);
    return res;
}

/**
 * @brief Entry point function for all new fibers.
 *
 * Sets up the Perl environment (ENTER/SAVETMPS), unpacks arguments, calls the user coderef, handles results/errors, and
 * manages the fiber's completion lifecycle.
 *
 * @param c Pointer to the fiber context being started.
 */
PARA_HIDDEN void para_entry_point(para_fiber_t * c) {
    dTHX;
    c->started = 1;
    ENTER;
    SAVETMPS;
    dSP;
    dJMPENV;
    PUSHMARK(SP);

    /* Unpack arguments passed during coro_call */
    if (c->transfer_data && SvROK(c->transfer_data) && SvTYPE(SvRV(c->transfer_data)) == SVt_PVAV) {
        AV * args = (AV *)SvRV(c->transfer_data);
        I32 len = av_top_index(args) + 1;

lib/Acme/Parataxis.c  view on Meta::CPAN

     * behind threads->create (perl_clone) are process-shared, so a cloned worker inherits the parent's opaque fiber
     * ids; destroy_coro() refuses a record whose owner is not the current interpreter so a worker's destruct cannot
     * free memory that belongs to the parent's pool. A recycled record re-binds to whoever is creating now. aTHX is
     * only a real expression on ithreads builds, where perl_clone (and the whole hazard) can exist at all. */
#ifdef USE_ITHREADS
    c->owner = (void *)aTHX;
#else
    c->owner = NULL;
#endif

    /* Reset the coderef's call depth so the fiber starts clean */
    if (user_code && user_code != &PL_sv_undef)
        force_depth_zero(user_code);

    c->user_cv = user_code;
    if (user_code && user_code != &PL_sv_undef)
        SvREFCNT_inc(user_code);
    c->self_ref = self_ref;
    if (self_ref && self_ref != &PL_sv_undef)
        SvREFCNT_inc(self_ref);
    c->id = idx;
    c->parent_id = -1;
    c->last_sender = -1;
    c->finished = 0;
    c->started = 0;
    c->exit_pending = 0;
    c->exit_status = 0;
    c->transfer_data = &PL_sv_undef;
    fibers[idx] = c;

    arm_fiber_context(c, idx);
    return idx;
}

/**

lib/Acme/Parataxis.c  view on Meta::CPAN

 * Suspends the caller and switches execution to the specified fiber. Sets the caller as the 'parent' for future yields.
 *
 * @param fiber_id Fiber ID to call.
 * @param args Perl SV (usually arrayref) to pass as arguments to the fiber.
 * @return SV* Result yielded by the fiber.
 */
DLLEXPORT SV * coro_call(int fiber_id, SV * args) {
    dTHX;
    if (fiber_id < 0 || fiber_id >= fiber_capacity || !fibers[fiber_id] || fibers[fiber_id]->finished)
        return &PL_sv_undef;
    /* A fiber whose context stack the deadlock purger tore down (started, not finished, si_cxix == -1)
     * has no live frame to resume: perform_switch into it would run unwound perl state and underflow the
     * context stack. Its run died with it parked, so any wait that was still registered can still try to
     * wake it -- that wake must be a no-op. The record stays in the table (the fid must keep its slot). */
    if (fibers[fiber_id]->started && fibers[fiber_id]->si && fibers[fiber_id]->si->si_cxix < 0)
        return &PL_sv_undef;
    if (fibers[fiber_id]->transfer_data != args) {
        if (fibers[fiber_id]->transfer_data && fibers[fiber_id]->transfer_data != &PL_sv_undef)
            SvREFCNT_dec(fibers[fiber_id]->transfer_data);
        fibers[fiber_id]->transfer_data = args;
        if (args && args != &PL_sv_undef)
            SvREFCNT_inc(args);
    }
    fibers[fiber_id]->parent_id = current_fiber_id;

lib/Acme/Parataxis.c  view on Meta::CPAN

         * stack. */
        if (fibers[fiber_id] && fibers[fiber_id]->exit_pending && current_fiber_id >= 0) {
            para_fiber_t * caller = fibers[current_fiber_id];
            if (caller) {
                caller->exit_pending = 1;
                caller->exit_status = fibers[fiber_id]->exit_status;
            }
        }
        JMPENV_JUMP(ret);
    }
    if (!fibers[fiber_id]->started)
        fibers[fiber_id]->top_env = &cur_env;
    perform_switch(fiber_id, 1);
    JMPENV_POP;
    if (fibers[fiber_id] && fibers[fiber_id]->exit_pending) {
        /* The fiber's exit() was caught on the fiber stack (see para_entry_point). We are back on the caller's stack,
         * so perl's exit machinery (which longjmps up the JMPENV chain) is safe here: every env it will hit lives on
         * this same stack. */
        int exit_status = fibers[fiber_id]->exit_status;
        fibers[fiber_id]->exit_pending = 0;
        fibers[fiber_id]->exit_status = 0;

lib/Acme/Parataxis.c  view on Meta::CPAN

 */
DLLEXPORT int run_fiber_checked(int fiber_id, SV * args) {
    dTHX;
    if (fiber_id < 0 || fiber_id >= fiber_capacity || !fibers[fiber_id])
        return -1;
    para_fiber_t * c = fibers[fiber_id];
    if (c->finished) {
        destroy_coro(fiber_id);
        return 1;
    }
    /* A fiber torn down by the deadlock purger (started, not finished, si_cxix == -1) can never be run
     * again: coro_call() would underflow its unwound context stack. Report "not found" so the scheduler
     * neither re-enqueues it (status 0) nor marks it done (status 1) -- the record and its fid must stay
     * occupied. See coro_call()'s guard for the other resume paths. */
    if (c->started && c->si && c->si->si_cxix < 0)
        return -1;
    SV * ret = coro_call(fiber_id, args);
    if (!fibers[fiber_id] || fibers[fiber_id]->finished) {
        destroy_coro(fiber_id);
        return 1;
    }
    if (ret && SvROK(ret) && SvTYPE(SvRV(ret)) == SVt_PVAV) {
        AV * av = (AV *)SvRV(ret);
        if (av_len(av) == 0) {
            SV ** svp = av_fetch(av, 0, 0);

lib/Acme/Parataxis.c  view on Meta::CPAN

 */
DLLEXPORT SV * coro_transfer(int target_id, SV * args) {
    dTHX;
    if (target_id < -1 || (target_id >= 0 && (target_id >= fiber_capacity || !fibers[target_id])))
        return &PL_sv_undef;
    if (target_id >= 0 && fibers[target_id]->finished)
        return &PL_sv_undef;
    /* Same guard as coro_call(): a fiber torn down by the deadlock purger has no live frame to
     * transfer to, and the wait that armed this wake (a completed job, a satisfied channel) was
     * registered before its run died. The wake is a no-op; the record stays occupied. */
    if (target_id >= 0 && fibers[target_id]->started
        && fibers[target_id]->si && fibers[target_id]->si->si_cxix < 0)
        return &PL_sv_undef;
    para_fiber_t * target = (target_id == -1) ? &main_context : fibers[target_id];
    if (target->transfer_data != args) {
        if (target->transfer_data && target->transfer_data != &PL_sv_undef)
            SvREFCNT_dec(target->transfer_data);
        target->transfer_data = args;
        if (args && args != &PL_sv_undef)
            SvREFCNT_inc(args);
    }

lib/Acme/Parataxis.c  view on Meta::CPAN

    if (!self_ref || self_ref == &PL_sv_undef)
        return &PL_sv_undef;
    SvREFCNT_inc(self_ref);
    return sv_2mortal(self_ref);
}

/** @brief Returns the number of currently live (non-destroyed) fibers. */
DLLEXPORT int get_live_fiber_count(void) {
    int count = 0;
    for (int i = 0; i < fiber_capacity; i++)
        if (fibers[i] && fibers[i]->started)
            count++;
    return count;
}

/** @brief Returns the number of allocated slots in the fiber table, i.e. the exclusive upper bound on a fiber id.
 *
 * The table starts at DEFAULT_FIBER_TABLE and doubles when it fills, so this is the value a caller must scan to
 * enumerate every id. Anything that walks ids (the Perl-side _live_fiber_ids, and so dump_fibers, the deadlock
 * report, and run()'s pre-run snapshot) has to read it rather than assume the old compile-time 1024. */
DLLEXPORT int get_fiber_capacity(void) {
    return fiber_capacity;
}

/** @brief Internal helper to reset subroutine depth for cleanup. */
static void recursive_depth_reset(pTHX_ CV * cv) {
    if (!cv || SvTYPE((SV *)cv) != SVt_PVCV)
        return;

lib/Acme/Parataxis.pm  view on Meta::CPAN

            }
        }
        die 'Could not find or load ' . $lib_name unless $lib;
        _bind_functions($lib);
    }

    # API aliases and wrappers
    sub fiber : prototype(&) ($code) { spawn( __PACKAGE__, $code ) }
    sub async : prototype(&) ($code) { return run($code) }

    # Index at which user arguments start in @_: 0 when it is a plain call, 1 when $_[0] is a self (package name or
    # blessed object). This mirrors the shift/unshift invocant dance used elsewhere, but reads $_[0] instead of
    # shifting, so calling it never reifies the caller's pad @_. A reified @_ left behind in a parked frame trips
    # pp_entersub's assert(!AvREAL(av))/assert(AvFILLp(av) == -1) when a different fiber later enters the same sub at
    # the same depth.
    sub _arg_offset {
        my $self = $_[0];
        return ( defined $self && ( ( ref $self || $self ) eq __PACKAGE__ || ( builtin::blessed($self) && $self->isa(__PACKAGE__) ) ) ) ? 1 : 0;
    }

    # Aggregate a list of futures into one that resolves when every input has: the result is an arrayref of each

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

=head1 NAME

Acme::Parataxis - Lightweight Cooperative Fibers

=head1 SYNOPSIS

    use v5.40;
    use Acme::Parataxis qw[:all];
    $|++;
    async {
        say 'Main task started';
        my $f1 = fiber {
            say '  Task 1: Sleeping...';
            await_sleep(1000);
            say '  Task 1: Waking up';
            return 'Coffee!';
        };
        my $f2 = fiber {
            say '  Task 2: Calculating... (simulated CPU work)';
            my $sum = 0;
            for ( 1 .. 100 ) {

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

            }
            say '  Task 2: Complete. Will return ' . $sum;
            return $sum;
        };

        # await works on fibers and futures
        say 'Result 1: ' . await($f1);
        say 'Result 2: ' . await($f2);
    };
    # Output:
    # Main task started
    #   Task 1: Sleeping...
    #   Task 2: Calculating... (simulated CPU work)
    #   Task 2: Complete. Will return 5050
    #   Task 1: Waking up
    # Result 1: Coffee!
    # Result 2: 5050

=head1 DESCRIPTION

C<Acme::Parataxis> brings stackful cooperative multitasking (green threads or fibers) and native thread-pool offloading

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

programming language and my own curiosity; I wanted to see how hard it would be to fiddle with perl's core from an FFI
and nothing requires more fiddling than picking up the full context and swapping it around at runtime.

=head1 FUNCTIONS

Importable individually or with the C<:all> tag.

=head2 C<async { ... }>

    async {
        # scheduler starts, executes block as the root fiber, and stops when finished
    };

Convenience wrapper around C<run()>. Executes the provided code block as the initial root fiber of a new scheduler
session and stops the scheduler once the block returns or dies.

=head2 C<fiber { ... }>

    my $f = fiber {
        my $val = do_work();
        return $val;

lib/Acme/Parataxis/Actor.pm  view on Meta::CPAN

use v5.40;
no warnings 'experimental::class', 'recursion';
use feature 'class';

# An actor is a named or anonymous mailbox behind a single private fiber, with a handler that
# runs at most one message at a time. spawn() builds and starts it (a class-level factory, since
# perlclass instances cannot be assembled by hand); the mailbox is created in ADJUST, the fiber
# and its weak self-capture in _start, so spawn() does the checks and plumbing a factory must.
class Acme::Parataxis::Actor v0.1.3 {
    use Acme::Parataxis qw[fiber];
    use Acme::Parataxis::Channel;
    use Acme::Parataxis::Future;
    use Carp qw[croak];
    our $STOP = \do { my $x = 1 };    # envelope value that tells the loop to shut down gracefully
    field $cap  : param;              # mailbox capacity
    field $code : param;              # the handler: ($self, $value) => result, run for each message
    field $done = 0;                  # set once at teardown
    field $error;                     # what killed the actor, or undef for a graceful stop

lib/Acme/Parataxis/Actor.pm  view on Meta::CPAN

        #
        delete @unknown{qw[supervised name]};
        croak 'Actor->spawn(): unknown options: ' . join ', ', sort keys %unknown if %unknown;
        my $name = $opts{name};
        if ( defined $name ) {
            croak 'Actor->spawn(): the name must be a non-empty string' unless !ref $name && length $name;
            my $existing = $Acme::Parataxis::ACTOR_REGISTRY{$name};
            croak "Actor->spawn(): an actor named '$name' is already registered" if $existing && $existing->is_alive;
        }
        my $self = $class->new( code => $code, cap => $capacity, name => $name, supervised => !!$opts{supervised}, opts => \%opts );
        $self->_start;
        return $self;
    }

    # Lives in its own method so the fiber closure only ever reaches the actor through field
    # values captured as lexicals (a perlclass closure cannot touch fields directly). The fiber
    # body captures a weak copy of $self, so a done actor is collectable.
    method _start () {
        my $weak = $self;    # the fiber body captures this weak copy, so a done actor is collectable
        builtin::weaken($weak);
        my $mb  = $mailbox;
        my $srv = $supervised;
        $fiber = fiber {
            my $crash;

            # The loop is guarded so teardown is reached on *every* exit path: an interrupt (a
            # cancellation token or a with_timeout deadline landing on this fiber) thrown from a
            # parked wait inside a handler escapes the loop and must not skip the drain below.

lib/Acme/Parataxis/Actor.pm  view on Meta::CPAN


    # Fires exactly once when this actor is gone: $err is what killed it, or undef for a graceful stop. An actor that
    # is already done calls back immediately, so a watcher never has to check.
    method on_death : prototype($&) ($cb) {
        if ($done) { $cb->( $self, $error ); return $self }
        push $on_death->@*, $cb;
        return $self;
    }
    method error () {$error}    # why it died, or undef if it stopped gracefully

    # A fresh, already-running actor with the same handler, mailbox size and options: what a supervisor starts in
    # place of this one. The new actor owns a new mailbox, so asks still outstanding here are failed here rather than
    # answered there.
    method respawn () {
        return ref($self)->spawn( $code, $cap, $opts->%* );
    }

    method _dispatch ( $reply, $value ) {
        my $err;
        my $ok = 1;
        try {

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


        # send: queue a message, expect no answer
        $upper->send( { text => 'nobody is reading this' } );

        # handle what is queued, then shutdown gracefully
        $upper->stop;
    };

=head1 DESCRIPTION

An actor is a private fiber with an incoming mailbox. C<spawn> starts one, binds it to a handler, and returns
immediately. The handler runs inside the actor's private fiber, processing one message at a time. Because messages are
serialized and isolated to this single fiber, internal state requires no mutexes or locking: keep your variables inside
the closure and interact with them purely via messages.

Two verbs do the talking:

=over

=item * C<ask( $msg )> queues a message and returns an L<Acme::Parataxis::Future> that resolves with the handler's return value.

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


=head2 C<spawn( $code, [$capacity = 16], [%opts] )>

    my $actor = Acme::Parataxis::Actor->spawn(
        sub ( $self, $msg ) { ... },
        32,
        supervised => 1,
        name       => 'worker'
    );

Class factory that spawns and starts a new actor. The handler receives C<($self, $msg)>.

=over

=item * C<$capacity>

Mailbox queue capacity before C<send> and C<ask> park the caller (default 16). Must be C<E<gt>= 1>.

=item * C<supervised =E<gt> 1>

If true, an uncaught exception in the handler terminates the actor so a supervisor can observe the failure and restart
it. If false, an exception only fails that specific message's C<ask> and the actor continues running.

=item * C<name =E<gt> $name>

Registers the actor in the process-wide name table so it can be retrieved via C<< Acme::Parataxis->actor($name) >>.
Must be unique among live actors.

=back

=head2 C<ask( $msg )>

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

    $actor->swap( sub ( $self, $msg ) { ... } );

Atomically replaces the message handler for subsequent messages. The swap takes effect at the next message boundary;
any message currently being executed finishes under the previous handler.

=head2 C<respawn( )>

    my $clone = $actor->respawn;

Spawns a fresh actor with the same handler, mailbox capacity, and options. The new actor receives an empty mailbox; any
unanswered requests on the old actor fail on the old actor. Used by supervisors to restart crashed workers.

=head2 C<name( )>

Returns the registered name string, or C<undef> if unnamed.

=head2 C<error( )>

Returns the exception that terminated the actor, or C<undef> if still running or stopped cleanly.

=head2 C<fid( )>

lib/Acme/Parataxis/Blocking.pm  view on Meta::CPAN


    # Reap a child without blocking the run loop, and return its exit status as (exited, status, signal).
    # WNOHANG in a park loop rather than a blocking waitpid: the loop's other fibers have to keep running.
    sub _fork_reap ($pid) {
        my $reaped = 0;
        while ( ( $reaped = waitpid( $pid, POSIX::WNOHANG() ) ) == 0 ) { await_sleep(1) }
        return ( 1, $? >> 8, $? & 127 ) if $reaped == $pid;
        return ( 0, undef,   undef );                         # already reaped by something else, or not ours
    }

    # Index at which user arguments start in @_: 0 when it is a plain call, 1 when $_[0] is a self (package name or
    # blessed object). Mirrors the dance in Acme::Parataxis: read $_[0] instead of shifting, so calling this never
    # reifies the caller's pad @_. A reified @_ left behind in a parked frame trips pp_entersub's invariants when a
    # different fiber later enters the same sub at the same depth.
    sub _arg_offset {
        my $self = $_[0];
        return ( defined $self && ( ( ref $self || $self ) eq __PACKAGE__ || ( builtin::blessed($self) && $self->isa(__PACKAGE__) ) ) ) ? 1 : 0;
    }

    # Run a CPU-bound closure on a dedicated background Perl interpreter, with its result arriving as a normal Future.
    #

lib/Acme/Parataxis/Blocking.pm  view on Meta::CPAN

    }

    # Run a CPU-bound closure in a forked child process and return its result as a normal Future.
    #
    # This is the same promise spawn_blocking makes, for a perl with no thread support. It is a separate entry point
    # rather than a backend switch inside spawn_blocking on purpose: the two have genuinely different limits, and a
    # caller should be able to see them at the call site instead of inheriting a silent per-build difference.
    #
    #   * no threads at all - the point. Nothing here requires threads, threads::shared or Thread::Queue, so a plain
    #     perl gets CPU offload and keeps the property that loading this distribution acquires no threads association.
    #   * copy-in by fork, copy-out by Storable - the child starts as a copy of the whole parent address space, so the
    #     closure sees the caller's world as it was at the fork: its args, and whatever its captured lexicals held
    #     then. Nothing the child does to memory comes back; the only thing that travels is the frozen result. A
    #     result Storable cannot store (a CODE ref, a resource) becomes the Future's error, as does a die().
    #   * the closure must not call back into Acme::Parataxis - the child's interpreter is a copy whose scheduler state
    #     is meaningless, and it holds copies of the parent's descriptors (including any attached driver's sockets), so
    #     a closure that reads or writes through one of those would act on a copy of a descriptor, not the original.
    #     Inherited descriptors also keep their ports busy until the child exits, which is worth knowing when a closure
    #     is short but a run is long.
    #   * cancellation kills - unlike the thread pool, this one can actually stop the work. Cancelling the *await*
    #     still only withdraws the waiter, exactly as with spawn_blocking, so nothing changes by accident; when you do

lib/Acme/Parataxis/Error.pm  view on Meta::CPAN

            my $primary = $natural[0] // $failures->[0];
            my $message = defined $primary ? "nursery failure: $primary" : 'nursery failure';
            bless { message => $message, label => 'nursery failure', wait_reason => undef, failures => $failures, primary => $primary, %args, },
                $class;
        }
        sub kind     ($self) {'nursery'}
        sub failures ($self) { @{ $self->{failures} // [] } }    # every child's error, in spawn order
        sub primary  ($self) { $self->{primary} }                # first natural (non-cancelled) failure
    }

    # Thrown by Acme::Parataxis::Supervisor->run when a supervised tree exhausts its restart
    # budget. Same shape as Error::Nursery: ->failures is every child death that counted against
    # the budget (in the order they happened), ->primary is the one that blew it, and ->child names
    # that child. The tree is already stopped by the time this is thrown.
    package Acme::Parataxis::Error::Supervisor v0.1.3 {
        use parent 'Acme::Parataxis::Error';

        sub new ( $class, %args ) {
            my $failures = delete $args{failures};
            $failures = [] unless ref $failures eq 'ARRAY';
            my $child   = delete $args{child};
            my $primary = delete $args{primary};
            $primary //= ( grep {defined} @$failures )[0];
            my $label   = 'supervisor failure';
            my $message = 'supervisor failure: restart budget exhausted';
            $message .= " by child '$child'" if defined $child;
            $message .= ": $primary"         if defined $primary;
            bless { message => $message, label => $label, wait_reason => undef, failures => $failures, primary => $primary, child => $child, %args, },
                $class;
        }
        sub kind     ($self) {'supervisor'}
        sub failures ($self) { @{ $self->{failures} // [] } }    # every death that counted against the budget
        sub primary  ($self) { $self->{primary} }                # the death that exhausted it
        sub child    ($self) { $self->{child} }                  # name of that child
    }

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

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:

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


=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



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