redis-semaphore

redis-semaphore

Mutex and Semaphore implementations based on Redis ready for distributed systems

Features

• Fail-safe (all actions performed by LUA scripts (atomic))

Usage

Installation

npm install --save redis-semaphore ioredis
# or
yarn add redis-semaphore ioredis

Mutex

See RedisLabs: Locks with timeouts

new Mutex(redisClient, key [, { lockTimeout = 10000, acquireTimeout = 10000, retryInterval = 10, refreshInterval = lockTimeout * 0.8 }])

• redisClient - required, configured redis client
• key - required, key for locking resource (final key in redis: mutex:<key>)
• timeouts optional
  • lockTimeout - ms, time after mutex will be auto released (expired)
  • acquireTimeout - ms, max timeout for .acquire() call
  • retryInterval - ms, time between acquire attempts if resource locked
  • refreshInterval - ms, auto-refresh interval

Example

const Mutex = require('redis-semaphore').Mutex
const Redis = require('ioredis')

// TypeScript
// import { Mutex } from 'redis-semaphore'
// import Redis from 'ioredis'

const redisClient = new Redis()

async function doSomething() {
  const mutex = new Mutex(redisClient, 'lockingResource')
  await mutex.acquire()
  try {
    // critical code
  } finally {
    await mutex.release()
  }
}

Semaphore

See RedisLabs: Basic counting sempahore

This implementation is slightly different from the algorithm described in the book, but the main idea has not changed.

zrank check replaced with zcard, so now it is fair as RedisLabs: Fair semaphore (see tests).

In edge cases (node time difference is greater than lockTimeout) both algorithms are not fair due cleanup stage (removing expired members from sorted set), so FairSemaphore API has been removed (it's safe to replace it with Semaphore).

Most reliable way to use: lockTimeout is greater than possible node clock differences, refreshInterval is not 0 and is less enough than lockTimeout (by default is lockTimeout * 0.8)

new Semaphore(redisClient, key, maxCount [, { lockTimeout = 10000, acquireTimeout = 10000, retryInterval = 10, refreshInterval = lockTimeout * 0.8 }])

• redisClient - required, configured redis client
• key - required, key for locking resource (final key in redis: semaphore:<key>)
• maxCount - required, maximum simultaneously resource usage count
• timeouts optional
  • lockTimeout - ms, time after semaphore will be auto released (expired)
  • acquireTimeout - ms, max timeout for .acquire() call
  • retryInterval - ms, time between acquire attempts if resource locked
  • refreshInterval - ms, auto-refresh interval

Example

const Semaphore = require('redis-semaphore').Semaphore
const Redis = require('ioredis')

// TypeScript
// import { Semaphore } from 'redis-semaphore'
// import Redis from 'ioredis'

const redisClient = new Redis()

async function doSomething() {
  const semaphore = new Semaphore(redisClient, 'lockingResource', 5)
  await semaphore.acquire()
  try {
    // maximum 5 simultaneously executions
  } finally {
    await semaphore.release()
  }
}

MultiSemaphore

Same as Semaphore with one difference - MultiSemaphore will try to acquire multiple permits instead of one.

MultiSemaphore and Semaphore shares same key namespace and can be used together (see test/src/RedisMultiSemaphore.test.ts).

new MultiSemaphore(redisClient, key, maxCount, permits [, { lockTimeout = 10000, acquireTimeout = 10000, retryInterval = 10, refreshInterval = lockTimeout * 0.8 }])

• redisClient - required, configured redis client
• key - required, key for locking resource (final key in redis: semaphore:<key>)
• maxCount - required, maximum simultaneously resource usage count
• permits - required, number of acquiring permits
• timeouts optional
  • lockTimeout - ms, time after semaphore will be auto released (expired)
  • acquireTimeout - ms, max timeout for .acquire() call
  • retryInterval - ms, time between acquire attempts if resource locked
  • refreshInterval - ms, auto-refresh interval

Example

const MultiSemaphore = require('redis-semaphore').MultiSemaphore
const Redis = require('ioredis')

// TypeScript
// import { MultiSemaphore } from 'redis-semaphore'
// import Redis from 'ioredis'

const redisClient = new Redis()

async function doSomething() {
  const semaphore = new MultiSemaphore(redisClient, 'lockingResource', 5, 2)

  await semaphore.acquire()
  try {
    // make 2 parallel calls to remote service which allow only 5 simultaneously calls
  } finally {
    await semaphore.release()
  }
}

License

MIT