🚦js-semaphore - Syncronization Using Promises

🚦js-semaphore is a simple Semaphore implementation using Promises for JavaScript aplications.

If you ever find a need for a syncronization mechanism usage into your application, you can use a Semaphore. If you want to use a Semaphore and you develop in JavaScript, you can use js-semaphore!

If your need is simple and a small mechanism with just 1 shared resource, you can use js-semaphore as a Mutex too!

The source code comprehends the full Semaphore implementation with some basics tests and some applications. Actually, we have:

• 🤔🍜 Philosophers Dinner

Common questions

• Why the tests take so long to complete?

As this is a Semaphore implementation, the tests are based in time and waiting for a specific resource to continue the execution. We emulate this as a test in order to validate the correct behavior of the lib.

• Why implement a Semaphore? Using Promises?

As a common solver for deadlocks avoidance, we found an util lib to create and test! The Promises usage is just a matter of asynchronous need.

Installation

js-semaphore is available with npm/yarn:

$ npm install @codevor/js-semaphore --save
$ yarn add @codevor/js-semaphore

Usage

With ES6/import

import { Semaphore } from '@codevor/js-semaphore';

// Semaphore with 1 resource = Mutex
const semaphore = Semaphore();

// Semaphore with 1 resource, starting at 0 value
const semaphore = Semaphore({ resource: 1, start: 0 });

// Semaphore with 3 resources
const semaphore = Semaphore({ resource: 3 });

// acquire the semaphore
semaphore.acquire().then(() => {
  // Your code goes here
  const x = 2 + 3;

  // remember to release the semaphore at the end of your usage
  semaphore.release();
});

With require

const Semaphore = require('@codevor/js-semaphore').Semaphore;

// Semaphore with 1 resource = Mutex
const semaphore = Semaphore();

// Semaphore with 1 resource, starting at 0 value
const semaphore = Semaphore({ resource: 1, start: 0 });

// Semaphore with 3 resources
const semaphore = Semaphore({ resource: 3 });

// acquire the semaphore
semaphore.acquire().then(() => {
  // Your code goes here
  const x = 2 + 3;

  // remember to release the semaphore at the end of your usage
  semaphore.release();
});

Control timeout

If you want, you can control the timeout. We hardly suggest not let this below 0.2s, but you can try if you want.

import { Semaphore, setTimespan, timespan } from '@codevor/js-semaphore';

// creates the Semaphore
const semaphore = Semaphore();

// get the actual Timespan
const actualTimespan = timespan();

// set the actual Timespan, in seconds
setTimespan(actualTimespan / 2);

// acquire the semaphore
semaphore.acquire().then(() => {
  // Your code goes here
  const x = 2 + 3;

  // remember to release the semaphore at the end of your usage
  semaphore.release();
});

Contributing

Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us.

Changelog

This project adheres to Semantic Versioning. Every release, along with the migration instructions, is documented on the Github Releases page.

Bugs and Sugestions

Report bugs or do suggestions using the issues.

License

MIT License © Codevor