Naturally Pacifist Marsupials

    qipp-services-semaphore

    1.0.2 • Public • Published

    qipp-services-semaphore Build Status npm version

    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

    Qipp modules

    Licence

    Released under the MIT license by qipp.

    Install

    npm i qipp-services-semaphore

    DownloadsWeekly Downloads

    3

    Version

    1.0.2

    License

    MIT

    Last publish

    Collaborators

    • qipp