redis-semaphore

To prevent dead clients from holding locks forever, you can use a stale-check mechanism. If a lock is older than the specified timeout, it can be considered stale.

Option 1: Automatic check on lock

Pass :stale_client_timeout (in seconds) during initialization. The semaphore will check for stale locks every time you attempt to call lock.

Option 2: Watchdog thread

Run a separate thread that calls release_stale_locks! frequently. This is more effective as it can unblock processes currently waiting in a lock call.

# Option 1: Automatic check
s = Redis::Semaphore.new(:stale_semaphore, :stale_client_timeout => 5)

# Option 2: Watchdog thread
Thread.new do
  watchdog = Redis::Semaphore.new(:semaphore, :stale_client_timeout => 5)
  while(true)
    watchdog.release_stale_locks!
    sleep 1
  end
end

Install the gem using the standard Ruby gem command:

$ gem install redis-semaphore

You can use lock with a block for automatic management, or call lock and unlock linearly. When using linear calls, you must call unlock to prevent the resource from staying locked indefinitely.

Blocking Behavior (v0.3.0+)

• lock: Blocks indefinitely until a resource is available.
• lock(nil): Blocks indefinitely (legacy behavior).
• lock(0): Non-blocking. Returns immediately if no resource is available.
• lock(timeout): Blocks for a maximum of timeout seconds.

# Using a block (recommended: auto-unlocks even on exceptions)
s.lock do
  work
end

# Linear calls (manual unlock required)
s.lock
work
s.unlock

# Non-blocking attempt
if s.lock(0)
  work
  s.unlock
else
  puts "No resource available"
end

# Blocking with a timeout
if s.lock(5)
  work
  s.unlock
else
  puts "Timed out"
end

Expiration

Pass :expiration (in seconds) to the constructor. This uses the Redis EXPIRE command on semaphore keys to ensure they are eventually cleaned up. Warning: Use this carefully; if the expiration is too short, the semaphore might disappear while a client is still in a critical section.

Local Time

By default, the library uses the Redis server's time (via the TIME command) to ensure consistency across distributed clients. To save a network round-trip and use the client's local clock instead, set :use_local_time => true.

# With expiration and local time
s = Redis::Semaphore.new(:name, :expiration => 100, :use_local_time => true)

The wait and signal methods provide traditional semaphore functionality.

• wait: Retrieves a resource (aliased to lock).
• signal: Returns a resource to the semaphore. If you pass a specific token, that token is returned. If no token is passed, a new unique token is generated.

This is useful for producer/consumer patterns where one process acquires a resource and another releases it.

# Consumer process
token = sem.wait

# Producer process
sem.signal(token) # Returns the specific token
# OR
sem.signal         # Returns a new unique token

Initialize a new Redis::Semaphore instance. You can provide a name, a host, or a custom Redis client.

To create a Mutex (only one process allowed), omit the :resources option. To create a Semaphore (multiple processes allowed), set the :resources option to the desired number of available slots.

Note: It is recommended to use a unique Redis client per thread because the underlying BLPOP command is blocking.

# Create a Mutex
s = Redis::Semaphore.new(:semaphore_name, :host => "localhost")

# Create a Semaphore with 5 resources
s = Redis::Semaphore.new(:semaphore_name, :resources => 5, :host => "localhost")

# Use a custom Redis client
r = Redis.new(:host => "localhost", :db => 222)
s = Redis::Semaphore.new(:another_name, :redis => r)

Use exists? to check if the semaphore exists and available_count to see how many resources are currently free.

puts "Exists" if s.exists?
puts "Available: #{s.available_count}"

Query the state of the semaphore using these methods:

• exists?: Returns true if the semaphore has been initialized in Redis.
• locked?(token = nil): Returns true if the semaphore is currently held. If a token is provided, it checks if that specific token is currently held. If no token is provided, it checks if any tokens are held.
• available_count: Returns the number of resources currently available for acquisition.

if semaphore.exists?
  puts "Available resources: #{semaphore.available_count}"
end

if semaphore.locked?
  puts "Semaphore is currently in use"
end

The delete! method removes all keys associated with the semaphore from Redis, including the availability list, the grabbed tokens list, the existence token, and the version key. Use this to completely reset or destroy a semaphore.

semaphore.delete!

The Redis::Semaphore class provides a way to implement distributed semaphores (and mutexes) using Redis. It allows you to limit the number of concurrent processes that can execute a specific block of code.

To use it, instantiate a Redis::Semaphore with a Redis client and a unique name. You can then use #acquire to block until a slot is available, or #try_acquire to attempt to acquire a slot without blocking.

# Example of basic usage
semaphore = Redis::Semaphore.new(redis_client, name: 'my_resource_lock', limit: 5)

# Blocking acquire
semaphore.acquire do
  # Critical section: only up to 5 processes can be here at once
end

# Non-blocking attempt
if semaphore.try_acquire
  begin
    # Critical section
  ensure
    semaphore.release
  end
else
  puts "Resource busy"
end