• Stars
    star
    655
  • Rank 65,586 (Top 2 %)
  • Language
    Ruby
  • License
    BSD 2-Clause "Sim...
  • Created over 9 years ago
  • Updated 5 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Redlock is a redis-based distributed lock implementation in Ruby. More than 20M downloads.

Build Status Coverage Status Code Climate Gem Version Inline docs

Redlock - A ruby distributed lock using redis.

Distributed locks are a very useful primitive in many environments where different processes require to operate with shared resources in a mutually exclusive way.

There are a number of libraries and blog posts describing how to implement a DLM (Distributed Lock Manager) with Redis, but every library uses a different approach, and many use a simple approach with lower guarantees compared to what can be achieved with slightly more complex designs.

This is an implementation of a proposed distributed lock algorithm with Redis. It started as a fork from antirez implementation.

Compatibility

  • It works with Redis server versions 6.0 or later.
  • Redlock >= 2.0 only works with RedisClient client instance.

Installation

Add this line to your application's Gemfile:

gem 'redlock'

And then execute:

$ bundle

Or install it yourself as:

$ gem install redlock

Documentation

RubyDoc

Usage example

Acquiring a lock

NOTE: All expiration durations are in milliseconds.

  # Locking
  lock_manager = Redlock::Client.new([ "redis://127.0.0.1:7777", "redis://127.0.0.1:7778", "redis://127.0.0.1:7779" ])
  first_try_lock_info = lock_manager.lock("resource_key", 2000)
  second_try_lock_info = lock_manager.lock("resource_key", 2000)

  p first_try_lock_info
  # => {validity: 1987, resource: "resource_key", value: "generated_uuid4"}

  p second_try_lock_info
  # => false

  # Unlocking
  lock_manager.unlock(first_try_lock_info)

  second_try_lock_info = lock_manager.lock("resource_key", 2000)

  p second_try_lock_info
  # => {validity: 1962, resource: "resource_key", value: "generated_uuid5"}

There's also a block version that automatically unlocks the lock:

lock_manager.lock("resource_key", 2000) do |locked|
  if locked
    # critical code
  else
    # error handling
  end
end

There's also a bang version that only executes the block if the lock is successfully acquired, returning the block's value as a result, or raising an exception otherwise. Passing a block is mandatory.

begin
  block_result = lock_manager.lock!("resource_key", 2000) do
    # critical code
  end
rescue Redlock::LockError
  # error handling
end

Extending a lock

To extend the life of the lock:

begin
  lock_info = lock_manager.lock("resource_key", 2000)
  while lock_info
    # Critical code

    # Time up and more work to do? Extend the lock.
    lock_info = lock_manager.lock("resource key", 3000, extend: lock_info)
  end
rescue Redlock::LockError
  # error handling
end

The above code will also acquire the lock if the previous lock has expired and the lock is currently free. Keep in mind that this means the lock could have been acquired and released by someone else in the meantime. To only extend the life of the lock if currently locked by yourself, use the extend_only_if_locked parameter:

lock_manager.lock("resource key", 3000, extend: lock_info, extend_only_if_locked: true)

Querying lock status

You can check if a resource is locked:

resource = "resource_key"
lock_info = lock_manager.lock(resource, 2000)
lock_manager.locked?(resource)
#=> true

lock_manager.unlock(lock_info)
lock_manager.locked?(resource)
#=> false

Any caller can call the above method to query the status. If you hold a lock and would like to check if it is valid, you can use the valid_lock? method:

lock_info = lock_manager.lock("resource_key", 2000)
lock_manager.valid_lock?(lock_info)
#=> true

lock_manager.unlock(lock_info)
lock_manager.valid_lock?(lock_info)
#=> false

The above methods are not safe if you are using this to time critical code, since they return true if the lock has not expired, even if there's only (for example) 1ms left on the lock. If you want to safely time the lock validity, you can use the get_remaining_ttl_for_lock and get_remaining_ttl_for_resource methods.

Use get_remaining_ttl_for_lock if you hold a lock and want to check the TTL specifically for your lock:

resource = "resource_key"
lock_info = lock_manager.lock(resource, 2000)
sleep 1

