---
title: "Threads: run functions side by side"
description: "shotcup:threads runs functions on other threads of the run's sandbox for Pro and higher: spawn and parallelMap, what is copied and what is refused, results and output in order, the run's limits across threads and the per-plan thread counts."
canonical: "https://shotcup.dev/docs/threads"
last_updated: "2026-10-18"
---
# 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.

```js
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

| Plan | Threads |
| --- | --- |
| Free | none |
| Pro | 4 |
| Scale | 8 |
| Platform | 8 |
