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`.