Repository files navigation

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 forNode.js,Deno and thebrowser. It can also be used with any framework or library such asReact,Vue orSvelte.

Depending on the environment, it usesWorker Threads orWeb Workers. In addition toES6 generators to make multithreading as simple as possible.

JavaScript's single-threaded nature means that tasks are executed one after the other, leading to potential performance bottlenecks and underutilized CPU resources. WhileWeb Workers andWorker 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.

npm install multithreading

import{threaded}from"multithreading";constadd=threaded(function*(a,b){returna+b;});console.log(awaitadd(5,10));// 15

Theadd 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.

import{threaded,$claim,$unclaim}from"multithreading";constuser={name:"john",balance:0,};constadd=threaded(asyncfunction*(amount){yielduser;// Add user to dependenciesawait$claim(user);// Wait for write lockuser.balance+=amount;$unclaim(user);// Release write lock});awaitPromise.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.

Theyield statement is used to specify external dependencies, and must be defined at the top of the function.

import{threaded,$claim,$unclaim}from"multithreading";// Some external functionfunctionadd(a,b){returna+b;}constuser={name:"john",balance:0,};constaddBalance=threaded(asyncfunction*(amount){yielduser;yieldadd;// Add external function to dependenciesawait$claim(user);user.balance=add(user.balance,amount);$unclaim(user);});awaitPromise.all([addBalance(5),addBalance(10),]);console.log(user.balance);// 15

In this example, theadd function is used within the multithreadedaddBalance function. Theyield 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 likeadd cannot have external dependencies themselves. All variables and functions used by an external function must be declared within the function itself.

When using external modules, you can dynamically import them by usingyield "some-package". This is useful when you want to use other packages within a threaded function.

import{threaded}from"multithreading";constgetId=threaded(function*(){/**   *@type {import("uuid")}   */const{ v4}=yield"uuid";// Import other packagereturnv4();}console.log(awaitgetId());// 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)

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.