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 = &para_cvreg[para_cvreg_active[k]];
        int was_on_stack = e->on_stack;
        if (was_on_stack)
            continue; /* Pass 1 set this CV to its exact value; a pin here would gift a level.
                       * Keep on_stack set so Pass 1c knows a live frame is being resumed. */
        e->on_stack = 0;
        CvDEPTH(e->cv) = e->max_depth;
        _clean_landing_pad(aTHX_ e->cv, e->max_depth + 1);
        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 = &para_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 )