Acme-Parataxis
view release on metacpan or search on metacpan
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.) */
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
/** @brief Default limit on how many fibers may exist at once. Generous on purpose: the table grows up to it on
* demand, so memory (64MB of lazily mapped stack per fiber) runs out long before this does. Adjustable with
* set_max_fibers(). */
#define DEFAULT_FIBER_LIMIT 65536
/** @brief Absolute bound on table growth, independent of the limit above. Growth only ever happens when every
* allocated slot is already in use, so the table stays within a doubling of the fibers actually present and this is
* never approached in practice. */
#define HARD_FIBER_LIMIT (1 << 20)
/** @brief Fibers that may exist at once; create_fiber refuses past this. Adjustable with set_max_fibers(). */
static int max_fibers = DEFAULT_FIBER_LIMIT;
/** @brief Entries allocated in every table below. Fibers are only ever indexed from the scheduler thread, so growing
* these (realloc) never races a worker thread. */
static int fiber_capacity = 0;
/** @brief Slots currently handed out, whether the fiber is live or still waiting for its jobs to drain. Capped by
* max_fibers, which is what makes "the table is full" a policy decision rather than a property of the array. */
static int fiber_used = 0;
/** @brief Array of active fiber structures (fiber_capacity entries) */
static para_fiber_t ** fibers = NULL;
/** @brief LIFO of free fiber slot indexes (O(1) allocation), fiber_capacity entries */
static int * free_slots = NULL;
/** @brief Number of free slots currently on the free list */
static int free_slot_count = 0;
/** @brief The context representing the main Perl thread */
static para_fiber_t main_context;
/** @brief ID of the currently executing fiber (-1 for Main) */
static int current_fiber_id = -1;
/** @brief Size of the background job queue */
#define MAX_JOBS 1024
/** @brief Fixed-size array for background tasks */
static job_t job_slots[MAX_JOBS];
/** @brief Mutex protecting access to the job queue */
static para_mutex_t queue_lock;
/*
* Completed-job notification ring.
*
* Workers push the index of every finished job into this ring so that check_for_completion() can find completed work in
* O(1) instead of scanning all MAX_JOBS slots under the lock on every scheduler tick.
*/
static int done_queue[MAX_JOBS + 1];
static int done_head = 0;
static int done_tail = 0;
/*
* Number of jobs that have been submitted but not yet reclaimed by the main thread via free_job_slot(). Only touched by
* the main thread, so it needs no lock. The scheduler uses it to skip polling entirely when no background work is in
* flight.
*/
static int outstanding_jobs = 0;
lib/Acme/Parataxis.c view on Meta::CPAN
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--;
UNLOCK(queue_lock);
}
#ifdef _WIN32
Sleep(1);
#else
usleep(1000);
#endif
}
}
return 0;
}
/**
* @brief Initializes the background thread pool.
*
* Automatically detects the CPU count and spawns worker threads. This function is called
* automatically by `init_system` and `submit_c_job`.
*/
DLLEXPORT void init_threads() {
dTHX;
if (threads_initialized)
return;
LOCK_INIT(queue_lock);
PARA_COND_INIT(queue_cond);
#ifndef _WIN32
if (pipe(shutdown_pipe) != 0)
shutdown_pipe[0] = shutdown_pipe[1] = -1;
#endif
for (int i = 0; i < MAX_JOBS; i++)
job_slots[i].status = JOB_FREE;
if (max_thread_pool_size == 0) {
max_thread_pool_size = get_cpu_count();
if (max_thread_pool_size < MIN_THREAD_POOL)
max_thread_pool_size = MIN_THREAD_POOL;
if (max_thread_pool_size > MAX_THREADS)
max_thread_pool_size = MAX_THREADS;
}
/* Start with a small "seed" pool of 2 threads */
_spawn_workers(2);
threads_initialized = 1;
}
/**
* @brief Submits a C-level task to the background pool.
*
* @param type The task type constant (TASK_*).
* @param arg Input integer or pointer data.
* @param timeout_ms Timeout for I/O operations.
* @return int The index of the submitted job, or -1 if the queue is full.
*/
DLLEXPORT int submit_c_job(int type, int64_t arg, int timeout_ms) {
if (!threads_initialized)
init_threads();
int idx = -1;
LOCK(queue_lock);
for (int i = 0; i < MAX_JOBS; i++) {
if (job_slots[i].status == JOB_FREE) {
idx = i;
break;
}
}
if (idx != -1) {
job_slots[idx].fiber_id = current_fiber_id;
job_slots[idx].type = type;
job_slots[idx].input.i = arg;
job_slots[idx].timeout_ms = timeout_ms;
job_slots[idx].status = JOB_NEW;
job_slots[idx].recall = 0;
outstanding_jobs++;
if (current_fiber_id >= 0 && current_fiber_id < fiber_capacity)
job_refcount[current_fiber_id]++;
/* Dynamic scaling: spawn exactly the deficit (pending - idle), bounded by the configured pool size. This
* must run AFTER the job is inserted: the previous check counted only jobs that were already pending, so a
* lone submission against a pool whose every worker sat in a long TASK_SLEEP saw pending == 0, spawned
* nothing, and queued behind sleeps lasting hundreds of milliseconds. A 10 ms await_sleep submitted while
* both seeded workers held a 400 ms and a 600 ms sleep woke at 400 ms instead of 10 ms. Pending work with
* no idle worker to claim it is exactly the case that needs a worker, so now that is what is measured. */
int pending_count = 0;
for (int i = 0; i < MAX_JOBS; i++)
if (job_slots[i].status == JOB_NEW)
pending_count++;
int idle_count = current_thread_count - busy_thread_count;
if (pending_count > idle_count)
_spawn_workers(pending_count - idle_count); /* stops at max_thread_pool_size / MAX_THREADS */
/* Broadcast (not signal): a single wakeup may be swallowed by a worker parked in its timed sleep wait
* (which only re-checks its absolute deadline and continues), leaving idle workers with no wakeup and
* JOB_NEW entries unclaimed until some long sleep ends. */
PARA_COND_BROADCAST(queue_cond);
}
UNLOCK(queue_lock);
return idx;
}
/**
* @brief Polls the queue for any completed background jobs.
*
* @return int Index of a finished job, or -1 if none are ready.
*/
DLLEXPORT int check_for_completion() {
if (!threads_initialized)
init_threads();
int job_idx = -1;
LOCK(queue_lock);
if (done_head != done_tail) {
job_idx = done_queue[done_head];
lib/Acme/Parataxis.c view on Meta::CPAN
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);
}
count = call_sv(c->user_cv, G_SCALAR | G_EVAL);
}
SPAGAIN;
SV * ret_val = &PL_sv_undef;
if (count == 1)
ret_val = POPs;
PUTBACK;
c->finished = true;
/* Cleanup transfer data and store result */
if (c->transfer_data && c->transfer_data != &PL_sv_undef) {
SvREFCNT_dec(c->transfer_data);
c->transfer_data = &PL_sv_undef;
}
if (ret_val && ret_val != &PL_sv_undef) {
SvREFCNT_inc(ret_val);
c->transfer_data = ret_val;
}
/* Update the Perl-level Acme::Parataxis object.
*
* The object is a blessed flat arrayref; slot layout mirrors the Perl-side constants F_ERROR=2, F_RESULT=3,
* F_IS_READY=5, F_CALLBACKS=6. Writing the result/error slots directly avoids a method dispatch per fiber
* completion; the callback dispatch sub is only invoked when callbacks were actually registered. */
if (c->self_ref && SvROK(c->self_ref)) {
AV * obj = (AV *)SvRV(c->self_ref);
SV ** ready = av_fetch(obj, 5, 0);
if (!(ready && *ready && SvTRUE(*ready))) {
int died;
if (SvROK(ERRSV) && SvOBJECT(SvRV(ERRSV)))
died = 1; /* blessed exceptions are always errors; e.g. Error::Timeout with an overloaded "" */
else
died = SvTRUE(ERRSV);
if (died) {
av_store(obj, 2, newSVsv(ERRSV));
av_store(obj, 5, &PL_sv_yes);
}
else {
if (ret_val != &PL_sv_undef)
av_store(obj, 3, SvREFCNT_inc(ret_val));
av_store(obj, 5, &PL_sv_yes);
}
/* F_IS_DONE=1, F_FID=-1: the fiber is finished, so the object is marked done and must not touch the
* (already recycled) C context from DESTROY/is_done. */
av_store(obj, 1, &PL_sv_yes);
SV ** fp = av_fetch(obj, 4, 0);
if (fp && *fp)
sv_setiv(*fp, -1);
SV ** cbs = av_fetch(obj, 6, 0);
if (cbs && *cbs && SvROK(*cbs) && SvTYPE(SvRV(*cbs)) == SVt_PVAV) {
AV * cbav = (AV *)SvRV(*cbs);
if (av_len(cbav) >= 0) {
dSP;
ENTER;
SAVETMPS;
PUSHMARK(SP);
XPUSHs(c->self_ref);
PUTBACK;
call_method("_dispatch_callbacks", G_DISCARD);
FREETMPS;
LEAVE;
}
}
}
}
FREETMPS;
LEAVE;
/* Final yield back to caller */
coro_yield(c->transfer_data ? c->transfer_data : &PL_sv_undef);
/* Loop indefinitely if resumed after finish */
while (1)
coro_yield(&PL_sv_undef);
}
#ifdef _WIN32
/** @brief Windows fiber callback wrapper. */
static void WINAPI fiber_entry(void * param) { para_entry_point((para_fiber_t *)param); }
#else
/** @brief POSIX makecontext callback wrapper. */
static void posix_entry(int fiber_id) { para_entry_point(fibers[fiber_id]); }
#endif
#ifndef _WIN32
/**
* @brief Allocates a fiber stack backed by a lazily-committed mmap mapping.
*
* The usable stack is FIBER_STACK_SZ with a PROT_NONE guard page below it. The mapping uses FIBER_MMAP_FLAGS:
* MAP_NORESERVE as a real flag (Linux, FreeBSD), so a 64 MB reservation is free until touched, and a small
* FIBER_STACK_SZ where it is missing or a 0-valued legacy no-op (macOS, OpenBSD), so a tableful of fibers stays
( run in 1.635 second using v1.01-cache-2.11-cpan-234fa220139 )