Acme-Parataxis
view release on metacpan or search on metacpan
lib/Acme/Parataxis.c view on Meta::CPAN
#include <errno.h>
#ifndef USE_ASM_CORO
#include <ucontext.h>
#endif
#include <unistd.h>
#include <sys/mman.h>
#include <sys/resource.h>
#if defined(__APPLE__) || defined(__FreeBSD__) || defined(__NetBSD__) || defined(__DragonFly__)
#include <sys/sysctl.h>
#include <sys/types.h>
#endif
/** @brief Export macro for Unix systems */
#define DLLEXPORT __attribute__((visibility("default")))
#ifdef USE_ASM_CORO
/** @brief Handle for the underlying OS fiber context (only the assembly path's rsp slot is used) */
typedef void * coro_handle_t;
#else
/** @brief Handle for the underlying OS fiber context (ucontext_t) */
typedef ucontext_t coro_handle_t;
#endif
/** @brief Handle for a native OS thread (pthread_t) */
typedef pthread_t para_thread_t;
/** @brief Mutex type for queue synchronization (pthread_mutex_t) */
typedef pthread_mutex_t para_mutex_t;
#define LOCK(m) pthread_mutex_lock(&m)
#define UNLOCK(m) pthread_mutex_unlock(&m)
#define LOCK_INIT(m) pthread_mutex_init(&m, NULL)
#endif
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include <stdlib.h>
#include <string.h>
// Forward declarations
DLLEXPORT SV * coro_yield(SV * ret_val);
DLLEXPORT SV * coro_transfer(int fiber_id, SV * args);
DLLEXPORT SV * coro_call(int fiber_id, SV * args);
DLLEXPORT void destroy_coro(int fiber_id);
#ifndef _WIN32
static void install_stack_guard(void);
static void rightsize_fiber_limit(void);
#endif
typedef struct para_fiber_t para_fiber_t;
/*
* These three symbols are wired together by hand (the asm trampoline, the stack layout in arm_fiber_context) and are
* never referenced outside this translation unit, so keep them non-preemptible. A shared object whose text holds an
* 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.
*
* @param from Pointer to the storage slot holding the current stack pointer.
* @param to Pointer to the storage slot holding the target stack pointer.
*/
PARA_HIDDEN extern void para_coro_switch(void ** from, void ** to);
/** @brief Initial jump target for brand-new fiber stacks. */
PARA_HIDDEN extern void para_trampoline(void);
__asm__(
".text\n"
".p2align 4\n"
".globl para_coro_switch\n"
".hidden para_coro_switch\n"
".type para_coro_switch, @function\n"
"para_coro_switch:\n"
" endbr64\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"
".hidden para_trampoline\n"
".type para_trampoline, @function\n"
"para_trampoline:\n"
" endbr64\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.
*
* Useful for debugging to prove that background tasks are running on different OS threads than the main Perl
* interpreter.
*
* @return int The TID (Windows) or LWP ID (Linux/BSD/macOS).
lib/Acme/Parataxis.c view on Meta::CPAN
#elif defined(__APPLE__) || defined(__FreeBSD__) || defined(__NetBSD__) || defined(__DragonFly__)
/* NetBSD and DragonFly never declare _SC_NPROCESSORS_ONLN; hw.ncpu exists on all four of these. */
int nm[2];
uint32_t count = 0;
size_t len = sizeof(count);
nm[0] = CTL_HW;
nm[1] = HW_NCPU;
/* A failed sysctl leaves count untouched, and the caller divides by the result (thread_id % cpu_count), so
* an indeterminate value is not a cosmetic problem here. Treat failure as "one core" and let the pool clamp. */
if (sysctl(nm, 2, &count, &len, NULL, 0) != 0)
return 1;
return (count > 0) ? (int)count : 1;
#else
long count = sysconf(_SC_NPROCESSORS_ONLN);
return (count > 0) ? (int)count : 1;
#endif
}
/**
* @brief The highest descriptor number this platform's fd_set can represent.
*
* FD_SETSIZE belongs to the platform's C library, not to us, and it is not 1024 everywhere: it is 1024 on
* Linux, macOS and FreeBSD, 256 on NetBSD, and 64 for the winsock fd_set on Win32. It bounds the descriptor
* NUMBER rather than how many descriptors are being watched, so a process that has opened 300 sockets can
* still be holding descriptor 605 - past a 256-entry set on NetBSD. FD_SET is a bare array index with no
* bounds check of its own and select() rejects an oversized nfds with EINVAL, so a descriptor at or past
* this cannot be waited on through an fd_set at all. Exposed so a caller can size a workload against the
* real ceiling instead of assuming the number they are used to.
*
* @return int FD_SETSIZE for this platform.
*/
DLLEXPORT int get_fd_setsize() { return FD_SETSIZE; }
/**
* @struct para_fiber_t
* @brief The complete execution context of a Perl Fiber.
*
* This structure encapsulates both the OS-level register state (via context) and the entire internal state of the Perl
* interpreter required to pause and resume execution of Perl code.
*/
typedef struct para_fiber_t {
coro_handle_t context; /**< OS-specific context handle */
#ifndef _WIN32
void * stack_p; /**< Pointer to dynamically allocated fiber stack (Unix only) */
size_t stack_sz; /**< Size of the allocated stack (Unix only) */
#ifdef USE_ASM_CORO
void * rsp; /**< Saved stack pointer for the assembly switch (Unix x86_64) */
#endif
#endif
/*
* 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
ANY * savestack; /**< Base of the Save Stack (tracks local/my variables for cleanup) */
I32 savestack_ix; /**< Current index in the Save Stack */
I32 savestack_max; /**< Limit of the Save Stack */
SV ** tmps_stack; /**< Base of the Mortal Stack (tracks SVs needing refcnt decrement) */
I32 tmps_ix; /**< Current index in the Mortal Stack */
I32 tmps_floor; /**< Current floor of the Mortal Stack */
I32 tmps_max; /**< Limit of the Mortal Stack */
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 */
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.) */
int exit_pending;
int exit_status;
} para_fiber_t;
/** @name Job Status Constants */
///@{
#define JOB_FREE 0 /**< Slot is available for new tasks */
#define JOB_NEW 1 /**< Task is submitted but not yet picked up by a worker */
#define JOB_BUSY 2 /**< Task is currently being processed by a worker thread */
#define JOB_DONE 3 /**< Task has completed and results are ready */
///@}
/** @name Task Type Constants */
///@{
#define TASK_SLEEP 0 /**< Sleep for N milliseconds */
#define TASK_GET_CPU 1 /**< Retrieve current core ID */
#define TASK_READ 2 /**< Wait for read-readiness on a file descriptor */
#define TASK_WRITE 3 /**< Wait for write-readiness on a file descriptor */
///@}
/**
* @union value_t
* @brief Generic container for task input/output data.
*/
typedef union {
int64_t i; /**< Integer/Pointer storage */
double d; /**< Floating point storage */
char * s; /**< String storage */
} value_t;
/**
* @struct job_t
* @brief Represents a task in the background thread pool queue.
*/
typedef struct {
int fiber_id; /**< ID of the Fiber that submitted this task */
int target_thread; /**< Index of the assigned worker thread */
int type; /**< Type of task to perform (TASK_*) */
value_t input; /**< Input data for the task */
value_t output; /**< Result data populated by the worker */
int timeout_ms; /**< Timeout duration for I/O tasks */
int status; /**< Current lifecycle state (JOB_*) */
volatile int recall; /**< Set to 1 when the owner fiber wants an armed sleep abandoned early */
} job_t;
// Global Registry and State
/** @brief Size of the fiber table when it is first allocated: big enough that an ordinary program never has to
* reallocate it, small enough that the four per-slot arrays cost a few tens of kilobytes. */
#define DEFAULT_FIBER_TABLE 1024
lib/Acme/Parataxis.c view on Meta::CPAN
/** @brief Floor for the default pool size. The pool seeds 2 workers and only grows when jobs pile up, so a machine
* reporting 1-2 cores would pin it at the seed and a freshly submitted job could never get its own worker until an
* unrelated long sleep ended. Sleeping workers are blocked rather than computing, so a small floor costs nothing. */
#define MIN_THREAD_POOL 8
/** @brief Native OS handles for pool threads */
static para_thread_t thread_handles[MAX_THREADS];
/** @brief Maximum allowed threads in the pool */
static int max_thread_pool_size = 0;
/** @brief Number of currently running worker threads */
static int current_thread_count = 0;
/** @brief Workers currently executing a job (guarded by queue_lock); idle = current_thread_count - busy_thread_count. */
static int busy_thread_count = 0;
/** @brief Flag to signal worker threads to terminate */
static volatile int threads_keep_running = 1;
#ifndef _WIN32
/** @brief Pipe used to wake worker threads blocked in select() during shutdown. */
static int shutdown_pipe[2] = { -1, -1 };
#endif
/** @brief Submitted-but-unreclaimed job count per fiber id (avoids fiber slot reuse while jobs are in flight),
* fiber_capacity entries. */
static int * job_refcount = NULL;
/** @brief Set when a fiber id is destroyed but still has outstanding jobs; the id must not be reused until they
* drain. fiber_capacity entries. */
static bool * fiber_destroyed = NULL;
#ifdef _WIN32
/** @brief Windows-only handle for the main thread converted to fiber */
static void * main_fiber_handle = NULL;
#endif
/** @brief Sets the maximum number of worker threads allowed in the pool. */
DLLEXPORT void set_max_threads(int max) {
if (max > 0 && max <= MAX_THREADS)
max_thread_pool_size = max;
}
/**
* @brief Sets how many fibers may exist at once.
*
* The limit is enforced against the slots in use rather than against the allocated table, so it may be raised or
* lowered at any time: lowering it never disturbs fibers that already exist, it only stops the next create_fiber from
* succeeding until some of them are gone. Values below 1 are ignored (as in set_max_threads) and values above
* HARD_FIBER_LIMIT are clamped to it, so what this reports is always what the table could actually hold.
*
* @param max Requested limit.
*/
DLLEXPORT void set_max_fibers(int max) {
if (max < 1)
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;
if (want < DEFAULT_FIBER_TABLE)
want = DEFAULT_FIBER_TABLE;
if (want > HARD_FIBER_LIMIT)
want = HARD_FIBER_LIMIT;
if (want <= fiber_capacity)
return 0;
/* All four tables must reach the new size together, so each pointer is committed the moment its own realloc
* succeeds (discarding a moved pointer would leak the old block) while fiber_capacity is only recorded once every
* one of them made it. A partial failure therefore leaves a table larger than fiber_capacity knows about, which
* is harmless: the next attempt simply reallocs it again. */
para_fiber_t ** nf = (para_fiber_t **)realloc(fibers, (size_t)want * sizeof(*nf));
if (!nf)
return 0;
fibers = nf;
int * nfree = (int *)realloc(free_slots, (size_t)want * sizeof(*nfree));
if (!nfree)
return 0;
free_slots = nfree;
int * nref = (int *)realloc(job_refcount, (size_t)want * sizeof(*nref));
if (!nref)
return 0;
job_refcount = nref;
bool * ndes = (bool *)realloc(fiber_destroyed, (size_t)want * sizeof(*ndes));
if (!ndes)
return 0;
fiber_destroyed = ndes;
for (int i = want - 1; i >= fiber_capacity; i--) {
fibers[i] = NULL;
job_refcount[i] = 0;
fiber_destroyed[i] = false;
free_slots[free_slot_count++] = i;
}
fiber_capacity = want;
return 1;
}
/**
* @brief Returns a slot to the free list, undoing the moment create_fiber took it.
*
* Every release path funnels through here so a taken slot and its `fiber_used` increment can never come apart: the
* allocation failure paths below, a fiber destroyed outright, and a fiber whose id is only released once its jobs
* drain.
*
* @param idx Slot index to give back.
*/
static void _release_slot(int idx) {
if (idx < 0 || idx >= fiber_capacity)
return;
lib/Acme/Parataxis.c view on Meta::CPAN
break;
PARA_COND_WAIT(queue_cond, queue_lock);
}
if (found_idx != -1)
busy_thread_count++; /* busy from claim until the job is marked done, all under queue_lock */
UNLOCK(queue_lock);
if (found_idx != -1 && threads_keep_running) {
job_t * job = &job_slots[found_idx];
// ... processing ...
if (job->type == TASK_SLEEP) {
int ms = (int)job->input.i;
int recalled = 0;
LOCK(queue_lock);
if (ms > 0 && !job->recall && threads_keep_running) {
/* Timed condition-variable wait instead of quantized polling: the OS sleeps for (almost) the whole
* remainder in one call, so a 1000 ms arm costs ~1000 ms on any platform (the old 4 ms quantum
* inflated Windows sleeps ~4x through the ~15.6 ms system timer tick). The wait releases
* queue_lock, so notifying threads (submit/recall/shutdown) are never blocked by a sleeping worker.
* Recall and shutdown wakes are observed by re-checking the predicate; the deadline is fixed, so
* spurious or broadcast wakeups just re-wait to it. */
#ifdef _WIN32
/* Absolute deadline as ms since boot; unsigned subtraction is wrap-safe. */
DWORD deadline = GetTickCount() + (DWORD)ms;
while (!job->recall && threads_keep_running) {
DWORD remaining = deadline - GetTickCount();
if ((int)remaining <= 0)
break;
PARA_COND_TIMEDWAIT(queue_cond, queue_lock, remaining);
}
#else
struct timespec deadline;
clock_gettime(CLOCK_REALTIME, &deadline);
deadline.tv_sec += ms / 1000;
deadline.tv_nsec += (long)(ms % 1000) * 1000000L;
if (deadline.tv_nsec >= 1000000000L) {
deadline.tv_sec++;
deadline.tv_nsec -= 1000000000L;
}
while (!job->recall && threads_keep_running &&
PARA_COND_TIMEDWAIT(queue_cond, queue_lock, &deadline)) {
/* woken (recall, spurious, or shutdown); re-check and re-wait to the same deadline */
}
#endif
}
recalled = job->recall;
UNLOCK(queue_lock);
/* output.i = -1 signals an early recall (interrupted or shutdown); otherwise the full duration elapses. */
job->output.i = (recalled || !threads_keep_running) ? -1 : ms;
}
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;
/* Pass both sets to select */
res = select(nfds, &read_fds, &write_fds, NULL, &tv);
#else
int fd = (int)job->input.i;
/* FD_SET is a bare array index with no bounds check, and read_fds/write_fds are FD_SETSIZE-bit
* sets sitting in this thread's stack frame - 128 bytes where FD_SETSIZE is 1024, but only 32 on
* NetBSD, whose FD_SETSIZE is 256. A descriptor at or past FD_SETSIZE
* writes off the end of them - into the neighbouring set, then into this frame's canary - and
* select() would reject the oversized nfds with EINVAL anyway, so there is nothing to gain by
* trying. Refuse it and report "not ready", the same answer a deadline produces. The Windows
* branch above needs no equivalent: a WinSock fd_set is a full descriptor bitmask, not a
* 1024-entry array, and has no FD_SETSIZE to exceed. */
if (fd >= 0 && fd < FD_SETSIZE) {
if (job->type == TASK_READ) FD_SET(fd, &read_fds);
else FD_SET(fd, &write_fds);
nfds = fd + 1;
if (shutdown_pipe[0] >= 0) {
FD_SET(shutdown_pipe[0], &read_fds); /* ALWAYS read_fds */
if (shutdown_pipe[0] + 1 > nfds)
nfds = shutdown_pipe[0] + 1;
}
int timeout = job->timeout_ms > 0 ? job->timeout_ms : 5000;
struct timeval tv;
tv.tv_sec = timeout / 1000;
tv.tv_usec = (timeout % 1000) * 1000;
/* Pass both sets to select */
res = select(nfds, &read_fds, &write_fds, NULL, &tv);
if (shutdown_pipe[0] >= 0 && FD_ISSET(shutdown_pipe[0], &read_fds))
res = -1; /* woken for shutdown, not readiness */
}
#endif
job->output.i = (res > 0) ? 1 : -1;
}
LOCK(queue_lock);
job->status = JOB_DONE;
busy_thread_count--;
done_queue[done_tail] = found_idx;
done_tail = (done_tail + 1) % (MAX_JOBS + 1);
UNLOCK(queue_lock);
}
else {
if (found_idx != -1) { /* claimed, but shutting down before it ran: keep the busy count honest */
LOCK(queue_lock);
busy_thread_count--;
lib/Acme/Parataxis.c view on Meta::CPAN
* @param idx The job index in the queue.
* @return SV* A mortalized Perl SV containing the result (IV).
*/
DLLEXPORT SV * get_job_result(int idx) {
dTHX;
if (idx < 0 || idx >= MAX_JOBS)
return &PL_sv_undef;
SV * res = &PL_sv_undef;
LOCK(queue_lock);
if (job_slots[idx].status == JOB_DONE || job_slots[idx].status == JOB_BUSY) {
if (job_slots[idx].type == TASK_SLEEP || job_slots[idx].type == TASK_GET_CPU ||
job_slots[idx].type == TASK_READ || job_slots[idx].type == TASK_WRITE) {
res = newSViv(job_slots[idx].output.i);
sv_2mortal(res);
}
}
UNLOCK(queue_lock);
return res;
}
/**
* @brief Gets the ID of the Fiber that submitted a specific job.
*
* @param idx Job index.
* @return int Fiber ID.
*/
DLLEXPORT int get_job_coro_id(int idx) {
if (idx < 0 || idx >= MAX_JOBS)
return -1;
return job_slots[idx].fiber_id;
}
/**
* @brief Frees a job slot in the queue after the result has been retrieved.
*
* @param idx Job index.
*/
DLLEXPORT void free_job_slot(int idx) {
if (idx < 0 || idx >= MAX_JOBS)
return;
int owner = job_slots[idx].fiber_id;
LOCK(queue_lock);
job_slots[idx].status = JOB_FREE;
outstanding_jobs--;
UNLOCK(queue_lock);
/* Release the owner fiber id only once every job it submitted has been reclaimed, and only if the fiber has been
* destroyed. This keeps a stale completion from ever waking a newer fiber that reused the same id. */
if (owner >= 0 && owner < fiber_capacity && job_refcount[owner] > 0) {
job_refcount[owner]--;
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;
if (cv && SvTYPE((SV *)cv) == SVt_PVCV)
((XPVCV *)MUTABLE_PTR(SvANY(cv)))->xcv_depth = 0;
}
/** @brief Returns the ID of the currently executing fiber. */
DLLEXPORT int get_current_parataxis_id() { return current_fiber_id; }
/** @brief Returns the OS-level thread ID of the main interpreter thread. */
DLLEXPORT int get_os_thread_id_export() { return get_os_thread_id(); }
/** @brief Returns the number of worker threads currently running in the pool. */
DLLEXPORT int get_thread_pool_size() { return current_thread_count; }
/** @brief Returns the maximum number of worker threads allowed in the pool. */
DLLEXPORT int get_max_thread_pool_size() { return max_thread_pool_size; }
/** @brief Returns the current count towards the preemption threshold. */
DLLEXPORT int64_t get_preempt_count() { return preempt_count; }
/** @brief Sets the threshold for automatic yield-based preemption. */
DLLEXPORT void set_preempt_threshold(int64_t threshold) { preempt_threshold = threshold; }
/**
* @brief Checks if automatic preemption should occur.
*
* Increments the internal counter and triggers a `coro_yield` if the threshold is reached.
*
* @return SV* Result of the yield, or undef if no yield occurred.
*/
DLLEXPORT SV * maybe_yield() {
dTHX;
preempt_count++;
if (preempt_threshold > 0 && preempt_count >= preempt_threshold) {
preempt_count = 0;
return coro_yield(&PL_sv_undef);
}
return &PL_sv_undef;
}
/**
* @brief DEBUGGING-only: name a CV whose pad @_ (slot 0) is AvREAL.
*
* A fiber that parks while a shared subroutine's @_ slot is AvREAL leaves that state in the CV's shared PadList.
* When a different fiber later enters the same CV at the same depth, pp_entersub's assert(!AvREAL(av)) panics in
* DEBUGGING builds. Printing the offending CV name + depth + where, at the moment the state is created or cleaned,
* localizes the parked-AvREAL-@_ corruption beyond pp_hot.c's bare "(on line N")" message.
*/
static void para_report_avreal_pad(pTHX_ CV * cv, I32 depth, const char * where) {
if (!cv || SvTYPE((SV *)cv) != SVt_PVCV)
return;
const char * pkg = (CvSTASH(cv) && HvNAME(CvSTASH(cv))) ? HvNAME(CvSTASH(cv)) : "?";
const char * name = "?";
GV * gv = CvGV(cv);
if (gv && isGV_with_GP(gv) && GvNAME_HEK(gv))
name = GvNAME(gv);
lib/Acme/Parataxis.c view on Meta::CPAN
return;
while (e->max_depth > 0 && e->counts[e->max_depth] <= 0)
e->max_depth--;
if (e->max_depth == 0) {
para_cvreg_deactivate(e);
Safefree(e->counts);
e->counts = NULL;
e->arr_len = 0;
}
}
static void para_cvreg_remove(CV * cv, I32 depth) {
if (!cv || depth <= 0)
return;
para_cvreg_dec(para_cvreg_lookup(cv, 0), depth);
}
/** @brief Ground truth for "is a frame of this CV live anywhere": walk the running stack and every fiber's.
*
* The registry is a cache of where parked frames are, populated on every swap (Pass 0) and drained on
* every resume (Pass 1). A frame that leaves without a swap in between (a longjmp out of a cancelled
* or timed-out fiber body, or a fiber whose cxstack is unwound by a die) is never drained, so the
* cache can claim a depth that nothing occupies. Callers that need to know whether a CV is *really*
* active must ask the stacks, not the cache. */
static int para_si_cx_has_frame(PERL_SI * si, CV * cv);
static int para_si_has_frame(PERL_SI * si, CV * cv);
static int para_cv_frame_live(pTHX_ CV * cv) {
PERL_SI * si = PL_curstackinfo;
if (para_si_has_frame(si, cv))
return 1;
/* The main context (id -1) is not in fibers[], but it is parked with a live frame whenever a
* fiber runs, so it has to be asked directly. */
if (main_context.si && main_context.si != si && para_si_has_frame(main_context.si, cv))
return 1;
for (int i = 0; i < fiber_capacity; i++) {
PERL_SI * fs = fibers[i] ? fibers[i]->si : NULL;
if (!fs || fs == si)
continue;
if (para_si_has_frame(fs, cv))
return 1;
}
return 0;
}
/** @brief TRUE if a live CXt_SUB/CXt_FORMAT frame for cv sits in this single si's own context stack. */
static int para_si_cx_has_frame(PERL_SI * si, CV * cv) {
if (!si || !si->si_cxstack)
return 0;
for (I32 i = 0; i <= si->si_cxix; i++) {
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)
if (para_si_cx_has_frame(s, cv))
return 1;
return 0;
}
/** @brief TRUE if a live frame for cv sits on the depositing (from) or resuming (to) stack.
*
* Pass 1c runs after PL_curstackinfo already points at the resuming stack, so the depositing stack is
* only reachable through the fiber struct. Both are asked directly, over their whole runlevel chain,
* because a pinned CV can still own a frame that no claim in the register accounts for. Settling such
* a CV to CvDEPTH 0 zeroes the depth its live frame needs, and the frame's own pop then trips core's
* cx_popsub_args assert (Padlist[CvDEPTH] == PL_curpad) or, in a non-debug build, reads @_ out of
* the wrong pad. */
static int para_cv_live_on_swap(pTHX_ para_fiber_t * from, para_fiber_t * to, CV * cv) {
if (from && from->si && para_si_has_frame(from->si, cv))
return 1;
if (to && to != from && to->si && para_si_has_frame(to->si, cv))
return 1;
return 0;
}
/** @brief Drops every claim the registry holds for a CV, leaving the (dead) key in place.
*
* Withdrawing a claim is not optional once the depth it justifies is being cleared: Pass 1b pins
* CvDEPTH back to max_depth for every still-active entry, so a stale claim would resurrect the very
* value we just released on the next swap. */
static void para_cvreg_purge(CV * cv) {
para_cvreg_entry_t * e = para_cvreg_lookup(cv, 0);
if (!e)
return;
para_cvreg_unpin(e);
para_cvreg_deactivate(e);
if (e->counts)
Safefree(e->counts);
e->counts = NULL;
e->arr_len = 0;
e->max_depth = 0;
}
/* Reset slot 0 of the pad a call would land on: slot 0 of a fresh perl pad is a REIFY-only,
* empty AV (pad_push), so a call re-entering a shared subroutine must find its @_ slot in
* exactly that state for pp_entersub's assert(!AvREAL(av)) / AvFILLp(av) == -1 invariants.
* AvREIFY_only -- not bare AvREAL_off -- restores the full canonical state perl expects (else
* the slot is neither-REAL-nor-REIFY and a later av_store re-turns it AvREAL). */
static void _clean_landing_pad(pTHX_ CV * cv, I32 depth) {
PADLIST * pl = CvPADLIST(cv);
if (!pl || depth <= 0 || depth > PadlistMAX(pl))
return;
/* A depth the registry still counts as occupied belongs to a fiber parked *inside* this CV, which will read
* its @_ again on resume. Resetting it destroys the victim's live state two ways: the handle read back out
lib/Acme/Parataxis.c view on Meta::CPAN
(CvDEPTH(cv) != occ) ? " <== DEPTH MISMATCH (assert would fire at pop)" : "",
(at_cd != at_occ) ? " <== DEPTH-PAD MISMATCH" : "",
(!at_occ || (SV *)at_occ == &PL_sv_undef) ? " <== MISSING PAD" : "");
}
}
/**
* @brief Restores subroutine call depths, syncs the parked-depth registry, and cleans argument pads.
*
* Runs at every swap. See the registry block above for the invariant this maintains.
*
* @param from The fiber being deposited (its frames become parked).
* @param to The fiber being resumed.
*/
static void _activate_current_depths(pTHX_ para_fiber_t * from, para_fiber_t * to) {
para_diag_swapno++;
/* Pass 0: the depositing fiber is parked now, so publish its live frame depths. Runs first
* so a CV shared by both fibers ends the swap with exactly `from` registered and `to` not. */
if (from && from != to && from->si && from->si->si_cxstack) {
for (I32 i = 0; i <= from->si->si_cxix; i++) {
PERL_CONTEXT * cx = &(from->si->si_cxstack[i]);
if (CxTYPE(cx) == CXt_SUB || CxTYPE(cx) == CXt_FORMAT) {
CV * cv = cx->blk_sub.cv;
if (cv && SvTYPE((SV *)cv) == SVt_PVCV)
para_cvreg_add(cv, cx->blk_sub.olddepth + 1);
}
}
}
PERL_SI * si = to->si;
if (!si || !si->si_cxstack)
return;
/* Pass 1: Restore CvDEPTH for all active frames of the resuming fiber (its own deepest
* frame depth per CV), deregister those depths now that the frames are live again, and
* flag CVs on this stack so Pass 1b leaves them at their exact value and Pass 1c does
* not settle a debt that a live frame is still entitled to. */
for (I32 i = 0; i <= si->si_cxix; i++) {
PERL_CONTEXT * cx = &(si->si_cxstack[i]);
if (CxTYPE(cx) == CXt_SUB || CxTYPE(cx) == CXt_FORMAT) {
CV * cv = cx->blk_sub.cv;
if (cv && SvTYPE((SV *)cv) == SVt_PVCV) {
I32 depth = cx->blk_sub.olddepth + 1;
CvDEPTH(cv) = depth;
para_cvreg_entry_t * e = para_cvreg_lookup(cv, 0);
if (e) {
para_cvreg_dec(e, depth);
e->on_stack = 1; /* even once the last claim drains: Pass 1c needs this */
}
}
}
}
/* 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 = ¶_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);
para_cvreg_pin(e);
}
/* Pass 1c: settle the pins. The registry only knows who *claims* a depth; it cannot know whether
* the frame that justified a claim ever popped. The resuming stack is ground truth for one fiber,
* and the swap is the only place this module is invoked while perl holds every live stack in a
* known place, so the debt a pin represents is settled here, not from a sub-return hook.
*
* A pinned CV is released only when (a) no fiber claims a depth in it and (b) no frame of it is
* live on the resuming stack. That is exactly the state in which nothing can ever use the pad or
* the depth again, so the fabricated CvDEPTH is unwound to perl's ordinary 0 -- the same release
* para_release_cv_depth() performs -- and the landing pad is made canonical once more.
*
* Pops that happen to be followed by a *later* swap are always repaid there: a fiber that pops its
* last frame of a CV must hand control back over a swap, and that swap's Pass 1c sees the register
* empty and the fiber bare. */
for (U32 k = 0; k < para_cvreg_pinned_n; k++) {
para_cvreg_entry_t * e = ¶_cvreg[para_cvreg_pinned[k]];
int was_on_stack = e->on_stack;
e->on_stack = 0;
if (e->max_depth > 0)
continue; /* still claimed by a parked fiber: Pass 1b repinned it this swap */
if (was_on_stack)
continue; /* a live frame is entitled to the depth Pass 1 gave it */
/* The register only knows *claims*, never frames. A frame that is still live can be parked on
* either stack including in a nested runlevel of it, which is not visible from the si the
* context happens to have stored so ask the runlevel chains of both stacks before unwinding
* the fabricated depth. A live frame means nothing may use pad 0 or depth 0 until it pops, so
* the entry stays pinned and the next swap retries this settle. */
if (para_cv_live_on_swap(aTHX_ from, to, e->cv)) {
PARA_DIAGF("[diag] SETTLE-SKIP-LIVE swap=%lu cv=%p dep=%d\n", para_diag_swapno, (void*)e->cv, CvDEPTH(e->cv));
continue;
}
PARA_DIAGF("[diag] SETTLE swap=%lu from=%p to=%p cv=%p dep=%d -> 0 live=%d\n",
para_diag_swapno, (void*)from, (void*)to, (void*)e->cv, CvDEPTH(e->cv), para_cv_frame_live(aTHX_ e->cv));
CvDEPTH(e->cv) = 0;
_clean_landing_pad(aTHX_ e->cv, 1);
para_cvreg_unpin(e); /* index k reused: do not advance */
k--;
}
/* Pass 2: Clean the landing pad for the NEXT call in each CV on the resuming stack. */
for (I32 i = 0; i <= si->si_cxix; i++) {
PERL_CONTEXT * cx = &(si->si_cxstack[i]);
if (CxTYPE(cx) == CXt_SUB || CxTYPE(cx) == CXt_FORMAT) {
CV * cv = cx->blk_sub.cv;
if (cv && SvTYPE((SV *)cv) == SVt_PVCV)
_clean_landing_pad(aTHX_ cv, CvDEPTH(cv) + 1);
}
}
lib/Acme/Parataxis.c view on Meta::CPAN
/* Use perl's allocator (Newx/Safefree) so that when perl grows these stacks with Renew()/realloc() it recognizes
* them as its own memory. Plain malloc'd memory panics ("realloc ... from wrong pool") in threaded-DEBUGGING perls
* that tag allocations per interpreter. */
PERL_SI * si = NULL;
PERL_CONTEXT * ctx_stack = NULL;
Newx(si, 1, PERL_SI);
Newx(ctx_stack, 65, PERL_CONTEXT);
Newx(c->markstack, sz, I32);
Newx(c->scopestack, sz, I32);
#ifdef DEBUGGING
Newx(c->scopestack_name, sz, const char *);
#endif
Newx(c->savestack, sz + SS_MAXPUSH, ANY);
Newx(c->tmps_stack, sz, SV *);
if (!si || !ctx_stack || !c->markstack || !c->scopestack || !c->savestack || !c->tmps_stack) {
Safefree(si);
Safefree(ctx_stack);
Safefree(c->markstack);
Safefree(c->scopestack);
#ifdef DEBUGGING
Safefree(c->scopestack_name);
#endif
Safefree(c->savestack);
Safefree(c->tmps_stack);
c->markstack = NULL;
c->scopestack = NULL;
c->savestack = NULL;
c->tmps_stack = NULL;
return;
}
/* Only the SI header needs zeroing; the control stacks are managed through their own ix/count fields and never read
* beyond them. */
memset(si, 0, sizeof(PERL_SI));
//
si->si_cxmax = 64;
si->si_cxstack = ctx_stack;
si->si_cxix = -1;
si->si_cxsubix = -1;
si->si_type = PERLSI_MAIN;
/* Link this fiber's stackinfo back to the permanent main stackinfo so that perl's POPSTACK_TO(PL_mainstack) (run on
* exit()) can pop out of the fiber and land on the main argument stack. pop_stackinfo panics ("panic: POPSTACK")
* and recurses via croak->my_exit if si_prev is NULL. We walk to the root rather than using the immediate current
* stackinfo so the chain never dangles after an intermediate fiber is destroyed. */
{
PERL_SI * root = PL_curstackinfo;
while (root->si_prev)
root = root->si_prev;
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) {
for (I32 i = 0; i <= c->tmps_ix; i++) {
SV * sv = c->tmps_stack[i];
if (sv && sv != &PL_sv_undef)
SvREFCNT_dec(sv);
}
}
if (c->curstack) {
/* Do NOT av_clear the fiber's argument stack here. Slots below the last-saved stack pointer may already have
* been popped and freed during earlier resume/yield cycles, so clearing them would double-decrement live SVs.
* The AV is reused verbatim; new pushes overwrite the stale slots before they are ever read. */
AvARRAY(c->curstack)[0] = &PL_sv_undef;
AvFILLp(c->curstack) = 0;
}
c->stack_sp_offset = 0;
if (si) {
si->si_cxix = -1;
si->si_stack = c->curstack;
}
/* exit()/POPSTACK_TO(PL_mainstack) inside this fiber must stop at the fiber's own argument stack instead of
* unwinding the shared main contexts whose pads are not current while a fiber runs. */
c->mainstack = c->curstack;
//
c->markstack_ptr = c->markstack;
*c->markstack_ptr = 0;
c->markstack_max = c->markstack + sz;
//
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;
c->ors_sv = PL_ors_sv;
c->defoutgv = PL_defoutgv;
lib/Acme/Parataxis.c view on Meta::CPAN
swap_perl_state(from, to);
#ifdef _WIN32
if (target_id == -1)
SwitchToFiber(main_fiber_handle);
else
SwitchToFiber(to->context);
#elif defined(USE_ASM_CORO)
para_coro_switch(&from->rsp, &to->rsp);
#else
swapcontext(&from->context, &to->context);
#endif
}
/**
* @brief Yields execution back to the caller or the main thread.
*
* Suspends the current fiber and returns a value to the context that last resumed or called this fiber.
*
* @param ret_val The Perl SV to "return" to the caller.
* @return SV* The value passed in when this fiber is eventually resumed.
*/
DLLEXPORT SV * coro_yield(SV * ret_val) {
dTHX;
if (current_fiber_id == -1)
return &PL_sv_undef;
para_fiber_t * self = fibers[current_fiber_id];
int parent = self->parent_id;
if (parent != -1 && (!fibers[parent] || fibers[parent]->finished))
parent = self->last_sender;
else if (parent == -1)
parent = self->last_sender;
if (parent >= 0 && (!fibers[parent] || fibers[parent]->finished))
parent = -1;
para_fiber_t * caller = (parent == -1) ? &main_context : fibers[parent];
/* Pass return value to caller */
if (caller->transfer_data != ret_val) {
if (caller->transfer_data && caller->transfer_data != &PL_sv_undef)
SvREFCNT_dec(caller->transfer_data);
caller->transfer_data = ret_val;
if (ret_val && ret_val != &PL_sv_undef)
SvREFCNT_inc(ret_val);
}
perform_switch(parent, 0);
/* Retrieve value passed back during resume */
SV * res = self->transfer_data;
self->transfer_data = &PL_sv_undef;
if (res && res != &PL_sv_undef)
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;
for (I32 i = 0; i < len; i++) {
SV ** svp = av_fetch(args, i, 0);
if (svp)
XPUSHs(*svp);
}
}
PUTBACK;
int count;
{
int volatile ret;
JMPENV_PUSH(ret);
if (ret == 2) {
/* exit() landed here. The fiber's saved top_env goes stale after its first yield (the coro_call
* guard it points at is popped), so a raw longjmp across stacks would jump to freed memory and
* crash in __longjmp; on x64 Windows the CRT cannot longjmp across stacks at all (0xC0000028 /
* STATUS_BAD_STACK). Either way we must NOT rethrow from this fiber stack. Record that this
* fiber's subtree asked to exit, mark it finished, and switch back to whoever called it.
* coro_call sees exit_pending and re-enters perl's exit machinery on the caller's stack, where
* the whole JMPENV chain lives on one stack. */
int fid = current_fiber_id;
if (fid >= 0 && fid < fiber_capacity && fibers[fid])
fibers[fid]->exit_pending = 1;
JMPENV_POP;
para_fiber_t * fc = (fid >= 0 && fid < fiber_capacity) ? fibers[fid] : c;
if (fc) {
fc->finished = true;
int parent = fc->parent_id;
if (parent != -1 && (!fibers[parent] || fibers[parent]->finished))
parent = -1;
perform_switch(parent, 0);
}
while (1)
coro_yield(&PL_sv_undef);
}
else if (ret != 0) {
/* A non-exit longjmp (die) that escaped the body's G_EVAL. This should not normally happen; finish the
* fiber with whatever is in $@ and hand control back to the caller. */
JMPENV_POP;
para_fiber_t * fc = (current_fiber_id >= 0 && current_fiber_id < fiber_capacity) ? fibers[current_fiber_id] : c;
if (fc) {
fc->finished = true;
int parent = fc->parent_id;
if (parent != -1 && (!fibers[parent] || fibers[parent]->finished))
parent = -1;
perform_switch(parent, 0);
}
while (1)
coro_yield(&PL_sv_undef);
}
lib/Acme/Parataxis.c view on Meta::CPAN
for (int i = 0; i < fiber_capacity; i++) {
if (fibers[i] == NULL && !fiber_destroyed[i]) {
idx = i;
break;
}
}
}
}
if (idx == -1)
return -2;
fiber_used++;
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) {
_release_slot(idx);
return -3;
}
memset(c, 0, sizeof(para_fiber_t));
/* Initialize Perl stacks */
init_perl_stacks(c);
if (!c->si) {
free(c);
_release_slot(idx);
return -3;
}
#ifndef _WIN32
c->stack_sz = FIBER_STACK_SZ;
c->stack_p = alloc_fiber_stack(c->stack_sz);
if (!c->stack_p) {
free_perl_stacks(aTHX_ c);
free(c);
_release_slot(idx);
return -3;
}
#else
c->context = NULL;
#endif
}
/* `owner` stamps which interpreter's arena owns this record, its stacks, and the SVs it references. The C tables
* 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;
}
/**
* @brief Resumes a fiber (asymmetric call).
*
* 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;
/* Guard the fiber run with our own jump environment. When the fiber longjmps out of the system (exit(), or a die
* that escapes the body's G_EVAL), perl never pops back into the scheduler: it unwinds the fiber's own contexts and
* jumps to the innermost env. That env chain is anchored here, so we can restore the perl state of whoever called
* coro_call (perl-owned stacks only) before rethrowing.
*
* The caller of this coro_call is the parent fiber (or main, for the top-level call). Restoring the PARENT's perl
* state matters: the next env on the chain is the parent's G_EVAL, and its case-2 cleanup runs `my_exit_jump()`
* which dounwinds the *current* savestack. If we left main's perl state current here, that dounwind would pop
* main's savestack entries (e.g. the scheduler's run_fiber_checked XSUB arena destructors) and perl_run's later
* LEAVE loop would free the same arenas a second time -> Affix "free from wrong pool" panic. Restoring the parent's
* own state makes the dounwind pop the parent's savestack (freed exactly once there, or leaked harmlessly if the
* parent's XSUB scopes were abandoned by the jump). Only the top-level wrapper (parent == main) restores main's
* state, so perl_run/perl_destruct finish on the main context. */
dJMPENV;
int volatile ret;
JMPENV_PUSH(ret);
if (ret) {
JMPENV_POP;
int parent = (fibers[fiber_id] ? fibers[fiber_id]->parent_id : -1);
if (parent >= 0 && parent < fiber_capacity && fibers[parent]) {
current_fiber_id = parent;
restore_perl_state(fibers[parent]);
}
else {
current_fiber_id = -1;
restore_perl_state(&main_context);
}
/* Propagate an exit() pending in the (sub)fiber we were resuming to the fiber that called us. Nested fiber
* exits then keep unwinding one stack level at a time and only re-enter perl's exit machinery on the main
* 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;
my_exit((U32)exit_status);
/* NOTREACHED */
}
if (fibers[fiber_id] && fibers[fiber_id]->finished) {
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 = &PL_sv_undef;
}
destroy_coro(fiber_id);
}
para_fiber_t * me = (current_fiber_id == -1) ? &main_context : fibers[current_fiber_id];
SV * res = me->transfer_data;
me->transfer_data = &PL_sv_undef;
if (res && res != &PL_sv_undef)
sv_2mortal(res);
return res;
}
/**
* @brief Runs a fiber to its next suspension point and cleans it up.
*
* Combines the scheduler's per-fiber work (resume, finish detection and destruction) into a single call so the FFI tax
* is paid once per fiber instead of four times.
*
* @param fiber_id Fiber to resume.
* @param args Argument arrayref to pass to the fiber, or NULL for none.
* @return int -1 fiber not found, 0 still running (re-enqueue),
* 1 finished and destroyed, 3 yielded 'WAITING'.
*/
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);
if (svp && *svp && SvPOK(*svp) && strEQ(SvPVX(*svp), "WAITING"))
return 3;
}
}
return 0;
}
/**
* @brief Creates a fiber object, its C context, and runs it inline.
*
* Merges the Perl-side spawn sequence (bless, create_fiber, run_fiber_checked) into a single FFI call. Returns the
* blessed fiber object with the run status stored at object slot 8 (F_LAST_STATUS): 1 finished, 0 yielded (re-enqueue),
* 3 yielded 'WAITING', -1 not found.
*
* @param user_code Coderef to run as the fiber body.
* @param class Class name to bless the fiber object into.
* @return SV* The blessed fiber object, or &PL_sv_undef on failure.
*/
DLLEXPORT SV * spawn_fiber(SV * user_code, SV * class) {
dTHX;
if (!user_code || user_code == &PL_sv_undef || !class || class == &PL_sv_undef)
return &PL_sv_undef;
char * cls = SvPV_nolen(class);
static HV * own_stash = NULL;
if (!own_stash)
own_stash = gv_stashpv("Acme::Parataxis", GV_ADD);
HV * stash = strEQ(cls, "Acme::Parataxis") ? own_stash : gv_stashpv(cls, GV_ADD);
AV * obj = newAV();
av_extend(obj, 8); /* pre-size to fit every F_* slot in one allocation */
SV * objrv = newRV_noinc((SV *)obj);
sv_bless(objrv, stash);
av_store(obj, 0, SvREFCNT_inc(user_code)); /* F_CODE */
int fid = create_fiber(user_code, objrv);
if (fid < 0) {
SvREFCNT_dec(objrv);
/* Carry the create_fiber error code out: -2 is the policy limit ("table full"), -3 is a failed stack mmap
* (address-space / data-segment budget on platforms without MAP_NORESERVE). The caller distinguishes them. */
return newSViv(fid);
}
av_store(obj, 4, newSViv(fid)); /* F_FID */
int st = run_fiber_checked(fid, &PL_sv_undef);
av_store(obj, 8, newSViv(st)); /* F_LAST_STATUS */
return objrv;
}
/**
* @brief Reclaims all completed background jobs in a single call.
*
* Returns an arrayref of [fiber_id, result] pairs for every finished job, freeing the job slots as it goes.
*
* @return SV* Arrayref of completed jobs (may be empty).
*/
DLLEXPORT void drain_jobs(SV * out_ref) {
dTHX;
if (!out_ref || !SvROK(out_ref) || SvTYPE(SvRV(out_ref)) != SVt_PVAV)
return;
AV * out = (AV *)SvRV(out_ref);
av_clear(out);
while (1) {
int job_idx = check_for_completion();
if (job_idx == -1)
break;
AV * pair = newAV();
av_push(pair, newSViv(get_job_coro_id(job_idx)));
SV * res = get_job_result(job_idx);
/* get_job_result returns a mortal parked on the caller's tmps stack; copy it so the pair owns its own SV
* instead of double-decrementing the mortal when both the pair and FREETMPS release it. */
av_push(pair, (res && res != &PL_sv_undef) ? newSVsv(res) : &PL_sv_undef);
av_push(out, newRV_noinc((SV *)pair));
free_job_slot(job_idx);
}
}
/**
* @brief Transfers control directly to another fiber (symmetric).
*
* Suspends the current fiber and switches directly to the target. No parent/child relationship is established.
*
* @param target_id Fiber ID to transfer to.
* @param args Arguments to pass to the target.
* @return SV* Data eventually transferred back to this fiber.
*/
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);
}
perform_switch(target_id, 1);
if (target_id >= 0 && fibers[target_id] && fibers[target_id]->finished) {
if (fibers[target_id]->transfer_data && fibers[target_id]->transfer_data != &PL_sv_undef) {
SvREFCNT_dec(fibers[target_id]->transfer_data);
fibers[target_id]->transfer_data = &PL_sv_undef;
}
destroy_coro(target_id);
}
para_fiber_t * me = (current_fiber_id == -1) ? &main_context : fibers[current_fiber_id];
SV * res = me->transfer_data;
me->transfer_data = &PL_sv_undef;
if (res && res != &PL_sv_undef)
sv_2mortal(res);
return res;
}
/** @brief Returns 1 if the fiber has finished execution. */
DLLEXPORT int is_finished(int fiber_id) {
if (fiber_id < 0 || fiber_id >= fiber_capacity)
return 0;
return (fibers[fiber_id] && fibers[fiber_id]->finished) ? 1 : 0;
}
/**
* @brief Returns the Perl object bound to a live fiber, if any.
*
* Replaces the Perl-level %REGISTRY lookup: the C context already owns a strong reference to the object via self_ref,
* so no separate registry or weak-reference bookkeeping is needed on the Perl side.
*
* @param fiber_id The fiber ID to look up.
* @return SV* The blessed fiber object (mortalized), or &PL_sv_undef.
*/
DLLEXPORT SV * get_fiber_by_id(int fiber_id) {
dTHX;
if (fiber_id < 0 || fiber_id >= fiber_capacity || !fibers[fiber_id])
return &PL_sv_undef;
SV * self_ref = fibers[fiber_id]->self_ref;
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;
if (CvDEPTH(cv) > 0)
CvDEPTH(cv) = 0;
}
/**
* @brief Clears active pads in the fiber stack.
*
* Internal helper used during fiber destruction to ensure all active lexical scopes are unwound and their variables
* freed.
*
* @param si The Stack Info structure of the fiber.
*/
static void _clear_pads_in_stack(pTHX_ PERL_SI * si) {
if (!si || !si->si_cxstack)
return;
for (I32 i = si->si_cxix; i >= 0; i--) {
PERL_CONTEXT * cx = &(si->si_cxstack[i]);
if (CxTYPE(cx) == CXt_SUB || CxTYPE(cx) == CXt_FORMAT) {
CV * cv = cx->blk_sub.cv;
if (cv && SvTYPE((SV *)cv) == SVt_PVCV) {
PADLIST * padlist = CvPADLIST(cv);
if (padlist) {
I32 depth = cx->blk_sub.olddepth + 1;
if (depth > 0 && depth <= PadlistMAX(padlist)) {
AV * pad = (AV *)PadlistARRAY(padlist)[depth];
if (pad && SvTYPE((SV *)pad) == SVt_PVAV)
av_clear(pad);
}
}
if (CvDEPTH(cv) > 0)
CvDEPTH(cv)--;
}
}
}
}
/**
* @brief Releases the pad bookkeeping for a CV that is about to be replaced or finalised.
*
* Pass 1b fabricates CvDEPTH values (see the parked-frame depth registry above): a CV some fiber is
* parked inside gets CvDEPTH = its deepest parked depth, so the next ++CvDEPTH() lands above every
* parked pad. That is the right value while the parked frame exists, but nothing withdraws it once
* the frame is gone -- cx_popsub_common() restores depths only for frames that actually leave, and a
* swap resuming a fiber that holds no frame of the CV skips it entirely. The count then survives for
* good and the CV looks permanently active to the rest of perl: cv_undef() refuses to finalise a CV
* whose CvDEPTH is positive, so replacing it dies with "Can't undef active subroutine" and reports
* the *replaced* sub's own definition site as the location.
*
* Acme::Parataxis::Compat::disable_transparent_unblocking() retires the CORE::GLOBAL overrides it
* installed, which is precisely that finalisation, so it calls this on each override before handing
( run in 0.832 second using v1.01-cache-2.11-cpan-234fa220139 )