coro_int.h

/*-
 * Copyright (c) 2026, The XTC Project
 * Use of this source code is governed by the ISC License.
 *
 * src/inc/coro_int.h
 *      Internal types for the L2 coroutine substrate.
 */
 
#ifndef XTC_CORO_INT_H
#define XTC_CORO_INT_H
 
#include "coro_select.h"   /* XTC_CORO_FCTX: which substrate is live */
 
#if defined(_WIN32)
# include <windows.h>
#elif !defined(XTC_CORO_FCTX)
# include <ucontext.h>
#endif
 
#include "xtc_async.h"
#include "loop_int.h"
 
/*
 * The fiber context attached to an xtc_task_t when it was spawned
 * via xtc_async.  Lives in the per-task arena (currently malloc).
 */
struct xtc_coro {
#if defined(_WIN32)
        LPVOID       fiber;         /* the coroutine's own Win32 fiber */
        LPVOID       loop_fiber;    /* return-to-loop fiber pointer */
#elif !defined(XTC_CORO_FCTX)
        ucontext_t   ctx;          /* the coroutine's own machine state */
        ucontext_t   loop_ctx;     /* return-to-loop context (set on resume) */
#else
        /* fcontext substrate (coro_fctx.c): a single saved stack pointer.
         * On make_fcontext it is the fresh entry point; each yield/await
         * overwrites it with the coroutine's current resume point.  The
         * scheduler's return point is a per-thread cursor in coro_fctx.c,
         * not stored here, because coroutines always return to the
         * scheduler, never directly to one another. */
        void        *fctx;
#endif
        void        *stack;
        size_t       stack_sz;
        xtc_coro_fn  fn;
        void        *arg;
        intptr_t     result;
        int          done;          /* 1 once fn has returned */
 
        xtc_task_t  *self;          /* back-pointer to our task */
        /*
         * The proc layer's handle for THIS fiber, published once by
         * __proc_entry from the fiber itself.
         *
         * It exists because __current_proc is a thread-local that
         * __xtc_fiber_ctx_save/restore carries across a yield, and under the
         * multi-loop executor the restored value can name a DIFFERENT proc
         * than the fiber now running -- measured on FreeBSD at 48909 wrong
         * against 511 right, confirmed independently by locating a stack
         * address (no thread-local involved) inside the registered coro
         * stack ranges.  A primitive that registers per-task state must not
         * act on the wrong proc, so it reads its identity from the running
         * fiber, and this is that link.  void * to keep the proc layer's
         * struct out of this header.
         */
        void        *proc;          /* struct xtc_proc * */
        xtc_task_t  *waiter;        /* task awaiting this one (or NULL) */
 
        /*
         * When non-NULL, this coroutine has just registered itself as
         * the `waiter` of another and is yielding into the loop with
         * the intent of staying parked rather than rescheduling.  The
         * step function reads and clears this flag to decide between
         * RESCHED and PENDING.
         */
        struct xtc_coro *_parked_on;
 
        /*
         * Sanitizer fiber-switch save token (ASan/TSan/LSan).  Holds this
         * coro's "fake stack" across a park so __sanitizer_start/finish_
         * switch_fiber can track the user-space stack switch and stop
         * mis-attributing stack memory.  Unused (always NULL) in a
         * non-sanitized build.  See XTC_FIBER_SWITCH_ANNOTATE in
         * coro_fctx.c / coro_uctx.c.
         */
        void        *san_fake_stack;
 
        /*
         * TSan fiber-IDENTITY token (clang ThreadSanitizer only).  TSan
         * does NOT implement __sanitizer_*_switch_fiber; it needs each
         * coroutine represented as a TSan "fiber object" (__tsan_create_
         * fiber at create, __tsan_switch_to_fiber at every switch,
         * __tsan_destroy_fiber at teardown) so it can carry per-fiber
         * happens-before across cooperative switches instead of seeing
         * them as one confused thread.  Distinct from san_fake_stack (the
         * two sanitizer models are mutually exclusive per build).  Always
         * NULL unless built with clang -fsanitize=thread.  See
         * XTC_TSAN_FIBERS in coro_fctx.c / coro_uctx.c.
         */
        void        *tsan_fiber;
 
        /* Valgrind stack id from VALGRIND_STACK_REGISTER for this coro's
         * stack, set whenever `stack` is (coro_common.h). */
        unsigned     vg_stack_id;
};
 
/* Shared by loop.c -- the currently-running coroutine on this loop.  */
extern XTC_THREAD_LOCAL struct xtc_coro *__xtc_current_coro;
 
/* Forward declarations for the dispatch glue.  */
int  __xtc_coro_step(xtc_task_t *self, void *user);
 
/*
 * Internal spawn with an explicit pin flag.  The public xtc_async wraps
 * this with pinned=1 (the long-standing default: a coro's task is not
 * work-stealable).  pinned=0 places the task on the stealable deque so
 * it can migrate across loops -- used by the proc layer when
 * xtc_proc_opts_t.migratable is set.  Every coro backend
 * (coro_fctx/uctx/winfiber) defines it.
 */
int  __xtc_async_ex(xtc_loop_t *loop, xtc_coro_fn fn, void *arg, int pinned,
                    xtc_task_t **out_task);
 
/* The task wrapping the currently-running coroutine on this thread,
 * or NULL when not running inside a coroutine.  Lets lower-level
 * primitives (e.g. xtc_amutex) find the current task to park it. */
xtc_task_t *__xtc_current_task(void);
 
/* xtc_loop_fini: unmap the loop's spare fiber stacks (a no-op for the
 * winfiber substrate, which does not mmap its stacks). */
void __xtc_coro_stack_spare_fini(xtc_loop_t *loop);
 
/* __xtc_current_coro read through an out-of-line call on the CURRENT
 * thread.  Use this, not the variable, in code that may run after a
 * stack switch on a migratable fiber: compilers keep a thread-local's
 * address live across calls, so a direct read after the fiber resumed
 * on another carrier sees the previous thread's slot. */
struct xtc_coro *__xtc_current_coro_get(void);
 
/*
 * xtc_await's kill point, at the top of each park round (all three
 * substrates).  The first round has nothing pending unless the kill came
 * first, and a later round runs only after a wake: if that wake was not
 * the target's completion and a kill is pending, stop being the target's
 * waiter (the target's DONE path reads target->waiter on this loop, so
 * this is single-threaded with it) and deliver.  __xtc_fiber_kill_poll
 * unwinds (does not return), or latches the kill under a mask and
 * returns, and the await then re-registers and waits on.
 */
#define AWAIT_KILL_POLL(me, target) do {                                 \
        if (__xtc_fiber_kill_poll != NULL) {                             \
                if ((target)->waiter == (me)->self)                      \
                        (target)->waiter = NULL;                         \
                __xtc_fiber_kill_poll();                                 \
        }                                                                \
} while (0)
 
#endif /* XTC_CORO_INT_H */