lock_manager.get_remaining_ttl_for_lock(lock_info)
#=> 986

lock_manager.unlock(lock_info)
lock_manager.get_remaining_ttl_for_lock(lock_info)
#=> nil

Use get_remaining_ttl_for_resource if you do not hold a lock, but want to know the remaining TTL on a locked resource:

# Some part of the code
resource = "resource_key"
lock_info = lock_manager.lock(resource, 2000)

# Some other part of the code
lock_manager.locked?(resource)
#=> true
lock_manager.get_remaining_ttl_for_resource(resource)
#=> 1975

# Sometime later
lock_manager.locked?(resource)
#=> false
lock_manager.get_remaining_ttl_for_resource(resource)
#=> nil

Redis client configuration

Redlock::Client expects URLs, or configurations or Redis objects on initialization. Redis objects should be used for configuring the connection in more detail, i.e. setting username and password.

servers = [ 'redis://localhost:6379', RedisClient.new(:url => 'redis://someotherhost:6379') ]
redlock = Redlock::Client.new(servers)

To utilize Redlock::Client with sentinels you can pass an instance of RedisClient or just a configuration hash as part of the servers array during initialization.

config = {
  name: "mymaster",
  sentinels: [
    { host: "127.0.0.1", port: 26380 },
    { host: "127.0.0.1", port: 26381 },
  ],
  role: :master
}
client = RedisClient.sentinel(**config).new_client
servers = [ config, client ]
redlock = Redlock::Client.new(servers)

Redlock supports the same configuration hash as RedisClient.

Redlock configuration

It's possible to customize the retry logic providing the following options:

  lock_manager = Redlock::Client.new(
                  servers, {
                  retry_count:   3,
                  retry_delay:   200, # milliseconds
                  retry_jitter:  50,  # milliseconds
                  redis_timeout: 0.1  # seconds
                 })

It is possible to associate :retry_delay option with Proc object. It will be called every time, with attempt number as argument, to get delay time value before next retry.

retry_delay = proc { |attempt_number| 200 * attempt_number ** 2 } # delay of 200ms for 1st retry, 800ms for 2nd retry, etc.
lock_manager = Redlock::Client.new(servers, retry_delay: retry_delay)

For more information you can check documentation.

Run tests

Make sure you have docker installed.

$ make

Disclaimer

This code implements an algorithm which is currently a proposal, it was not formally analyzed. Make sure to understand how it works before using it in your production environments. You can see discussion about this approach at reddit and also the Antirez answers for some critics.

Contributing

  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create a new Pull Request

More Repositories

1

digital_video_introduction

A hands-on introduction to video technology: image, video, codec (av1, vp9, h265) and more (ffmpeg encoding). Translations: 🇺🇸 🇨🇳 🇯🇵 🇮🇹 🇰🇷 🇷🇺 🇧🇷 🇪🇸
Jupyter Notebook
15,022
star
2

ffmpeg-libav-tutorial

FFmpeg libav tutorial - learn how media works from basic to transmuxing, transcoding and more. Translations: 🇺🇸 🇨🇳 🇰🇷 🇪🇸 🇻🇳 🇧🇷
C
9,443
star
3

linux-network-performance-parameters

Learn where some of the network sysctl variables fit into the Linux/Kernel network flow. Translations: 🇷🇺
5,276
star
4

cdn-up-and-running

CDN Up and Running - Building a CDN from Scratch to Learn about CDN, Nginx, Lua, Prometheus, Grafana, Load balancing, and Containers.
Lua
3,033
star
5

live-stream-from-desktop

Provide guidance to test live streaming (mpeg-dash or hls) or vod from your desktop
Shell
169
star
6

nginx-lua-redis-rate-measuring

A lua library to provide distributed rate measurement using nginx + redis, you can use it to do a throttling system within many nodes.
Lua
144
star
7

http-video-streaming-troubleshooting

A collection of fixes / problem solutions to HTTP video streaming
77
star
8

nott

The New OTT Platform - an excuse to discuss and design a simple edge computing platform
Lua
50
star
9

video-containers-debugging-tools

