qipp-services-semaphore

General

This service is used in order to deal with race conditions. It provides methods to create named and uuid-based semaphores for manageing resources availability or state.

Installation

npm i qipp-services-semaphore

Angular usage

In the config phase of your application

You can set the default timeout for the service, which will be used by the kill() and waitForUnlock() methods:

semaphoreProvider.defaults.timeout = 60 // in seconds.

Named semaphores

There two different categories of available semaphores, the named ones, which could be created in the scaffold phase of your application, and the generic ones, created later on demand.

Use the init() method in order to create a hash map of unique named semaphores on top of the underlaying pool of uuids:

semaphore.init('myNamedSemaphore')
console.log(semaphore.namesPool)
// Object {myNamedSemaphore: "39b357ec-7931-433a-9a19-85128f964197"}
console.log(semaphore.uuidsPool)
// Object {39b357ec-7931-433a-9a19-85128f964197: [false]}

You can also create multiple semaphores as arguments:

semaphore.init('semaphoreA', 'semaphoreB', 'semaphoreC')

Note that the boolean value is the lock state of the semaphore.

Generic semaphores

Use the create() method to create a generic semaphore:

semaphore.create() // returns the uuid.

Killing semaphores

The kill() method is a promise with .success and .error callbacks. Be aware that this method could be called externally, unlike the unlock(), which means that you don't need to know the secret. This method wait for the semaphore to be unclocked:

semaphore
    .kill('39b357ec-7931-433a-9a19-85128f964197')
    // Semaphore was unlocked, then killed.
    .success(function () {
        // Do something.
    })
    // Semaphore was locked, then not killed.
    .error(function () {
        // Do something else.
    })

Note that the default timeout is used if the semaphore is locked.

Locking semaphores

The lock() method is a promise with .success and .error callbacks. It locks a given semaphore if previously unlocked, then returns a new uuid as secret that must be provided later to the unlock() method:

semaphore
    .lock('39b357ec-7931-433a-9a19-85128f964197')
    .success(function (secret) {
        console.log(secret) // 2290890c-1733-46ec-b392-52bef39f1fa8
    })
    .error(function () {
        // Do something else.
    })

Unlocking semaphores

The unlock() method is a promise with .success and .error callbacks. It must be called with the id of the semaphore and the corresponding secret:

semaphore
    .unlock(
        '39b357ec-7931-433a-9a19-85128f964197', // semaphore
        '2290890c-1733-46ec-b392-52bef39f1fa8'  // uuid
    )
    // Semaphore is now unlocked.
    .success(function () {
        // Do something.
    })
    // Semaphore is still locked.
    .error(function () {
        // Do something else.
    })

Waiting for a semaphore to be unlocked

The waitForUnlock() method is a promise with .success and .error callbacks. This method could be called after an unlock error in order to wait for a given semaphore to be freed:

semaphore
    .waitForUnlock('39b357ec-7931-433a-9a19-85128f964197')
    .success(function () {
        // Do something.
    })
    .error(function () {
        // Do something else.
    })

Note that the default timeout is also used here.

Tools

Linting with StandardJS

Please refer to the JavaScript Standard Style for general rules.

npm run lint

Unit testing with Karma

npm test

Requirements

Angular

• angular 1.4.3

Qipp modules

• qipp-services-uuid 0.1.0

Licence

Released under the MIT license by qipp.