The Divine Synchronization Library

Introduction

Many JavaScript or TypeScript developers don't think much about synchronization, even if they should. While it's true that JavaScript in Node.js or on the web is single-threaded, anytime an asynchronous function call is invoked, something else might be executed before control is handed back to your callback.

This library contains a classical set of high-quality synchronization primitives that can be used to protect critical sections in such code.

It's written in TypeScript (which means it provides excellent IDE/editor support out of the box) and down-compiled to ES5, so it works equally well in Node.js or in any web browser (a Promise polyfill might be required, though).

About fairness

Most synchronization primitives in this library has a "fair" counterpart, that requires the waiter to provide an ID token. The waiters are then woken up not in FIFO order but in such a way that each ID is processed before a waiter with a duplicate ID.

Provided primitives

This section lists the synchronization primitives provided by this library.

DDRQueue

Although not really a classical primitive, it's a fair queue based on the paper Efficient Fair Queuing Using Deficit Round-Robin. It's more or less just a TypeScript rewrite of Matt Lavin's drr-fair-queue.

This queue is the foundation of all the "fair" variants of the synchronization primitives.

Queue and FairQueue

A blocking queue (strict FIFO, or fair).

Condition and FairCondition

A condition variable implementation with notify(), notifyAll and wait() methods.

Signal and FairSignal

A trivial extension to the condition variable that allows a value to be passed to the waiter.

NOTE: Don't mistake this for a Pub/Sub primitive! While possible, it's very difficult to use these two primitives as event emitters without losing messages. See below instead.

PubSub and FairPubSub

A Pub/Sub primitive, with configurable capacity, blocking publishing and generator-based subscription, suitable to be used in a for await-loop.

Semaphore and FairSemaphore

A classical semaphore that can be signaled and waited for. There is also a non-blocking take() method available.

Mutex and FairMutex

Just a semaphore initialized to 1 and with more appropriate method names.

Barrier, Lightswitch and ReadWriteLock

A few extra primitives taken more or less verbatim from the The Little Book of Semaphores by Allen B. Downey. There are no fair variants of these.