timed_semaphore 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6356f0e509d4d66d0fe37b7d83e498a7a5c02438
-  data.tar.gz: a4cbfb7255933034f2b97cd3e4d5b1a936519b8d
+  metadata.gz: bab3b772c57f7baf507fd6ed56a86fd52bfa2115
+  data.tar.gz: 5a75209d8eaa5653c94dc0d1bba19c87cc9db74c
 SHA512:
-  metadata.gz: 4520d9f271ade92caec7970c63fa052e38153fe34caacb47898b5a81aabed74b8fa45060e11c9e54ec038c7e9b8e54a62bd23a045a0ff2386fda4eefaf7980ee
-  data.tar.gz: 1d11602b416694c51f45d88291373699793d7543bfbd43c0ee75a1e2dbd154521c0a08ec1cec9a3068be53850b0ff5066485101d85df3fe1a33b9c66668b8830
+  metadata.gz: 42722a9b4048dd59583f8574569dee3870dbf0016b1f8370f406aff14ed1dc3bdf203976135c425f8c2f6f5e6fdcd4d8217afc40094845a846d7e219f511c44a
+  data.tar.gz: 82f7a221df7da977c0aa80448d278cbcf3b2c76d2379af0054ec2e64ef2f7a29421cf7d1ad2d986029befc006fa942cfc61455b1d8d0816d638f19e46aa3e3cd

data/lib/timed_semaphore.rb

@@ -1,4 +1,30 @@
+# TimedSemaphore is a specialized implementation of a Semaphore
+# that gives a number of permits in a given time frame. A use case
+# for it is to limit the load on a resource.
+# The idea is taken from the Apache Commons Lang package.
+# @see https://commons.apache.org/proper/commons-lang/javadocs/api-3.1/org/apache/commons/lang3/concurrent/TimedSemaphore.html
+#   Apache Commons Lang
+#
+# @author ssuljic
+#
+# @example
+#   threads = []
+#   semaphore = TimedSemaphore.new(2, 3)
+#
+#   10.times do
+#     threads << Thread.new do
+#       semaphore.acquire
+#       puts Time.now
+#     end
+#   end
+#
+#   threads.map(&:join)
 class TimedSemaphore
+  # @param num_of_ops [Fixnum] Number of operations
+  #   which should be allowed in a specified time frame.
+  # @param num_of_seconds [Fixnum] Period in seconds after all
+  #   permits are released.
+  # @return [TimedSemaphore] a new instance of TimedSemaphore.
   def initialize(num_of_ops, num_of_seconds)
     @count = 0
     @limit = num_of_ops
@@ -8,7 +34,10 @@ class TimedSemaphore
     @timer = nil
   end
 
-  # Acquires a permit or sleeps the thread if all permits are exhausted
+  # Tries to acquire a permit from the semaphore. This method
+  # will block if the limit for the current period has already
+  # been reached. The first call starts a timer thread for releasing
+  # all permits, which makes the semaphore active
   def acquire
     synchronize do
       @condition.wait while @limit > 0 && @count == @limit
@@ -19,7 +48,8 @@ class TimedSemaphore
 
   private
 
-  # Starts a thread which releases all permits after @period seconds
+  # Starts a timer thread which releases
+  # all permits after @period seconds.
   def start_timer
     synchronize do
       @timer = Thread.new do
@@ -29,7 +59,8 @@ class TimedSemaphore
     end
   end
 
-  # Releases all permits and notifies all waiting threads to try acquire again
+  # Releases all permits and notifies all
+  # waiting threads to try acquire again.
   def release_permits
     synchronize do
       @timer = nil
@@ -38,6 +69,8 @@ class TimedSemaphore
     end
   end
 
+  # Method used for synchronizing on @lock.
+  # Syntactic sugar
   def synchronize(&block)
     fail 'No block given' unless block_given?
     @lock.synchronize(&block)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: timed_semaphore
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - Sadžid Suljić
@@ -45,3 +45,4 @@ specification_version: 4
 summary: Implementation of TimedSemaphore
 test_files:
 - test/timed_semaphore_test.rb
+has_rdoc: