node-synch

Synchronization Primitives in JavaScript

/* Main thread */
import { Sema, Lock } from 'node-synch';

const sema = new Sema();
const lock = new Lock();

const worker = new Worker(...);

worker.postMessage({ sema, lock });

// Do something with the locks



/* Worker thread */
import { Sema, Lock } from 'node-synch';
import { mainThread } from 'worker_threads';

...
mainThread.on('message', ({ sema, lock }) => {
  sema = Sema.from(sema);
  lock = Lock.from(lock);
  
  // Do something with the locks
});

Installation

npm install node-synch

Features

• Synchronization Primitives
  • Semaphores
  • Locks; not to be confused with Lock Web API
• Browser support
• Synchronous and Asynchronous methods

Table of Contents

• Class: Sema
  • Sema.from(sema)
  • new Sema(init)
  • sema.down()
  • sema.downSync()
  • sema.up()
  • sema.value()
  • sema.clone()
  • sema.toString()
• Class: Lock
  • Lock.from(lock, tid)
  • new Lock(tid)
  • lock.acquire()
  • lock.acquireSync()
  • lock.release()
  • lock.isLocked()
  • lock.holder()
  • lock.tid()
  • lock.clone()
  • lock.toString()

Class: Sema

The Sema class represents a single instance of a semaphore. A semaphore is a synchronization primitive that keeps an internal counter. On attempting to decrement past 0, the decrementing thread is put to sleep until this counter is incremented again. To use semaphores in both a worker thread and the main thread, this class must be imported in both locations.

Sema.from(sema)

• sema <Sema> A Sema object or a structuredClone Sema object to create a shared clone
• Returns: <Sema> A Sema object representing a shared copy of the semaphore.

/* Main Thread */
import { Sema } from 'node-synch';

const sema = new Sema();

const worker = new Worker(..., {
  workerData: { sema }
});

await sema.down();
...
sema.up();



/* Worker Thread */
import { Sema } from 'node-synch';
import { workerData } from 'worker_threads';

let { sema } = workerData;

sema = Sema.from(sema);

await sema.down();
...
sema.up();

new Sema(init)

• init <number> An optional non-negative Int-32 number representing the internal counter of the semaphore. This is used to determine the semaphore's value. Default: 1.

sema.down()

• Returns: <Promise> -> <boolean>

Attempts to decrease the semaphore's internal counter. This will sleep the thread if counter is at 0. Unlike sema.downSync(), this method is asynchronous and non-blocking. Returns Promise that resolves to true.

import { Sema } from 'node-synch';

const sema = new Sema();

await sema.down();

... // Critical section

sema.up();

sema.downSync()

• Returns: <boolean>

Attempts to decrease the semaphore's internal counter. This will sleep the thread if counter is at 0. Unlike sema.down(), this method is synchronous and blocking. Returns true.

import { Sema } from 'node-synch';

const sema = new Sema();

sema.downSync();

... // Critical section

sema.up();

sema.up()

• Returns: <boolean>

Increases the internal counter of the semaphore. Wakes up threads that are waiting on the semaphore. Returns true.

sema.value()

• Returns: <number>

Returns the current value of the semaphore.

sema.clone()

• Returns: <Sema>

Returns a shared copy of the semaphore.

sema.toString()

• Returns: <string>

Returns the string format for the semaphore.

Class: Lock

The Lock class represents a single instance of a lock. To use locks in both a worker thread and the main thread, this class must be imported in both locations. Unlike Lock Web API, this lock synchronization primitive stalls threads that attempt to hold it when it is held by another thread. Once unlocked, the waiting threads are woken up.

Lock.from(lock[, tid])

• lock <Lock> A Lock object or a structuredClone Lock object to create a shared clone
• tid <number> An optional non-negative Int-32 number representing the tid of the lock. This is used to determine the holder when the lock is acquired. If not specified, the lock keeps an internal counter which it uses to determine the tid of the shared cloned Lock. Default: Next internal lock number.
• Returns: <Lock> A Lock object representing a shared copy of the lock.

/* Main Thread */
import { Lock } from 'node-synch';

const lock = new Lock();

const worker = new Worker(..., {
  workerData: { lock }
});

await lock.acquire();
...
lock.release();



/* Worker Thread */
import { Lock } from 'node-synch';
import { workerData, threadId } from 'worker_threads';

let { lock } = workerData;

lock = Lock.from(lock, threadId);

await lock.acquire();
...
lock.release();

new Lock([tid])

• tid <number> An optional non-negative Int-32 number representing the tid of the lock. This is used to determine the holder when the lock is acquired. Default: 0.

lock.acquire()

• Returns: <Promise> -> <boolean>

Attempts to acquire the lock with the internal tid. This will sleep the thread if the lock is already held by a different tid. Unlike lock.acquireSync(), this method is asynchronous and non-blocking. Returns Promise that resolves to true if the lock is currently not held, false if the lock is already held by the current tid.

import { Lock } from 'node-synch';

const lock = new Lock();

await lock.acquire();

... // Critical section

lock.release();

lock.acquireSync()

• Returns: <boolean>

Attempts to acquire the lock with the internal tid. This will sleep the thread if the lock is already held by a different tid. Unlike lock.acquire(), this method is synchronous and blocking. Returns true if the lock is currently not held, false if the lock is already held by the current tid.

import { Lock } from 'node-synch';

const lock = new Lock();

lock.acquireSync();

... // Critical section

lock.release();

lock.release()'

• Returns: <boolean>

Attempts to release the lock. Threads that are currently waiting on this lock are woken up. Returns true if the lock is held by the current thread, false otherwise.

lock.isLocked()

• Returns: <boolean>

Returns true if the lock is held by a thread, false otherwise.

lock.holder()

• Returns: <number>

Returns the tid of the thread holding the lock, -1 otherwise.

lock.tid()

• Returns: <number>

Returns the internal tid of the lock clone/instance.

lock.clone()

• Returns: <Lock>

Returns a shared copy of the lock.

lock.toString()

• Returns: <string>

Returns the string format for the lock.