A set of command lines to debug video streaming files like mp4 (MPEG-4 Part 14), ts (MPEG-2 Part 1), fmp4 in Dash, HLS, or MSS, with or without DRM.
45
star
10

python_chip16

A full implementation (tested) of chip16 virtual machine, or emulator as you wish, using python and rendering with opengl.
Python
34
star
11

scte-35-scte-104-scte-67

Documentation/references about Dynamic Ad Insertion (DAI) through SCTE-104, SCTE-35 to HLS, MPEG DASH, Smooth, RTMP
30
star
12

tls_certificate_generation

Use temporary Amazon EC2 / Digital Ocean cloud machines to get / renew letsencrypt certificates
Shell
28
star
13

docker-ffmpeg-vmaf

Docker FFmpeg VMAF usage example / tips / workflow
25
star
14

edge-computing-resty

a simple edge computing platform using nginx, lua and rails
Ruby
24
star
15

lua-resty-dynacode

A library to provide dynamic (via json/API) load of lua byte code into nginx/openresty.
Ruby
24
star
16

resty-bakery

An Nginx+Lua library to modify media manifests like HLS and MPEG Dash, acting like a proxy.
Lua
21
star
17

player-ffmpeg

Up to date tutorial of ffmpeg
C
19
star
18

fake-as-fuck

I'm a lonely, lonely lord. Pick another day to be restored. Just another fate that's going overboard.
Python
19
star
19

lua-resty-perf

A small ngx resty lua library to benchmark memory and throughput of a function.
Lua
16
star
20

kaltura-media-framework-docker-compose

A docker compose for https://github.com/kaltura/media-framework
Go
13
star
21

cassandra-lock

A ruby lib to achieve consensus with Cassandra
Ruby
12
star
22

dotfiles

dotfiles
Shell
8
star
23

JChip16BR

An java implementation of VM Chip16.
Assembly
8
star
24

clappr-pause-tab-visibility

A clappr container plugin to pause when user is in another tab and resume when the user is back.
JavaScript
6
star
25

py-chip8

introduction to low level thingies
Python
6
star
26

tc-linux-rate-delay-specific-ip-on-docker

a docker experiment to learn to apply tc (linux traffic control) to shaping and delaying network for a specific CIDR/network.
Shell
6
star
27

jgb

gameboy emulator written in JavaScript
JavaScript
4
star
28

ruby_meta_programming

Meta programming Ruby - Book practise
Ruby
4
star
29

dcpu16

JDCPU16BR
Java
4
star
30

nginx-throttling-leaderboard

POC to test local throttling and top leaderboard most requested token
Lua
3
star
31

js_learning

My javascript training files
JavaScript
3
star
32

jmf

jmf - java media framework example of server and player
Java
3
star
33

hackday-27-06-19

Globo.com hackday-27-06-19
Lua
2
star
34

clojure_playground

It is a simple repo to study clojure
Clojure
2
star
35

clappr-dash-dashjs

A dash playback (based on dashjs) for 🎬 Clappr
HTML
2
star
36

clojure-playground

Silly repo -> While I'm reading and learning about clojure I will use this guy to keep track
Clojure
2
star
37

clint

An ordinary encoder.
JavaScript
2
star
38

jchip8br

Automatically exported from code.google.com/p/jchip8br
Java
1
star
39

playground.sh

A place to practice the fine art of shell script
Shell
1
star
40

d3.playground

A place to play with d3js
1
star
41

rslimbr

Ruby Slim Protocol for Fitnesse compatible with Ruby 1.9.x
Ruby
1
star
42

minimal-js-dash-player

JavaScript
1
star
43

mediainfo

docker image for mediainfo
1
star
44

playground.coffe

just another playground for a 'new' language
1
star
45

angularjs-pet

Pet project to learn and apply angularjs for large project with tests and fine structure.
JavaScript
1
star
46

jschip16br

the chip16 virtual machine specification implemented using javascript
1
star
47

test_legacy

Improve your legacy project providing certain level of test automation
Ruby
1
star
48

rspec_book

the book in praticse
Ruby
1
star
49

cat

Container as a Teacher
Shell
1
star