Threads
thread.spawn(f, args...) runs a function on a new thread, and thread.join(h) waits for it to finish and receives its return value. thread.spawnEach(f, own items, args...) starts one thread per array element (the k-th runs f(items[k], args...); elements are moved), and thread.join then returns an array of return values in the same order as items. thread.cpus() is the number of logical CPUs, and thread.yield() gives the CPU to other runnable threads (for loops that wait while watching a flag in a RacyBuffer; it returns immediately if no other thread can run; it does nothing on wasm32).
function search(w: own Worker, sh: Shared, root: Position): Worker { ... }
const sh: Shared = { tt: new RacyBuffer<u64>(n), stop: new RacyBuffer<u32>(1) };{ const g = thread.spawnEach(search, own workers, sh, root); // helper threads ... // the main thread does its own work (I/O, time management) sh.stop.store(0, 1); workers = thread.join(g); // each Worker comes back}- A handle (the result of
thread.spawn) can only be written as the initialiser of aconstdeclaration. It cannot be moved, assigned,returned, passed as an argument, or stored in a field or array element (the typesThread<R>/Threads<R>can only be written in thatconst’s annotation).thread.joinconsumes the handle, and a handle that was not joined is joined automatically at the end of the block containing its declaration (including when leaving withreturn/break/continue; the return value is discarded). - Passing values to a thread: types that are copied are copied,
ownmoves (the thread owns the value and returns or frees it), and unqualified values with heap data are shared as read-only borrows. Functions withmutarguments cannot be started. A variable lent as a read-only borrow cannot be modified, moved or passed asmutfrom theconstdeclaration to the end of the block (even afterjoin). To modify it after joining, put the start in an inner block{ ... }. Temporary values cannot be lent (put them in aconstfirst). - Only the elements of a
RacyBuffercan be modified by multiple threads. Outside kernels,RacyBufferelements can be written even through a read-only borrow (the length and memory do not change). Element reads and writesb[i]are atomic instructions with no ordering guarantee (relaxed outside kernels); the values may differ between runs, but memory is not corrupted.for...ofandclone()also read elements atomically one at a time. Element types arei8/u8/i16/u16/i32/u32/f32, plusi64/u64outside kernels only (for transposition tables and the like). With 8- and 16-bit elements too, neighbouring elements written at the same time by other threads do not get mixed. A kernel can read and write any element of amut RacyBuffer. - Atomic operations:
b.load(i),b.store(i, v),b.fetchAdd(i, v)(returns the previous value),b.compareExchange(i, expected, desired)(returns the previous value). The ordering is seq_cst: writes before astore(includingb[i]) are visible to a thread that sees that value withload. Use these for “write the data, then raise a flag” hand-offs (b[i]accesses have no ordering among themselves).fetchAdd/compareExchangeare for integers only and cannot be used inside kernels. - A read-only-borrowed
RacyBuffercan be passed as it is to a kernel’smut RacyBuffer(gpu.submit(k, n, mut sh.out, sh.inp), because a kernel cannot replace the memory).dispatch/gpu.submit/gpu.ready/gpu.waitcan be called from any thread, and a ticket can be waited on from any thread. - The output of one
printcall (one line) is not mixed with other threads.readLine()/inputReady()can only be used on the main thread (calling them elsewhere stops the program). A stop on any thread stops the whole program (with one message). - Up to 256 threads can exist at once (more stops the program). The stack is 64 MiB (change it with
UM_THREAD_STACK_MB). Starting and joining costs 10–15 microseconds per thread (Apple M4). - The thread pool that runs kernels in parallel on the CPU uses as many threads as logical CPUs by default (including the calling thread; at most 64). Change the number with
UM_THREADS. Pool threads wait for the next job without sleeping for 100 microseconds after a job (change withUM_POOL_SPIN_US; 0 sleeps immediately). The pool takes one job at a time, so acpu.dispatchmade while another thread is using it runs only on the calling thread. - wasm32 has no threads. Every form is accepted, and the function runs to completion on the spot at the join point (
thread.joinor the automatic join) (spawnEachin element order;thread.cpus()is 1). Programs that loop waiting for the results of other threads (such as one that collects work and sends it to the GPU) never finish on wasm32.
Examples: examples/threads.um, examples/racy_shared.um, examples/racy_buffer.um.