Acme-Parataxis
view release on metacpan or search on metacpan
### 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
- Spawned fibers run inline at spawn time.
## [v0.0.10] - 2026-02-22
This version comes with a dynamic thread pool and an improved API.
### Added
- New ergonomic API using exported functions like `async { ... }`, `fiber { ... }`, and `await( $target )`.
### Changed
- Refactored native thread pool to use cond vars (`PARA_COND_*`) instead of busy polling, reducing idle CPU usage to near zero.
- Switched to a global job queue for the thread pool for better load balancing across worker threads.
- Reduced default fiber stack size from 4MB to 512K.
- Worker threads are now only spawned when the first asynchronous job is submitted.
- Increased `MAX_FIBERS` limit to 1024.
- Expose thread pool config with `set_max_threads` and `max_threads`.
## [v0.0.9] - 2026-02-21
Asynchronous HTTP::Tiny is basically a semi-automatic footgun.
### Fixed
## Architectural Inspiration
The core concurrency model in Parataxis is heavily inspired by the **Wren** programming language, specifically its
treatment of fibers as the primary unit of execution and its deterministic cooperative scheduling.
## Stack Virtualization
On Unix-like systems, we use `ucontext.h` to manage stack and register state. On Windows, we leverage the native
`Fiber API`. In both cases, we perform heart surgery on the Perl interpreter by manually teleporting its internal
global pointers (the `PL_*` variables) between contexts.
## Shared CVs and Pad Virtualization
A significant challenge in Perl green threads is the shared nature of PadLists and the global `CvDEPTH` counter. In
debug builds of Perl, calling a shared subroutine from multiple fibers can trigger internal assertions (like
`AvFILLp(av) == -1`). Parataxis includes a specialized workaround that surgically cleans the next landing pad before
every context switch to satisfy these assertions without clobbering active lexical state.
## `eval` vs. `try/catch`
While `feature 'try'` is available in modern Perl, manually teleporting interpreter state can occasionally confuse the
compiler's expectations for stack unwinding. Standard `eval { ... }` remains the most predictable way to handle
exceptions within fibers.
lib/Acme/Parataxis.c view on Meta::CPAN
* This file implements a cooperative multitasking system (Fibers) integrated with a preemptive native thread pool. It
* allows Perl to run thousands of user-mode fibers that can offload blocking C-level tasks to background OS threads
* without stalling the main interpreter.
*
* @section Architecture
* - **Fibers**: The primitive unit of execution. Each fiber has its own OS context and a complete set of Perl
* interpreter stacks (Argument, Mark, Scope, Save, Mortal).
* - **Coroutines**: The execution pattern (yield/call/transfer) used by fibers to pass control.
* - **Thread Pool**: A fixed pool of worker threads that poll a job queue for blocking operations like sleep, I/O, or
* heavy computation.
* - **Context Switching**: The `swap_perl_state` function manually saves and restores the global state of the Perl
* interpreter (`PL_*` variables) to allow disjoint execution flows.
*
* @section Caveats
* Shared subroutines (CVs) with re-entrant yielding calls are handled by a specialized pad-clearing mechanism in
* `_activate_current_depths` to satisfy Perl's internal `AvFILLp` assertions in debug builds.
*/
#ifdef _WIN32
#define WIN32_LEAN_AND_MEAN
#ifndef _WIN32_WINNT
lib/Acme/Parataxis.c view on Meta::CPAN
* @param from Pointer to the storage slot holding the current stack pointer.
* @param to Pointer to the storage slot holding the target stack pointer.
*/
extern void para_coro_switch(void ** from, void ** to);
/** @brief Initial jump target for brand-new fiber stacks. */
extern void para_trampoline(void);
__asm__(
".text\n"
".p2align 4\n"
".globl para_coro_switch\n"
".type para_coro_switch, @function\n"
"para_coro_switch:\n"
" pushq %rbx\n"
" pushq %rbp\n"
" pushq %r12\n"
" pushq %r13\n"
" pushq %r14\n"
" pushq %r15\n"
" movq %rsp, (%rdi)\n"
" movq (%rsi), %rsp\n"
" popq %r15\n"
" popq %r14\n"
" popq %r13\n"
" popq %r12\n"
" popq %rbp\n"
" popq %rbx\n"
" ret\n"
".size para_coro_switch, .-para_coro_switch\n"
".p2align 4\n"
".globl para_trampoline\n"
".type para_trampoline, @function\n"
"para_trampoline:\n"
" popq %rdi\n"
" call para_entry_point\n"
" ud2\n"
".size para_trampoline, .-para_trampoline\n");
#endif /* USE_ASM_CORO */
/**
* @brief Get the Operating System's unique Thread ID.
lib/Acme/Parataxis.c view on Meta::CPAN
JMPENV * top_env; /**< Pointer to the top exception environment (eval/die buffers) */
COP * curcop; /**< Current Op Pointer (location in the source/bytecode) */
OP * op; /**< Current Operation being executed */
PAD * comppad; /**< Current lexical Pad (variable storage) */
SV ** curpad; /**< Array pointer to the current lexical Pad */
PMOP * curpm; /**< Current pattern match state */
PMOP * curpm_under; /**< Current pattern match state under */
PMOP * reg_curpm; /**< Current regex match state */
GV * defgv; /**< The $_ global */
GV * last_in_gv; /**< GV used in last <FH> */
SV * rs; /**< The $/ global */
GV * ofsgv; /**< The $, global */
SV * ors_sv; /**< The $\ global */
GV * defoutgv; /**< The default output filehandle */
HV * curstash; /**< Current package stash */
HV * defstash; /**< Default package stash */
SV * errors; /**< Outstanding queued errors */
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 */
lib/Acme/Parataxis.c view on Meta::CPAN
}
}
}
}
}
}
/**
* @brief Swaps the internal Perl Interpreter state pointers.
*
* This is the core of the fiber implementation. It manually saves all global pointers that define the "state" of the
* Perl virtual machine for the current context and restores them for the target context.
*
* @param from Context being paused.
* @param to Context being resumed.
*/
void swap_perl_state(para_fiber_t * from, para_fiber_t * to) {
dTHX;
/* Save current state into 'from' context */
from->si = PL_curstackinfo;
lib/Acme/Parataxis.c view on Meta::CPAN
else
PL_curpad = to->curpad;
// Restore CvDEPTH and clean landing pads
_activate_current_depths(aTHX_ to);
}
/**
* @brief Restores a context's saved Perl interpreter state in-place.
*
* Loads every saved interpreter global from @p to without performing an OS context switch. Used when a fiber longjmps
* out of the system (e.g. via exit()) so that the top-level main context's perl-owned stacks are current again before
* the jump propagates to perl_run/perl_destruct.
*
* Unlike swap_perl_state this deliberately leaves PL_top_env alone: the caller manages the jump environment so the
* rethrow continues past the wrapper that caught the exit.
*
* @param to The context whose saved state should become current.
*/
void restore_perl_state(para_fiber_t * to) {
dTHX;
lib/Acme/Parataxis.c view on Meta::CPAN
c->scopestack_ix = 0;
c->scopestack_max = sz;
c->savestack_ix = 0;
c->savestack_max = sz;
c->tmps_ix = -1;
c->tmps_floor = -1;
c->tmps_max = sz;
/* Inherit globals from the current interpreter state */
c->curcop = PL_curcop;
c->op = PL_op;
c->top_env = PL_top_env;
c->curpm = PL_curpm;
c->curpm_under = PL_curpm_under;
c->reg_curpm = NULL;
c->defgv = PL_defgv;
c->last_in_gv = PL_last_in_gv;
c->rs = PL_rs;
c->ofsgv = PL_ofsgv;
lib/Acme/Parataxis.c view on Meta::CPAN
}
if (idx == -1)
return -2;
para_fiber_t * c = NULL;
#ifndef _WIN32
if (fiber_cache_count > 0)
c = fiber_cache[--fiber_cache_count];
#endif
if (c) {
/* Recycle a parked fiber context: re-inherit globals, clear pads */
reset_perl_stacks(aTHX_ c);
}
else {
c = (para_fiber_t *)malloc(sizeof(para_fiber_t));
if (!c)
return -3;
memset(c, 0, sizeof(para_fiber_t));
/* Initialize Perl stacks */
init_perl_stacks(c);
if (!c->si) {
lib/Acme/Parataxis.c view on Meta::CPAN
}
#endif
free_perl_stacks(aTHX_ c);
free(c);
}
/**
* @brief Global cleanup function for the fiber and thread pool system.
*
* Signals all worker threads to terminate and destroys all remaining fibers. Should be called during global destruction
* or system shutdown.
*/
DLLEXPORT void cleanup() {
dTHX;
#ifdef _WIN32
/* Restore the original exit op so any exit() during global destruction (after this DLL could be unmapped) behaves
* like a plain perl exit. */
if (parataxis_saved_pp_exit && PL_ppaddr[OP_EXIT] == parataxis_pp_exit)
PL_ppaddr[OP_EXIT] = parataxis_saved_pp_exit;
#endif
if (threads_initialized) {
LOCK(queue_lock);
threads_keep_running = 0;
PARA_COND_BROADCAST(queue_cond);
UNLOCK(queue_lock);
lib/Acme/Parataxis.pm view on Meta::CPAN
if ( $status == 0 ) {
$fiber->[F_PRIORITY] //= 0;
_enqueue($fiber);
}
return $status;
}
sub run ($code) {
if ($IS_RUNNING) {
# Nested run/async inside a shared global scheduler. Queue a fresh fiber for the block and park the current
# fiber until it completes.
my $fiber = __PACKAGE__->new( code => $code );
_enqueue($fiber);
return $fiber->await;
}
@SCHEDULER_QUEUE = ();
%SCHEDULER_QUEUED = ();
$IS_RUNNING = 1;
my $main_fiber = __PACKAGE__->new( code => $code );
_enqueue($main_fiber);
lib/Acme/Parataxis.pod view on Meta::CPAN
=head2 Architectural Inspiration
The core concurrency model in Parataxis is heavily inspired by the B<Wren> programming language, specifically its
treatment of fibers as the primary unit of execution and its deterministic cooperative scheduling.
=head2 Stack Virtualization
On Unix-like systems, we use C<ucontext.h> to manage stack and register state. On Windows, we leverage the native
C<Fiber API>. In both cases, we perform heart surgery on the Perl interpreter by manually teleporting its internal
global pointers (the C<PL_*> variables) between contexts.
=head2 Shared CVs and Pad Virtualization
A significant challenge in Perl green threads is the shared nature of PadLists and the global C<CvDEPTH> counter. In
debug builds of Perl, calling a shared subroutine from multiple fibers can trigger internal assertions (like
C<AvFILLp(av) == -1>). Parataxis includes a specialized workaround that surgically cleans the next landing pad before
every context switch to satisfy these assertions without clobbering active lexical state.
=head2 C<eval> vs. C<try/catch>
While C<feature 'try'> is available in modern Perl, manually teleporting interpreter state can occasionally confuse the
compiler's expectations for stack unwinding. Standard C<eval { ... }> remains the most predictable way to handle
exceptions within fibers.
lib/Acme/Parataxis/Semaphore.pod view on Meta::CPAN
$sem->wait;
Block until a permit is available. This is equivalent to C<down> but is named for consistency with other
C<Acme::Parataxis> synchronization primitives.
=head2 C<guard>
my $guard = $sem->guard( );
Acquire a permit and return an L<Acme::Parataxis::Semaphore::Guard> object. The permit is automatically released when
the guard object goes out of scope (unless the interpreter is in global destruction). This is a convenient way to
ensure cleanup.
{
my $guard = $sem->guard;
# permits are held here
}
# $sem->up called automatically
=head1 AUTHOR
( run in 1.261 second using v1.01-cache-2.11-cpan-4716db65a44 )