README.md in redis_lock-0.1.0 vs README.md in redis_lock-0.2.0

- old
+ new

@@ -1,9 +1,10 @@ # RedisLock +**use cases:** -Do not allow anyone to perfor de same operation while this is running. -Do not perform this operation unless the previous was executed in more than 5 minutes ago. +- Do not allow anyone to perform de same operation while this is running. +- Do not perform this operation unless the previous was executed in more than 5 minutes ago. ## Installation Add this line to your application's Gemfile: @@ -19,15 +20,45 @@ $ gem install redis_lock ## Setup +This setup it's optional in any instance of `RedisLock` you can provide an optional +argument `:redis`. +But if you do not want to provide it in all the instances is a good shortcut to +set it here. + ```ruby RedisLock.setup do |config| + # redis + # Accepts `block` (or something responding to `#call`) or `Hash` + # + # In test configuration like your `spec_helper` + # recommend `mock_redis` gem + # example: + # config.redis = -> { MockRedis.new } + # + # When using Sidekiq + # example: + # config.redis = -> { Sidekiq.redis{ |r| r } } + # + # In `Rails` + # example: + # config.redis = -> do + # if Rails.env.test? + # MockRedis.new + # elsif Rails.env.development? + # { host: '127.0.0.1', port: 6379 } + # else + # Sidekiq.redis{ |r| r } + # end + # end config.redis = { host: '127.0.0.1' port: 6379 db: 2 } + # logger + # default: Logger.new(STDOUT) config.logger = Rails.logger end ``` ## Usage @@ -40,23 +71,138 @@ lock.set(20) #=> true lock.locked? #=> true lock.remove #=> true lock.locked? #=> false ``` - +__as Mutex__ ```ruby lock = RedisLock.new('my_key') -out = subject.perform do - #no one can perform the same operation while this is running - {}.tap do |t| - t[:locked?] = subject.locked? - end +out = lock.if_open do |l| + # no one can perform the same operation while this is running + l.set(30) # place the lock so no one else can perform this tasks + sleep 3 # Do something + l.unlock! # release the lock + :hello end -out[:locked?] #=> true -# once the block has finished releases the lock +out #=> :hello lock.locked? #=> false ``` +__blocking for a time__ + +Send email to user. The User should receive only 1 email per day + +```ruby +ttl = (24 * 3600) # one day +lock = RedisLock.new("User:1-sales-products") +lock.if_open do |l| + # Send Email + l.set(ttl) +end +``` + +## Methods: + +__set__ +Will store the key to redis with a ttl (time to live). +args: + - ttl # default: 60 + - opts # default: {} + * value (String) - default: time now + * px (true) - miliseconds instead of seconds default: false + * nk (true) - Only set the key if it does not already exist. + * xx (true) - Only set the key if it already exist. +```ruby +lock = RedisLock.new('my_key') + +lock.set(60) +lock.ttl #=> 60 +lock.open? # => false +``` + +_with options_ + +```ruby +lock = RedisLock.new('my_key') + +lock.set(60, nx: true) # only if the key does not exists +# => true (key has been stored) +lock.ttl #=> 60 +lock.open? # => false +``` + +Redis documentation: https://redis.io/commands/set + +Set key to hold the string value. If key already holds a value, it is overwritten, regardless of its type. Any previous time to live associated with the key is discarded on successful SET operation. + +EX seconds -- Set the specified expire time, in seconds. +PX milliseconds -- Set the specified expire time, in milliseconds. +NX -- Only set the key if it does not already exist. +XX -- Only set the key if it already exist. + + +__locked?__ +Returns `true` if lock is set + +```ruby +lock = RedisLock.new('my_key') +lock.set(60) # => true (key has been stored) +lock.locked? # => true +lock.remove +lock.locked? # => false +``` +_alias method:_ `exists?` + +__open?__ +Returns `true` if NO lock is set + +```ruby +lock = RedisLock.new('my_key') +lock.open? # => true +lock.set(60) # => true (key has been stored) +lock.open? # => false +``` +_alias method:_ `unlocked?` + +__delete__ +Removes the key from the Redis store + +```ruby +lock = RedisLock.new('my_key') +lock.set(60) # => true (key has been stored) +lock.locked? # => true +lock.delete +lock.locked? # => false +``` +_alias methods:_ `unlock!`,`open!` + +__value__ +Returns the value stored in redis + +```ruby +lock = RedisLock.new('my_key') +lock.set(60, value: 'hi there!') +lock.value # => 'hi there!' +``` +__ttl__ +Returns the pending ttl (time to live) + +```ruby +lock = RedisLock.new('my_key') +lock.set(60) +lock.ttl # => 60 +sleep 10 +lock.ttl # => 50 +``` + +__having already a connection:__ _example: Sidekiq_ + +```ruby +Sidekiq.redis do |connection| + lock = RedisLock.new('my_key', redis: connection) + # do something +end +``` ## Development After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment. To install this gem onto your local machine, run `bundle exec rake install`.