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 )