multithreading v0.2.1
multithreading
Multithreading is a tiny runtime that allows you to execute JavaScript functions on separate threads. It is designed to be as simple and fast as possible, and to be used in a similar way to regular functions.
With a minified size of only 4.5kb, it has first class support for Node.js, Deno and the browser. It can also be used with any framework or library such as React, Vue or Svelte.
Depending on the environment, it uses Worker Threads or Web Workers. In addition to ES6 generators to make multithreading as simple as possible.
The State of Multithreading in JavaScript
JavaScript's single-threaded nature means that tasks are executed one after the other, leading to potential performance bottlenecks and underutilized CPU resources. While Web Workers and Worker Threads offer a way to offload tasks to separate threads, managing the state and communication between these threads is often complex and error-prone.
This project aims to solve these challenges by providing an intuitive Web Worker abstraction that mirrors the behavior of regular JavaScript functions. This way it feels like you're executing a regular function, but in reality, it's running in parallel on a separate threads.
Installation
npm install multithreading
Usage
Basic example
import { threaded } from "multithreading";
const add = threaded(function* (a, b) {
return a + b;
});
console.log(await add(5, 10)); // 15
The add
function is executed on a separate thread, and the result is returned to the main thread when the function is done executing. Consecutive invocations will be automatically executed in parallel on separate threads.
Example with shared state
import { threaded, $claim, $unclaim } from "multithreading";
const user = {
name: "john",
balance: 0,
};
const add = threaded(async function* (amount) {
yield user; // Add user to dependencies
await $claim(user); // Wait for write lock
user.balance += amount;
$unclaim(user); // Release write lock
});
await Promise.all([
add(5),
add(10),
]);
console.log(user.balance); // 15
This example shows how to use a shared state across multiple threads. It introduces the concepts of claiming and unclaiming write access using $claim
and $unclaim
. This is to ensure that only one thread can write to a shared state at a time.
Always
$unclaim()
a shared state after use, otherwise the write lock will never be released and other threads that want to write to this state will be blocked indefinitely.
The yield
statement is used to specify external dependencies, and must be defined at the top of the function.
Example with external functions
import { threaded, $claim, $unclaim } from "multithreading";
// Some external function
function add (a, b) {
return a + b;
}
const user = {
name: "john",
balance: 0,
};
const addBalance = threaded(async function* (amount) {
yield user;
yield add; // Add external function to dependencies
await $claim(user);
user.balance = add(user.balance, amount);
$unclaim(user);
});
await Promise.all([
addBalance(5),
addBalance(10),
]);
console.log(user.balance); // 15
In this example, the add
function is used within the multithreaded addBalance
function. The yield
statement is used to declare external dependencies. You can think of it as a way to import external data, functions or even packages.
As with previous examples, the shared state is managed using $claim
and $unclaim
to guarantee proper synchronization and prevent data conflicts.
External functions like
add
cannot have external dependencies themselves. All variables and functions used by an external function must be declared within the function itself.
Using imports from external packages
When using external modules, you can dynamically import them by using yield "some-package"
. This is useful when you want to use other packages within a threaded function.
import { threaded } from "multithreading";
const getId = threaded(async function* () {
const { v4 } = yield "uuid"; // Import other package
return v4();
}
console.log(await getId()); // 1a107623-3052-4f61-aca9-9d9388fb2d81
You can also import external modules in a variety of other ways:
const { v4 } = yield "npm:uuid"; // Using npm specifier (available in Deno)
const { v4 } = yield "https://esm.sh/uuid"; // From CDN url (available in browser and Deno)
Enhanced Error Handling
Errors inside threads are automatically injected with a pretty stack trace. This makes it easier to identify which line of your function caused the error, and in which thread the error occured.
12 months ago
12 months ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
10 years ago
10 years ago