Skip to content

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.

JavaScript
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, let and functions of your script. Their values at the moment of spawn are 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 call spawn (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: spawn refuses 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 and Error, 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, a RegExp, a symbol, a BigInt, an import, a tool, fetch, SharedArrayBuffer and Atomics are refused when you call spawn, 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, TextDecoder and console, and can read your files: import fs from "fs" gives it readFileSync, existsSync, readdirSync and statSync (not aliased; any other call of fs is a TypeError). 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

PlanThreads
Freenone
Pro4
Scale8
Platform8

This page as Markdown: /docs/threads.md