EgretDoc - coroutine

Location:system/coroutine

Module

Module documentation.

modulecoroutine

Classes

Classes and inheritance.

classcoroutine::CoQueue

@briefCoQueue

@noteInternal helper

class CoQueue {
    /*
    @brief In stack

classcoroutine::Scheduler

@briefScheduler

class Scheduler {
    /*
    @brief Run queue

Functions

Free functions and class methods.

functioncoroutine::co_rt_alloc

Signatureextern func co_rt_alloc(size: Int) -> Ptr;

extern func co_rt_alloc(size: Int) -> Ptr;
/*
@brief Binds the low-level runtime symbol `co_rt_free`.

@briefBinds the low-level runtime symbol `co_rt_alloc`.

@detailsThis function is an external entry point used by system modules to access native runtime capabilities such as filesystem, networking, threading, GC, cryptography, or platform operations. Prefer the safe wrapper functions in the same file when available. When calling this entry directly, pass validated arguments that match the signature and handle failures according to the return-value convention.

@param

sizeSize or length value that limits how much data the operation processes.

@returnReturns the operation result as `Ptr`.

functioncoroutine::co_rt_free

Signatureextern func co_rt_free(p: Ptr) -> Void;

extern func co_rt_free(p: Ptr) -> Void;
/*
@brief Binds the low-level runtime symbol `eg_gc_register_root_range`.

@briefBinds the low-level runtime symbol `co_rt_free`.

@param

pNative pointer address passed to the runtime binding.

@returnVoid

functioncoroutine::eg_gc_register_root_range

Signatureextern func eg_gc_register_root_range(lo: Ptr, hi: Ptr) -> Void;

extern func eg_gc_register_root_range(lo: Ptr, hi: Ptr) -> Void;
/*
@brief Binds the low-level runtime symbol `eg_gc_unregister_root_range`.

@briefBinds the low-level runtime symbol `eg_gc_register_root_range`.

@param

loLower pointer, index, or numeric boundary used by the operation.
hiUpper pointer, index, or numeric boundary used by the operation.

@returnVoid

functioncoroutine::eg_gc_unregister_root_range

Signatureextern func eg_gc_unregister_root_range(lo: Ptr) -> Void;

extern func eg_gc_unregister_root_range(lo: Ptr) -> Void;
/*
@brief Binds the low-level runtime symbol `coctx_size`.

@briefBinds the low-level runtime symbol `eg_gc_unregister_root_range`.

@param

loLower pointer, index, or numeric boundary used by the operation.

@returnVoid

functioncoroutine::coctx_size

Signatureextern func coctx_size() -> Int;

extern func coctx_size() -> Int;
/*
@brief Binds the low-level runtime symbol `coctx_init`.

@briefBinds the low-level runtime symbol `coctx_size`.

@returnReturns the operation result as `Int`.

functioncoroutine::coctx_init

Signatureextern func coctx_init(ctx: Ptr, stack_top: Ptr, entry: Int, arg0: Int) -> Void;

extern func coctx_init(ctx: Ptr, stack_top: Ptr, entry: Int, arg0: Int) -> Void;
/*
@brief Binds the low-level runtime symbol `coctx_swap`.

@briefBinds the low-level runtime symbol `coctx_init`.

@param

ctxNative context pointer or runtime context object used by the operation.
stack_topPointer to the top of the coroutine stack.
entryEntry function address used to start a coroutine or native callback.
arg0First raw argument passed to the entry function.

@returnVoid

functioncoroutine::coctx_swap

Signatureextern func coctx_swap(from: Ptr, to: Ptr) -> Void;

extern func coctx_swap(from: Ptr, to: Ptr) -> Void;
/*
@brief Binds the low-level runtime symbol `co_trampoline`.

@briefBinds the low-level runtime symbol `coctx_swap`.

@param

fromSource endpoint, path, index, or lower boundary for the operation.
toDestination endpoint, path, index, or upper boundary for the operation.

@returnVoid

functioncoroutine::co_trampoline

Signatureextern func co_trampoline(co: Int) -> Void;

extern func co_trampoline(co: Int) -> Void;

/*

@briefBinds the low-level runtime symbol `co_trampoline`.

@param

coCoroutine handle or coroutine object controlled by the scheduler operation.

@returnVoid

functioncoroutine::co_arg

Signaturefunc co_arg(co: Int) -> Int

func co_arg(co: Int) -> Int {
    return load64(ptr_add(ptr(co), 32));
}

@briefGet coroutine argument

@param

coCoroutine handle (Int)

@returnThe arg passed when the coroutine was created

functioncoroutine::co_ret

Signaturefunc co_ret(co: Int) -> Int

func co_ret(co: Int) -> Int {
    return load64(ptr_add(ptr(co), 64));
}

@briefGet coroutine return value

@param

coCoroutine handle (Int)

@returnCoroutine function return value

functioncoroutine::co_done

Signaturefunc co_done(co: Int) -> Bool

func co_done(co: Int) -> Bool {
    return load64(ptr_add(ptr(co), 56)) != 0;
}

@briefCheck whether a coroutine is done

@detailsReturns whether the coroutine has finished execution.

@param

coCoroutine handle (Int)

@returnWhether the coroutine has finished

functioncoroutine::yield_now

Signaturefunc yield_now(co: Int) -> Void

func yield_now(co: Int) -> Void {
    let base: Ptr = ptr(co);
    let cur: Ptr = ptr(load64(ptr_add(base, 0)));

@briefYield

@param

coCoroutine handle (Int)

@returnVoid

@noteUsually called inside the coroutine function.

functioncoroutine::checkpoint

Signaturefunc checkpoint(co: Int) -> Void

func checkpoint(co: Int) -> Void {
    let base: Ptr = ptr(co);
    let h: Int = load64(ptr_add(base, 48));

@briefCheckpoint

@param

coCoroutine handle (Int)

@returnVoid

@noteSoft preemption does not forcibly interrupt the coroutine.

functioncoroutine::co_new

Signaturefunc co_new(fn: (Int) -> Int, arg: Int, stack_bytes: Int, main_ctx: Ptr, preempt_h: Int) -> Int

func co_new(fn: (Int) -> Int, arg: Int, stack_bytes: Int, main_ctx: Ptr, preempt_h: Int) -> Int {
    let co_mem: Ptr = co_rt_alloc(72);
    let co: Int = ptr_to_int(co_mem);

@briefco_new helper

@param

fnCoroutine entry function (signature: (Int)->Int)
argArgument passed to fn
stack_bytesStack size in bytes
main_ctxScheduler main context pointer
preempt_hSoft-preempt flag handle (0 means disabled)

@returnCoroutine handle (Int)

@noteInternal helper

functioncoroutine::co_free

Signaturefunc co_free(co: Int) -> Void

func co_free(co: Int) -> Void {
    if co == 0 {
        return;

@briefProvides the system library operation `co_free`.

@detailsExecutes the `co_free` system-library API. The documented parameters define the accepted inputs, ownership requirements, range limits, and timeout behavior for this call. Callers must check returned `ErrCode` values or boolean status values before using the result.

@param

coCoroutine handle or coroutine object controlled by the scheduler operation.

@returnVoid

functioncoroutine::CoQueue.init

Signaturefunc init(self: coroutine.CoQueue) -> Void

    func init(self: coroutine.CoQueue) -> Void {
        self.in = new collections.Vector<Int>();
        self.out = new collections.Vector<Int>();

@briefInitialize the queue

@param

selfCoQueue instance

@returnVoid

functioncoroutine::CoQueue.len

Signaturefunc len(self: coroutine.CoQueue) -> Int

    func len(self: coroutine.CoQueue) -> Int {
        return self.in.len() + self.out.len();
    }

@briefGet length

@detailsReturns the number of coroutines in the queue.

@param

selfCoQueue instance

@returnNumber of coroutines

functioncoroutine::CoQueue.push

Signaturefunc push(self: coroutine.CoQueue, co: Int) -> Void

    func push(self: coroutine.CoQueue, co: Int) -> Void {
        _ = self.in.push(co);
    }

@briefpush

@detailsEnqueues a coroutine handle.

@param

selfCoQueue instance
coCoroutine handle (Int)

@returnVoid

functioncoroutine::CoQueue.pop

Signaturefunc pop(self: coroutine.CoQueue) -> Int

    func pop(self: coroutine.CoQueue) -> Int {
        if self.out.len() == 0 {
            loop (; self.in.len() > 0; ) {

@briefpop

@param

selfCoQueue instance

@returnCoroutine handle (Int).

functioncoroutine::CoQueue.free

Signaturefunc free(self: coroutine.CoQueue) -> Void

    func free(self: coroutine.CoQueue) -> Void {
        _ = self.in.free();
        _ = self.out.free();

@brieffree

@detailsFrees the internal Vector<Int> resources.

@param

selfCoQueue instance

@returnVoid

functioncoroutine::CoQueue.dispose

Signaturefunc dispose(self: coroutine.CoQueue) -> Void

    func dispose(self: coroutine.CoQueue) -> Void {
        _ = self.free();
    }

@briefExplicitly releases resources owned by `CoQueue`.

@detailsThis method deterministically cleans up file descriptors, network connections, native handles, buffers, or other external resources. Implementations should be idempotent where possible, and repeated calls must not corrupt object state.

@param

selfThe current instance whose fields, handles, buffers, or external resources are read or modified by this method.

@returnVoid

functioncoroutine::CoQueue.deinit

Signaturefunc deinit(self: coroutine.CoQueue) -> Void

    func deinit(self: coroutine.CoQueue) -> Void {
        _ = self.free();
    }

@briefdeinit

@detailsReleases the internal Vector<Int> resources when the queue is collected.

@param

selfCoQueue instance

@returnVoid

functioncoroutine::timer_loop

Signaturefunc timer_loop(arg: Any) -> Int

func timer_loop(arg: Any) -> Int {
    let cfg: Int = arg => Int;
    let base: Ptr = ptr(cfg);

@brieftimer_loop helper

@param

argOpaque thread entry argument that must contain the integer address of the timer configuration block laid out as `preempt_h`, `running_h`, and `quantum_ms`.

@returnThread return value (always 0)

@noteInternal helper

functioncoroutine::Scheduler.init

Signaturefunc init(self: coroutine.Scheduler) -> Void

    func init(self: coroutine.Scheduler) -> Void {
        _ = native_init();
        self.q = new coroutine.CoQueue();

@briefInitialize the scheduler

@param

selfScheduler instance

@returnVoid

functioncoroutine::Scheduler.free

Signaturefunc free(self: coroutine.Scheduler) -> Void

    func free(self: coroutine.Scheduler) -> Void {
        _ = self.disable_preemptive();
        _ = self.q.dispose();

@briefFree scheduler resources

@detailsFrees the queue and soft-preemption-related atomic handles (if created).

@param

selfScheduler instance

@returnVoid

functioncoroutine::Scheduler.dispose

Signaturefunc dispose(self: coroutine.Scheduler) -> Void

    func dispose(self: coroutine.Scheduler) -> Void {
        _ = self.free();
    }

@briefExplicitly releases resources owned by `Scheduler`.

@param

selfThe current instance whose fields, handles, buffers, or external resources are read or modified by this method.

@returnVoid

functioncoroutine::Scheduler.deinit

Signaturefunc deinit(self: coroutine.Scheduler) -> Void

    func deinit(self: coroutine.Scheduler) -> Void {
        _ = self.free();
    }

@briefdeinit

@detailsReleases scheduler resources when the scheduler is collected.

@param

selfScheduler instance

@returnVoid

functioncoroutine::Scheduler.enable_preemptive

Signaturefunc enable_preemptive(self: coroutine.Scheduler, quantum_ms: Int) -> Void

    func enable_preemptive(self: coroutine.Scheduler, quantum_ms: Int) -> Void {
        if self.preempt_h != 0 {
            return;

@briefenable_preemptive

@param

selfScheduler instance
quantum_msPreemption check period (milliseconds)

@returnVoid

@noteRepeated calls are ignored when preempt_h is already enabled (preempt_h != 0).

functioncoroutine::Scheduler.disable_preemptive

Signaturefunc disable_preemptive(self: coroutine.Scheduler) -> Void

    func disable_preemptive(self: coroutine.Scheduler) -> Void {
        if self.running_h != 0 {
            _ = sync.atomic_i64_store(self.running_h, 0);

@briefdisable_preemptive

@param

selfScheduler instance

@returnVoid

functioncoroutine::Scheduler.spawn_coroutine

Signaturefunc spawn_coroutine(self: coroutine.Scheduler, fn: (Int) -> Int, arg: Int, stack_kb: Int) -> Int

    func spawn_coroutine(self: coroutine.Scheduler, fn: (Int) -> Int, arg: Int, stack_kb: Int) -> Int {
        let stack_bytes: Int = stack_kb * 1024;
        let co: Int = co_new(fn, arg, stack_bytes, self.main_ctx, self.preempt_h);

@briefspawn_coroutine

@param

selfScheduler instance
fnCoroutine entry function (signature: (Int)->Int)
argArgument passed to fn
stack_kbStack size (KB)

@returnCoroutine handle (Int)

functioncoroutine::Scheduler.resume

Signaturefunc resume(self: coroutine.Scheduler, co: Int) -> Void

    func resume(self: coroutine.Scheduler, co: Int) -> Void {
        let cur: Ptr = ptr(load64(ptr_add(ptr(co), 0)));
        _ = coctx_swap(self.main_ctx, cur);

@briefresume

@detailsSwitches to the coroutine context to continue execution.

@param

selfScheduler instance
coCoroutine handle (Int)

@returnVoid

functioncoroutine::Scheduler.run

Signaturefunc run(self: coroutine.Scheduler) -> Void

    func run(self: coroutine.Scheduler) -> Void {
        loop (; self.q.len() > 0; ) {
            let co: Int = self.q.pop();

@briefrun

@param

selfScheduler instance

@returnVoid

Variables

Class fields (var).

varcoroutine::CoQueue.in

Typecollections.Vector<Int>

@briefIn stack

@detailspush appends into this stack

    var in: collections.Vector<Int>;

    /*

varcoroutine::CoQueue.out

Typecollections.Vector<Int>

@briefOut stack

@detailspop pops from this stack.

    var out: collections.Vector<Int>;

    /*

varcoroutine::Scheduler.q

Typecoroutine.CoQueue

@briefRun queue

@detailsQueue of runnable coroutines

    var q: coroutine.CoQueue;
    /*
    @brief `all` field.

varcoroutine::Scheduler.all

Typecollections.Vector<Int>

@brief`all` field.

@detailsHolds the `all` value for each `Scheduler` instance. The field type is `collections.Vector<Int>`, and constructors and methods keep it synchronized with the object's runtime state.

    var all: collections.Vector<Int>;

    /*

varcoroutine::Scheduler.main_ctx

TypePtr

@briefScheduler main context

@detailsThe context used as the "return target" for coctx_swap

    var main_ctx: Ptr;

    /*

varcoroutine::Scheduler.preempt_h

TypeInt

@briefSoft-preempt flag handle

@details0 means disabled.

    var preempt_h: Int;

    /*

varcoroutine::Scheduler.running_h

TypeInt

@briefTimer thread running flag

@detailsAtomic handle.

    var running_h: Int;

    /*

varcoroutine::Scheduler.timer_thread

Typethread.JoinHandle

@briefTimer thread handle

@detailsThread handle created by EnablePreemptive.

    var timer_thread: thread.JoinHandle;
    /*
    @brief `timer_cfg` field.

varcoroutine::Scheduler.timer_cfg

TypeInt

@brief`timer_cfg` field.

@detailsHolds the `timer_cfg` value for each `Scheduler` instance. The field type is `Int`, and constructors and methods keep it synchronized with the object's runtime state.

    var timer_cfg: Int;

    /*