restrainer 1.0.1 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ff5a0d8ca6659d4feeb9d6fd8e453e1b1733917c20dbfadb4686173998085903
-  data.tar.gz: 5f3bb001fd3fde135999d50e2383d6f4e826c54a35c4ab02a11d45c7cc29bce3
+  metadata.gz: 6e999370930d2d5686a75214e30aa63223b828f77ba5ba94d48506f5afcca8c9
+  data.tar.gz: 494b772ddc967646f15f3ba1db809fd34eb6f12a0714242f327326e33af1b648
 SHA512:
-  metadata.gz: e9c097fbdb451fb6de6574427f3b672a09db445cb0df2f0784bd9133adbb97c614a73177c6017f0b6fe57618da24b69734538d127c84b54ec8495514d1c86660
-  data.tar.gz: 0404b8096e47387750cbef9b2ba89d5de6e795f19633c6d613ae202d211b510758db3d1d6d342a2f8c1da4a1d2e1d15727ec6034c38e2de4d6cac23341ffc4d2
+  metadata.gz: b2b8dd65c7cd2a5d96daa8c67fe2d7b3a71a77a9035ff00a065b693d179ec1d71f6084ab1d1d8b98f5b9d62bda7628e0d898a0c32d637bc1fcb02032e3e6d7fa
+  data.tar.gz: e4c85a817f9e0f9b2445e000b8f1f3c2cc79d74023020b8f02fa9f9895e61ee528f6b69aacc88dde8a3fbe6c04cb10f494075e7188bacf37e049486e516a2513

data/CHANGE_LOG.md

@@ -1,3 +1,9 @@
+# 1.1.0
+
+* Expose manually locking and unlocking processes.
+
+* Allow passing in a redis connection in the constructor.
+
 # 1.0.1
 
 * Use Lua script to avoid race conditions and ensure no extra processes slip through.

data/README.md

@@ -17,11 +17,24 @@ If the throttle is already full, the block will not be run and a `Restrainer::Th
 
 You can also override the limit in the `throttle` method. Setting a limit of zero will disable processing entirely. Setting a limit less than zero will remove the limit. Note that the limit set in the throttle is not shared with other processes, but the count of the number of processes is shared. Thus it is possible to have the throttle allow one process but reject another if the limits are different.
 
+You can also manually lock and release processes using the `lock` and `release` methods if your logic needs to break out of a block.
+
+```ruby
+  process_id = restrainer.lock!
+  begin
+    # Do something
+  ensure
+    restrainer.release!(process_id)
+  end
+```
+
+If you already hava a unique identifier, you can pass it in to the lock! method. This can be useful if the calls to `lock!` and `release!` are in different parts of the code but have access to the same common identifier. Identifiers are unique per throttle name, so you can use something as simple as database row id.
+
 Instances of Restrainer do not use any internal state to keep track of the number of running processes. All of that information is maintained in redis. Therefore you don't need to worry about maintaining references to Restrainer instances and you can create them as needed as long as they are named consistently. You can create multiple Restrainers for different uses in your application by simply giving them different names.
 
 ### Configuration
 
-To set the redis connection used by for the gem you can either specify a block that yields a Redis object (from the [redis](https://github.com/redis/redis-rb) gem) or you can explicitly set the attribute. The block form is generally preferred since it can work with connection pools, etc.
+To set the redis connection used by for the gem you can either specify a block that yields a `Redis` object (from the [redis](https://github.com/redis/redis-rb) gem) or you can explicitly set the attribute. The block form is generally preferred since it can work with connection pools, etc.
 
 ```ruby
 Restrainer.redis{ connection_pool.redis }
