Module thread

OS thread handle — Rust's JoinHandle. Each spawned thread gets its own Io event loop. join waits for it, once; dropping a handle that was never joined DETACHES the thread (it keeps running and the OS reclaims it when it finishes).

A move-only value (its state is a Box): there is one handle per thread, so detach-on-drop runs exactly once (issues/fixed/thread-join-was-re-callable-and-handles-leaked.md), and a copy is E0901. Lend it with &t; join takes self : &Self and marks the handle joined inside the box, so a Thread is never Sync. To join from elsewhere, move the handle there.

A pool of worker threads that tasks are handed to.

Each task is pinned to one worker thread (round-robin, no work stealing), and every worker thread has its own GC heap and async Io event loop.

The OS worker threads live in one process-global pool owned by the runtime, which starts it on the first spawn and tears it down at process exit. A ThreadPool value is the explicit handle on that pool: it decides the thread count, submits tasks, and drains them. Two consequences:

• the num_threads passed to new is a request — it only takes effect while the runtime pool has not started yet, so the first ThreadPool created (before any task is spawned) fixes the count for the process;
• the worker threads are shared by every ThreadPool value, but each pool counts ITS OWN tasks: join_all and shutdown wait for the work submitted through that pool (and for the tasks that work submits into it), not for another pool's.

Uses atomic reference counting, so a pool may be shared across threads.

Example

{ ThreadPool, spawn } :: import("std/thread");

pool := ThreadPool.new(usize(4));
spawn(pool, io => {
  // ... do work ...
});
pool.join_all(); // wait for everything submitted so far
pool.shutdown(); // refuse new work, then drain

Get the number of hardware threads (CPU cores) available.

Get the current OS thread ID.

The CPU core the calling thread is currently running on, or -1 when the platform cannot say. Linux (sched_getcpu) and Windows (GetCurrentProcessorNumber) report it; macOS has no public per-thread CPU query and always returns -1, as does WASM. Advisory only — the scheduler may migrate the thread right after the call.

sink(cb) : Impl(FnOnce(...), Send): the task closure is MOVED in and run exactly once (plans/VALUES_BY_DEFAULT.md decision 37), so it may move its captures out; an Fn closure is accepted too. (A plain cb borrowed a literal capturing a not-implicitly-copyable value, and a borrow capture is never Send, decision 38 E: issues/fixed/a-move-only-value-cannot-be-moved-into-thread-spawn.md.)

Exported since 2026-09-13. It was written and working long before that but held back on a compiler defect: the closure-param form of fn(generic(T), … Impl(Fn() -> T) …) -> Impl(Future(T)) had no per-call identity for T, so it compiled at ONE T per program and silently miscompiled the second (issues/fixed/a-generic-function-returning-impl-future-t-miscompiles-at-a-second-t.md). tests/spawn_blocking.test.yo uses two different Ts for that reason.