Threads: run functions side by side
shotcup:threads runs a function on another thread of the run's sandbox and gives you a promise of its result, the way you would start a task in C# or Java, written the way you write JavaScript. It is for Pro and higher, it is experimental (its shape can change), and it needs no engine switch.
import { spawn, parallelMap } from "shotcup:threads";
const heavy = (n) => { let s = 0; for (let i = 0; i < n; i++) s += i % 7; return s; };
const sums = await Promise.all([100000, 200000, 300000].map((n) => spawn(heavy, n)));
const squares = await parallelMap([1, 2, 3, 4, 5, 6], (x) => x * x, { concurrency: 3 });spawn(fn, ...args) runs fn(...args) on a thread and returns a Promise of its result. parallelMap(items, fn, { concurrency }?) runs fn(item, index) for every item, at most concurrency at a time (never more than your plan's threads), and resolves with the results in order. concurrency is a whole number from 1 up or Infinity, and leaving it out (or undefined) uses all your plan's threads; 0, a negative number, NaN or a fraction is a RangeError, and another value that is not a number is a TypeError. There are no thread objects and nothing to load or close.
Copies, not sharing
A thread does not share memory with your script. The function travels as its source text and is compiled again on the thread; its arguments and everything it uses from outside are copied when you call spawn, and its result is copied back.
- A function can use the variables of the functions around it, and the top-level
const,letand functions of your script. Their values at the moment ofspawnare copied in, and nothing it changes on the thread comes back. A function that assigns to one of them, or holds a function that does, is refused when you callspawn(the function assigns to 'count', a variable from outside it): work on a local variable and return the value. - A function it calls goes along as source with what it uses, to 8 helpers deep. A function that calls itself, or two that call each other, work. A method, getter, setter or class member, a generator, a built-in function, or a function passed as an argument does not travel:
spawnrefuses it, naming what it is. Pass an arrow function instead. - Plain data travels: numbers, strings, booleans,
null,undefined, arrays, plain objects,Map,Set,ArrayBuffer, typed arrays andError, with cycles and shared references kept inside one value. A typed array arrives as its own buffer holding its elements. - A class instance, a
Date, aRegExp, a symbol, a BigInt, an import, a tool,fetch,SharedArrayBufferandAtomicsare refused when you callspawn, with an error that names what it was (captured value 'p' cannot be copied to another thread: p is an instance of the class 'Point'). Pass the data instead: its fields as an object, a date as a number. - A thread can use the language's built-ins,
TextEncoder,TextDecoderandconsole, and can read your files:import fs from "fs"gives itreadFileSync,existsSync,readdirSyncandstatSync(not aliased; any other call offsis aTypeError). Other imports are refused.
An error a function throws rejects its promise as a copy with its class, message and stack (read an error's code inside the function). A function that returns a promise has it awaited on the thread. A result or a thrown value that cannot be copied back rejects the promise with a TypeError, as an argument that cannot be copied does at spawn.
Order
Results are delivered in the order you called spawn, whatever order the threads finish in: a promise settles only after the ones before it, and each task's console output is written to your run's output when its result is delivered. The output of a run is the same every time, a deterministic run's included. A task that is cancelled (because the run ended at a limit, or an earlier item of the same parallelMap failed) writes nothing.
Limits are the run's
The threads of a run share its limits. The instruction cap counts every thread's instructions together; the timeout and a cancel stop every thread; the heap is one budget for your script and its threads: while tasks run it is divided into equal parts, one for your script and one for each of the run's threads (the copies a task holds count against the heap too). A function that needs more than its part gets the same RangeError (Allocation failed: GC heap size exceeds the configured memory limit) your script gets at the heap limit: the function can catch it, and otherwise it rejects the task's promise, which your script can catch too. When nothing catches it, the run ends with resource-limit. A copy that does not fit, or a file larger than a task's part, ends the run with resource-limit at once. A fault in native code on any thread ends the run as a host-error. Tasks you do not await still finish before the run ends.
On today's machines each run has one CPU, so threads run side by side without running faster: they give you the API and its ordering, not a speed-up, until runs can be placed on larger machines. Starting a task costs a few milliseconds, so a task should be work, not a one-line function.
Threads per plan
| Plan | Threads |
|---|---|
| Free | none |
| Pro | 4 |
| Scale | 8 |
| Platform | 8 |
This page as Markdown: /docs/threads.md