Cross-platform scheduler, context, timer, IPv4, and TCP helpers. The selected backend is linux/sync, macos/sync, or windows/sync.

Scheduling and timing

spawn

(callable out -- context) Creates, schedules, and returns one Context for callable with output schema out.
  • The callable is invoked with no stack inputs. For () as out, it must return no objects; otherwise it must return one object matching the requested output schema.
  • A wrong-schema single output reports context return schema mismatch.
  • Block callables run through a call boundary.
  • A mutable callable view is moved into the new context. An immutable callable view is borrowed; keep the callable and anything it borrows alive until execution finishes.
  • The callable body begins when scheduled, not before spawn returns.

Known issue: Linux: direct Text outputs currently lose their contents when retrieved from the Context, despite matching the requested schema; return an owned String instead, for example ["hello" toString] String spawn.

yield

(--) Allows another ready context to run and later resumes the current context.
  • Linux: a positive timed wait installs a cancellation callback, but yield does not. Canceling a context suspended by yield, including a sleep that takes the zero-duration yield path, can terminate with invalid cancelation function. Do not treat yield as a safely cancellable timed wait.
  • macOS: yield enqueues and dispatches without installing a cancellation callback; its default callback reports invalid cancelation function.
  • Windows: yield enqueues and dispatches without installing a cancellation callback; its default callback reports invalid cancelation function.

canceled?

(-- canceled) Reports whether the current context has been canceled.

sleepFor

(duration --) Waits for the requested duration unless canceled; cancellation can resume the current context early.
  • Linux: duration is seconds in Real64. Fractional durations passed to sleepFor or sleepUntil are truncated to whole nanoseconds; a duration that truncates to zero yields without a timer. The scheduler can resume later than the requested time.
  • A zero duration yields without installing a timer.
  • An already-canceled context skips a supported nonnegative sleep. Duration validation precedes this check; cancellation does not make a negative duration valid.
  • The duration must be nonnegative. Checked violations report negative sleep duration; a known violation can fail compilation. Run-time assertions require DEBUG.
  • Linux: Disabling assertions does not make a negative duration supported and can instead cause a fatal native-timer failure.
  • macOS: The input is cast to Real64 before validation. Below one second it truncates to nanoseconds; at least one second uses truncated microseconds. The duration assertion precedes the cancellation-sensitive wait path.
  • Windows: The duration assertion precedes the cancellation-sensitive wait path; do not infer the macOS input conversions for this backend.

Known issue: Linux: canceling a context suspended in a zero-duration sleepFor (or a duration that truncates to zero nanoseconds) terminates the process with invalid cancelation function, exit 2; positive timed waits cancel correctly.

sleepUntil

(time --) Waits until the requested scheduler time unless canceled.
  • Linux: time uses the elapsed-time scale in Real64 seconds returned by getTime, not a calendar or Unix timestamp. A past deadline takes the zero-duration path.
  • Linux: fractional durations passed to sleepUntil are truncated to whole nanoseconds; a duration that truncates to zero yields without a timer. The scheduler can resume later than the requested time.
  • An already-canceled context returns without waiting.
  • macOS: Past times take the zero-duration path, and the wait uses one-shot kevent timer behavior.
  • Windows: The earliest pending timer supplies the timer timeout; ready contexts and I/O completions can resume first. A timer deadline does not guarantee immediate execution or global resumption order.

getTime

(-- time) Returns elapsed Real64 seconds since the sync subsystem initialized.
  • Linux: Uses CLOCK_BOOTTIME.
  • macOS: Uses CLOCK_MONOTONIC.
  • Windows: Derives elapsed Real64 seconds from QueryPerformanceCounter and QueryPerformanceFrequency.

Fiber stack setting

SL_FIBER_STACK_SIZE is an optional build definition; for example, -D SL_FIBER_STACK_SIZE=131072. It is not defined as a public sync getter. The default usable/requested stack size is 65536 bytes.

The context model is cooperative: a running context continues until it calls yield, waits, sleeps, performs a blocking wrapper operation, or finishes. A waiting context resumes when its wait completes or is canceled; readiness does not guarantee immediate execution or global resumption order.

Network helpers

ipv4ToString

(address -- addressString) Converts a host-order IPv4 Nat32 to dotted-decimal String.
  • address is a host-order Nat32 with the first dotted octet in the most significant byte. Use 0x7F000001n32 for 127.0.0.1.
  • No hostname resolution is performed. The result is a separate owned String, not borrowed formatting storage.

connectTcp

(address port -- connection result) Creates a TCP connection to the host-order IPv4 address and port.
  • address is a host-order Nat32; port is a host-order Nat16. No hostname resolution is performed.
  • Success returns a live TcpConnection and an empty owned String. Failure returns an invalid connection and a nonempty owned error String.
  • The connection wrapper is owned, movable, and noncopyable.
  • Cancellation before a successful result returns the error String "canceled".
  • Immediate native success is accepted, but it does not guarantee that connectTcp returns without yielding; the backend can still wait for completion notification.

listenTcp

(address port -- acceptor result) Creates a TCP listener for the host-order IPv4 address and port.
  • address is a host-order Nat32; port is a host-order Nat16. No hostname resolution is performed.
  • Success returns a live TcpAcceptor and an empty owned String. Failure returns an invalid acceptor and a nonempty owned error String.
  • The acceptor wrapper is owned, movable, and noncopyable.
  • Cancellation before a successful result returns the error String "canceled".
  • Linux: EPOLLERR and EPOLLHUP wake a parked accept or I/O wait so the operation reports its result; one-shot registrations do not repeatedly dispatch an idle error or hangup.
  • Windows: Listeners set SO_EXCLUSIVEADDRUSE and use a backlog of 128.

macOS backend

Result and ownership model

Failure behavior

Linux: ordinary TCP setup failures return a nonempty String such as bind failed, result=<errno> or connect failed, result=<errno>. The suffix is a numeric native error value. Cancellation returns canceled.

Timer, scheduler, clock, and fiber-creation failures can instead print a fatal diagnostic and terminate; these operations return no error record. The Linux diagnostics are listed below; only the FATAL prefixes are followed by a native error number.

OperationLinux diagnostic prefix
getTimeFATAL: clock_gettime failed, result=
sleep timer creationFATAL: timerfd_create failed, result=
FATAL: epoll_ctl failed, result=
timer programming / wait registrationFATAL: timerfd_settime failed, result=
FATAL: epoll_ctl failed, result=
scheduling / switchingFATAL: swapcontext failed, result=
FATAL: epoll_wait failed, result=
fiber allocationinvalid fiber stack size
FATAL: getcontext failed, result=
FATAL: mmap failed, result=
FATAL: mprotect failed, result=

Preconditions can also report invalid cancelation function or invalid fiber stack size.

Examples

IPv4 formatting and spawn

"String"    use
"control"   use
"sync/sync" use

{} Int32 {} [
  0xC0A86465n32 ipv4ToString print
  LF print
  context: [("done" LF) printList] () spawn;
  @context.wait
  0
] "main" exportFunction

Expected Output

192.168.100.101
done

See also