@@ -29,6 +42,12 @@ Restrainer.redis{ connection_pool.redis }
 Restrainer.redis = redis_client
 ```
 
+You can also pass in a `Redis` instance in the constructor.
+
+```ruby
+restrainer = Restrainer.new(limit: 5, redis: my_redis)
+```
+
 ### Internals
 
 To protect against situations where a process is killed without a chance to cleanup after itself (i.e. `kill -9`), each process is only tracked for a limited amount of time (one minute by default). After this time, the Restrainer will assume that the process has been orphaned and removes it from the list.

data/VERSION

@@ -1 +1 @@
-1.0.1
+1.1.0

data/lib/restrainer.rb

@@ -88,11 +88,12 @@ class Restrainer
   # if their process is killed. Processes will automatically be removed from the running jobs list after the
   # specified number of seconds. Note that the Restrainer will not handle timing out any code itself. This
   # value is just used to insure the integrity of internal data structures.
-  def initialize(name, limit:, timeout: 60)
+  def initialize(name, limit:, timeout: 60, redis: nil)
     @name = name
     @limit = limit
     @timeout = timeout
     @key = "#{self.class.name}.#{name.to_s}"
+    @redis ||= redis
   end
 
   # Wrap a block with this method to throttle concurrent execution. If more than the alotted number
@@ -105,28 +106,55 @@ class Restrainer
 
     # limit of less zero is no limit; limit of zero is allow none
     return yield if limit < 0
-    raise ThrottledError.new("#{self.class}: #{@name} is not allowing any processing") if limit == 0
-
-    # Grab a reference to the redis instance to that it will be consistent throughout the method
-    redis = self.class.redis
-    process_id = SecureRandom.uuid
-    add_process!(redis, process_id, limit)
     
+    process_id = lock!(limit: limit)
     begin
       yield
     ensure
-      remove_process!(redis, process_id)
+      release!(process_id)
     end
   end
+  
+  # Obtain a lock on one the allowed processes. The method returns a process
+  # identifier that must be passed to the release! to release the lock.
+  # You can pass in a unique identifier if you already have one.
+  #
+  # Raises a Restrainer::ThrottledError if the lock cannot be obtained.
+  #
+  # The limit argument can be used to override the value set in the constructor.
+  def lock!(process_id = nil, limit: limit)
+    process_id ||= SecureRandom.uuid
+    limit ||= self.limit
+
+    # limit of less zero is no limit; limit of zero is allow none
+    return nil if limit < 0
+    raise ThrottledError.new("#{self.class}: #{@name} is not allowing any processing") if limit == 0
+
+    add_process!(redis, process_id, limit)
+    process_id
+  end
+  
+  # release one of the allowed processes. You must pass in a process id returned by the lock method.
+  def release!(process_id)
+    remove_process!(redis, process_id) unless process_id.nil?
+  end
 
   # Get the number of processes currently being executed for this restrainer.
-  def current(redis = nil)
-    redis ||= self.class.redis
+  def current
     redis.zcard(key).to_i
   end
+  
+  # Clear all locks
+  def clear!
+    redis.del(key)
+  end
 
   private
 
+  def redis
+    @redis || self.class.redis
+  end
+  
   # Hash key in redis to story a sorted set of current processes.
   def key
     @key

data/spec/restrainer_spec.rb

@@ -3,21 +3,25 @@
 require 'spec_helper'
 
 describe Restrainer do
-  
+
+  before(:each) do
+    Restrainer.new(:restrainer_test, limit: 1).clear!
+  end
+
   it "should have a name and max_processes" do
     restrainer = Restrainer.new(:restrainer_test, limit: 1)
     expect(restrainer.name).to eq(:restrainer_test)
     expect(restrainer.limit).to eq(1)
   end
-  
-  it "should run a block" do
+
+  it "should run a block!" do
     restrainer = Restrainer.new(:restrainer_test, limit: 1)
     x = nil
     expect(restrainer.throttle{ x = restrainer.current }).to eq(1)
     expect(x).to eq(1)
     expect(restrainer.current).to eq(0)
   end
-  
+
   it "should throw an error if too many processes are already running" do
     restrainer = Restrainer.new(:restrainer_test, limit: 5)
     x = nil
@@ -34,7 +38,7 @@ describe Restrainer do
     end
     expect(x).to eq(nil)
   end
-  
+
   it "should not throw an error if the number of processes is under the limit" do
     restrainer = Restrainer.new(:restrainer_test, limit: 2)
     x = nil
@@ -43,7 +47,7 @@ describe Restrainer do
     end
     expect(x).to eq(1)
   end
-  
+
   it "should let the throttle method override the limit" do
     restrainer = Restrainer.new(:restrainer_test, limit: 1)
     x = nil
@@ -52,21 +56,21 @@ describe Restrainer do
     end
     expect(x).to eq(1)
   end
-  
+
   it "should allow processing to be turned off entirely by setting the limit to zero" do
     restrainer = Restrainer.new(:restrainer_test, limit: 1)
     x = nil
     expect(lambda{restrainer.throttle(limit: 0){ x = 1 }}).to raise_error(Restrainer::ThrottledError)
     expect(x).to eq(nil)
   end
-  
+
   it "should allow the throttle to be opened up entirely with a negative limit" do
     restrainer = Restrainer.new(:restrainer_test, limit: 0)
     x = nil
     restrainer.throttle(limit: -1){ x = 1 }
     expect(x).to eq(1)
   end
-  
+
   it "should cleanup the running process list if orphaned processes exist" do
     restrainer = Restrainer.new(:restrainer_test, limit: 1, timeout: 10)
     x = nil
@@ -77,4 +81,58 @@ describe Restrainer do
     end
     expect(x).to eq(1)
   end
+
+  it "should be able to lock! and release! processes manually" do
+    restrainer = Restrainer.new(:restrainer_test, limit: 5)
+    p1 = restrainer.lock!
+    begin
+      p2 = restrainer.lock!
+      begin
+        p3 = restrainer.lock!
+        begin
+          p4 = restrainer.lock!
+          begin
+            p5 = restrainer.lock!
+            begin
+              expect{ restrainer.lock! }.to raise_error(Restrainer::ThrottledError)
+            ensure
+              restrainer.release!(p5)
+            end
+            p6 = restrainer.lock!
+            restrainer.release!(p6)
+          ensure
+            restrainer.release!(p4)
+          end
+        ensure
+          restrainer.release!(p3)
+        end
+      ensure
+        restrainer.release!(p2)
+      end
+    ensure
+      restrainer.release!(p1)
+    end
+  end
+
+  it "should be able to pass in the process id" do
+    restrainer = Restrainer.new(:restrainer_test, limit: 1)
+    expect(restrainer.lock!("foo")).to eq "foo"
+  end
+
+  it "should not get a lock! if the limit is 0" do
+    restrainer = Restrainer.new(:restrainer_test, limit: 0)
+    expect{ restrainer.lock! }.to raise_error(Restrainer::ThrottledError)
+  end
+
+  it "should get a lock! if the limit is negative" do
+    restrainer = Restrainer.new(:restrainer_test, limit: -1)
+    process_id = restrainer.lock!
+    expect(process_id).to eq nil
+    restrainer.release!(nil)
+  end
+
+  it "should be able to override the limit in lock!" do
+    restrainer = Restrainer.new(:restrainer_test, limit: 0)
+    restrainer.lock!(limit: 1)
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: restrainer
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.1.0
 platform: ruby
 authors:
 - We Heart It
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-07-03 00:00:00.000000000 Z
+date: 2019-07-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: redis