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()
  // critical code
  await mutex.release()
}

Semaphore

See RedisLabs: Basic counting sempahore

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()
  // maximum 5 simultaneously executions
  await semaphore.release()
}

Fair Semaphore

See RedisLabs: Fair semaphore

new FairSemaphore(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 FairSemaphore = require('redis-semaphore').FairSemaphore
const Redis = require('ioredis')

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

const redisClient = new Redis()

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

License

MIT

Changelog

redis-semaphore@3.0.0

• Breaking change: FairSemaphore has been removed. Use Semaphore instead (has the same "fairness")
  • the acquire method in Semaphore no longer returns a boolean. Instead, it throws an error if it cannot acquire, and if it doesn't throw, you can assume it worked.
• Internal code has been cleaned up
• Added more test, include synthetic node unsynchroned clocks