Narcoleptic Pasta Manufacturer
    Have ideas to improve npm?Join in the discussion! »

    simple-mutex-promise
    TypeScript icon, indicating that this package has built-in type declarations

    1.1.0 • Public • Published

    simple-mutex-promise

    Commitizen friendly Build Status

    This library provides a very simple mutex/lock implementation in JavaScript.

    Usage

    The problem

    You have an operation / a function that does the following:

    1. A value from outside of the operation is read.
    2. An asynchronous action takes place which leads to giving the execution context to another part of the code.
    3. That other part of the code (can also be another invocation of the same function) does also use the value from outside. Also potentially modifying it.
    4. The first (invocation of the) operation continues and writes a changed value to the same place (variable) that was read from initially.

    This kind of code can lead to race conditions where a stale value is read, modified and written back while other parts of the code have already changed it by themselves. One very simple example is shown as unit test case: .

    The solution

    Before the value in question is read and potentially modified a lock or mutex (mutual exclusion) has to be aquired which blocks (or queues) other parts of the code from accessing the same value. Once the operation is done the lock is released and if other code already tried to access the variable they are informed that execution can continue.

    Usage with this library

    Install it with npm

    npm install simple-mutex-promise

    or with yarn

    yarn add simple-mutex-promise

    In your code import it and create the mutex instance outside of the critical function:

    import { getMutex } from 'simple-mutex-promise'
    
    const mutex = getMutex()

    It is important that all parts of the code that access the value in question use the same instance returned from getMutex().

    Then acquire the lock inside the critical function before any and release it after every usage of the variable is done:

    let i = 1
    
    async function criticalAsyncFunction() {
      const [lock, release] = mutex.getLock()
      await lock                               // 1
    
      const temp = i
    
      await someAsyncAction()                  // 2
      i = temp + 1
    
      release()                                // 3
    }

    Before the outside value is used we await the lock (1). So function execution is paused and only continued when the lock resolves. Then we can read the value and use it (2). In this case we don't use the value in the async action but typically that would be the case. After writing to the outside variable is done we release the lock and now other execution contexts can make use of the value (3). We made sure that other code is only run when all our updates are done.

    Types

    simple-mutex-promise is written in TypeScript and type declarations are also part of the build. You don't need to install them separately.

    Install

    npm i simple-mutex-promise

    DownloadsWeekly Downloads

    1

    Version

    1.1.0

    License

    MIT

    Unpacked Size

    9.23 kB

    Total Files

    16

    Last publish

    Collaborators

    • avatar