sigildocs

(sigil async)

(sigil async) - Cooperative Async Runtime

Provides a cooperative multitasking runtime with lightweight tasks, async I/O, and timer support. Tasks yield control explicitly via blocking operations (sleep, I/O waits, channel operations).

Basic Usage

(import (sigil async))

(with-async
  (go (begin
        (display "Task A\n")
        (sleep 0.1)
        (display "Task A done\n")))
  (go (begin
        (display "Task B\n")
        (sleep 0.05)
        (display "Task B done\n"))))

I/O Integration

(with-async
  (go (begin
        (await-readable sock)
        (display (socket-read sock)))))

Exports

schedulerprocedure

Scheduler record type.

The scheduler manages concurrent tasks with support for I/O and timer-based waiting.

scheduler?procedure

Test if a value is a scheduler struct.

scheduler-run-queueprocedure

Get the run-queue field of a scheduler struct.

scheduler-blocked-countprocedure

Get the blocked-count field of a scheduler struct.

scheduler-io-waitersprocedure

Get the io-waiters field of a scheduler struct.

scheduler-fd-waitersprocedure

Get the fd-waiters field of a scheduler struct.

scheduler-timer-waitersprocedure

Get the timer-waiters field of a scheduler struct.

set-scheduler-run-queue!procedure

Set the run-queue field of a scheduler struct.

set-scheduler-blocked-count!procedure

Set the blocked-count field of a scheduler struct.

set-scheduler-io-waiters!procedure

Set the io-waiters field of a scheduler struct.

set-scheduler-fd-waiters!procedure

Set the fd-waiters field of a scheduler struct.

set-scheduler-timer-waiters!procedure

Set the timer-waiters field of a scheduler struct.

make-schedulerprocedure

Create a new scheduler.

scheduler-spawnprocedure

Add a new task to the scheduler.

scheduler-runprocedure

Run all scheduler tasks until completion or deadlock.

with-asyncsyntax

Run async code in a scheduler context.

Creates a scheduler and runs the body until all tasks complete. Use go within the body to spawn concurrent tasks.

(with-async
  (go (task-1))
  (go (task-2)))
gosyntax

Spawn a concurrent task.

Must be called within with-async. The task runs concurrently with other tasks, yielding at blocking operations.

(with-async
  (go (display "hello\n")))
yieldprocedure

Yield control to the scheduler.

Allows other tasks to run before continuing.

sleepprocedure

Sleep for a specified number of seconds.

Yields to the scheduler, allowing other tasks to run. Other tasks continue during the sleep.

(with-async
  (go (begin
        (display "start\n")
        (sleep 1)
        (display "done\n"))))
await-readableprocedure

Wait until a socket is readable.

Yields to the scheduler until the socket has data available.

await-writableprocedure

Wait until a socket is writable.

Yields to the scheduler until the socket can accept data.

in-async-context?procedure

Check if currently running in an async context.

Returns #t if running inside with-async, #f otherwise. Useful for writing code that behaves differently in sync vs async contexts.

(if (in-async-context?)
    (display "running async\n")
    (display "running sync\n"))
when-asyncsyntax

Execute body only if in async context.

The body is only evaluated when running inside with-async.

(when-async
  (yield))
if-asyncsyntax

Choose between async and sync expressions.

Evaluates async-expr if in async context, sync-expr otherwise.

(if-async
  (await-readable port)  ; async: yield to scheduler
  (socket-select ...))   ; sync: block
await-readable-fdprocedure

Wait until a file descriptor is readable.

Yields to the scheduler until the fd has data available. Use for non-blocking reads from process pipes.

await-writable-fdprocedure

Wait until a file descriptor is writable.

Yields to the scheduler until the fd can accept data. Use for non-blocking writes to process pipes.

current-schedulerprocedure

Get the current async scheduler.

Returns the scheduler if running inside with-async, #f otherwise.

Re-exported from (sigil async scheduler)