gcslock 1.0.1 → 1.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1d0120bfbfe6842595ebbdcdb1108937c61ee4e04ea71214ae0027b0ed0e68e1
-  data.tar.gz: 6002bf7b00837cf7685400909d550104ced2fc6b99fe22097589c6fde59b6ae7
+  metadata.gz: 2fa87f56360a57de01a55b6b9cf5607b678f38d719b5e5e82f6a77dba84ecf6c
+  data.tar.gz: c121126258ba7b7da738ed1afd61a68d13a191f0e18f5e3318bc30f8a81fb1d8
 SHA512:
-  metadata.gz: 3bea490c78bb1e57788500046967379c4f69862e7b49c03eae367547233b811671c0316152ff231d643dbd70378775af3786d292a4d0c7d557fa3b34e53986f2
-  data.tar.gz: 9388122c6c3a2c3db1250177f4e75dc040de63cb5d0a9f839533a4bb02d7d2d9a143eec0e415466880267b0ed04a770c1437f012bb6c1aa564b4ce31c0ebca8d
+  metadata.gz: d4ac377cc6e39833e5ccc8afedcaa1df7c186a5ff230b9cb1c7f991c74e67e0c4d0c6fb29e445e226ba40daebcffe7fc6a1f80224434709ca8710058116c26ef
+  data.tar.gz: fc2b9b5c25f468e430f035b48edfe254f35b47ebd45bf81c7a5d84b532ed389764353e24ce9a18e358544e33306838dfb6ff8b7b7349e0d27e7171920b012443

data/README.md

@@ -15,7 +15,7 @@ require 'gcslock/mutex'
 
 m = GCSLock::Mutex.new('your-bucket-name', 'my-file.lock')
 m.synchronize do
-  // Protected and globally serialized computation happens here.
+  # Protected and globally serialized computation happens here.
 end
 ```
 

data/lib/gcslock/errors.rb

@@ -1,5 +1,6 @@
 module GCSLock
   class Error < StandardError; end
+
   class LockAlreadyOwnedError < Error; end
   class LockNotOwnedError < Error; end
   class LockNotFoundError < Error; end

data/lib/gcslock/mutex.rb

@@ -2,6 +2,7 @@ require 'google/cloud/storage'
 require 'securerandom'
 
 require_relative 'errors'
+require_relative 'utils'
 
 module GCSLock
   class Mutex
@@ -16,35 +17,29 @@ module GCSLock
     end
 
     # Attempts to grab the lock and waits if it isn't available.
-    # Raises `ThreadError` if `mutex` was locked by the current thread.
+    #
+    # @param timeout [Integer] the duration to wait before cancelling the operation
+    #   if the lock was not obtained (unlimited if _nil_).
+    #
+    # @return [Boolean] `true` if the lock was obtained.
+    #
+    # @raise [LockAlreadyOwnedError] if the lock is already owned by the current instance.
+    # @raise [LockTimeoutError] if the lock was not obtained before reaching the timeout.
     def lock(timeout: nil)
       raise LockAlreadyOwnedError, "Mutex for #{@object.name} is already owned by this process" if owned?
 
-      backoff = @min_backoff
-
-      now = Time.now
-      end_time = now + timeout unless timeout.nil?
-
-      loop do
-        return true if try_lock
-        break if !timeout.nil? && now + backoff >= end_time
-        sleep(backoff)
-
-        backoff_opts = [@max_backoff, backoff * 2]
-
-        unless timeout.nil?
-          now = Time.now
-          diff = end_time - now
-          backoff_opts.push(diff) if diff > 0
+      begin
+        Utils.backoff(min_backoff: @min_backoff, max_backoff: @max_backoff, timeout: timeout) do
+          try_lock
         end
-
-        backoff = backoff_opts.min
+      rescue LockTimeoutError
+        raise LockTimeoutError, "Unable to get mutex for #{@object.name} before timeout"
       end
-
-      raise LockTimeoutError, "Unable to get mutex for #{@object.name} before timeout"
     end
 
-    # Returns `true` if this lock is currently held by some thread.
+    # Verifies if the lock is already taken.
+    #
+    # @return [Boolean] `true` if this lock is currently held.
     def locked?
       @object.reload!
       @object.exists?
@@ -52,25 +47,36 @@ module GCSLock
       false
     end
 
-    # Returns `true` if this lock is currently held by current thread.
+    # Verifies if the lock is already owned by this instance.
+    #
+    # @return [Boolean] `true` if this lock is currently held by this instance.
     def owned?
       locked? && @object.size == @uuid.size && @object.download.read == @uuid
     end
 
     # Obtains a lock, runs the block, and releases the lock when the block completes.
-    # Raises `LockAlreadyOwnedError` if the lock is already owned by the current instance.
+    #
+    # @param timeout [Integer] the duration to wait before cancelling the operation
+    #   if the lock was not obtained (unlimited if _nil_).
+    #
+    # @return [Object] what the called block returned.
+    #
+    # @raise [LockAlreadyOwnedError] if the lock is already owned by the current instance.
+    # @raise [LockTimeoutError] if the lock was not obtained before reaching the timeout.
     def synchronize(timeout: nil)
-      raise LockAlreadyOwnedError, "Mutex for #{@object.name} is already owned by this process" if owned?
-
       lock(timeout: timeout)
       begin
-        yield
+        block = yield
       ensure
         unlock
       end
+
+      block
     end
 
-    # Attempts to obtain the lock and returns immediately. Returns `true` if the lock was granted.
+    # Attempts to obtain the lock and returns immediately.
+    #
+    # @return [Boolean] `true` if the lock was granted.
     def try_lock
       @client.service.service.insert_object(
         @bucket.name,
@@ -86,15 +92,27 @@ module GCSLock
       false
     end
 
-    # Releases the lock. Raises `LockNotOwnedError` if the lock is not owned by the current instance.
+    # Releases the lock.
+    #
+    # @return _nil_
+    #
+    # @raise [LockNotOwnedError] if the lock is not owned by the current instance.
     def unlock
       raise LockNotOwnedError, "Mutex for #{@object.name} is not owned by this process" unless owned?
       @object.delete
+
+      nil
     end
 
-    # Releases the lock even if not owned by this instance. Raises `LockNotFoundError` if the lock cannot be found.
+    # Releases the lock even if not owned by this instance.
+    #
+    # @return _nil_
+    #
+    # @raise [LockNotFoundError] if the lock is not held by anyone.
     def unlock!
       @object.delete
+
+      nil
     rescue Google::Cloud::NotFoundError => e
       raise LockNotFoundError, "Mutex for #{@object.name} not found"
     end

data/lib/gcslock/semaphore.rb

@@ -0,0 +1,161 @@
+require 'google/cloud/storage'
+require 'securerandom'
+
+require_relative 'errors'
+require_relative 'mutex'
+require_relative 'utils'
+
+module GCSLock
+  class Semaphore
+    def initialize(bucket, object, count, client: nil, uuid: nil, min_backoff: nil, max_backoff: nil)
+      @client = client || Google::Cloud::Storage.new
+      @bucket = bucket
+      @object = object
+      @count = count
+
+      @uuid = uuid || SecureRandom.uuid
+      @min_backoff = min_backoff || 0.01
+      @max_backoff = max_backoff || 5.0
+
+      @permits = []
+    end
+
+    # Attempts to grab permits and waits if it isn't available.
+    #
+    # @param permits [Integer] the number of permits to acquire
+    # @param timeout [Integer] the duration to wait before cancelling the operation
+    #   if the lock was not obtained (unlimited if _nil_).
+    # @param permits_to_check [Integer] the number of permits to check for acquisition
+    #   until the required number of permits is secured for each iteration
+    #   (defaults to _nil_, all permits if _nil_)
+    #
+    # @return [Boolean] `true` if the lock was obtained.
+    #
+    # @raise [LockAlreadyOwnedError] if the permit is already owned by the current instance.
+    # @raise [LockTimeoutError] if the permits were not obtained before reaching the timeout.
+    def acquire(permits: 1, timeout: nil, permits_to_check: nil)
+      begin
+        Utils.backoff(min_backoff: @min_backoff, max_backoff: @max_backoff, timeout: timeout) do
+          try_acquire(permits: permits, permits_to_check: permits_to_check)
+        end
+      rescue LockTimeoutError
+        raise LockTimeoutError, "Unable to get semaphore permit for #{@object} before timeout"
+      end
+    end
+
+    # Attempts to obtain a permit and returns immediately.
+    #
+    # @param permits [Integer] the number of permits to acquire
+    # @param permits_to_check [Integer] the number of permits to check for acquisition
+    #   until the required number of permits is secured (defaults to _nil_, all permits if _nil_)
+    #
+    # @return [Boolean] `true` if the requested number of permits was granted.
+    def try_acquire(permits: 1, permits_to_check: nil)
+      acquired = []
+
+      @count.times.to_a.sample(permits_to_check || @count).each do |index|
+        mutex = mutex_object(index: index)
+        if mutex.try_lock
+          acquired.push(mutex)
+          break if acquired.size == permits
+        end
+      end
+
+      if acquired.size < permits
+        acquired.each { |mutex| mutex.unlock }
+        return false
+      end
+
+      @permits.push(*acquired)
+      true
+    end
+
+    # Releases the given number of permits.
+    #
+    # @param permits [Integer] the number of permits to acquire
+    #
+    # @return _nil_
+    #
+    # @raise [LockNotOwnedError] if the permit is not owned by the current instance.
+    def release(permits: 1)
+      permits.times do
+        raise LockNotOwnedError, "No semaphore for #{@object} is owned by this process" unless @permits&.any?
+
+        @permits.pop.unlock
+      end
+
+      nil
+    end
+
+    # Releases all of the owned permits.
+    #
+    # @return _nil_
+    #
+    # @raise [LockNotOwnedError] if the permit is not owned by the current instance.
+    def release_all
+      while @permits&.any?
+        @permits.pop.unlock
+      end
+
+      nil
+    end
+
+    # Force releases all of the permits in the semaphore, even if not owned.
+    #
+    # @return _nil_
+    def release_all!
+      mutexes = @count.times.map { |index| mutex_object(index: index) }
+      mutexes.each do |mut|
+        mut.unlock!
+      rescue LockNotFoundError
+        nil
+      end
+
+      @permits = []
+
+      nil
+    end
+
+    # Acquires and returns all permits that are immediately available.
+    #
+    # @return [Integer] The number of permits acquired
+    def drain_permits
+      mutexes = @count.times.map { |index| mutex_object(index: index) }
+      mutexes.select! { |mutex| mutex.try_lock }
+
+      @permits.push(*mutexes)
+
+      mutexes.size
+    end
+
+    # Returns the current number of permits available for this semaphore.
+    #
+    # @return [Integer] The number of permits available
+    def available_permits
+      mutexes = @count.times.map { |index| mutex_object(index: index) }
+      mutexes.select! { |mutex| !mutex.locked? }
+
+      mutexes.size
+    end
+
+    # Returns the current number of permits owned by this process for this semaphore.
+    #
+    # @return [Integer] The number of permits owned by this process
+    def owned_permits
+      @permits.select! { |mutex| mutex.owned? }
+      @permits.size
+    end
+
+    private
+
+    def mutex_object(index: nil)
+      GCSLock::Mutex.new(
+        @bucket, "#{@object}.#{index.nil? ? rand(@count) : index}",
+        client: @client,
+        uuid: @uuid,
+        min_backoff: @min_backoff,
+        max_backoff: @max_backoff,
+      )
+    end
+  end
+end

data/lib/gcslock/utils.rb

@@ -0,0 +1,31 @@
+module GCSLock
+  class Utils
+    class << self
+      def backoff(min_backoff:, max_backoff:, timeout: nil)
+        backoff = min_backoff
+
+        now = Time.now
+        end_time = now + timeout unless timeout.nil?
+
+        loop do
+          return true if yield
+          break if !timeout.nil? && now + backoff >= end_time
+          sleep(backoff)
+
+          backoff_opts = [max_backoff, backoff * 2]
+
+          unless timeout.nil?
+            now = Time.now
+            diff = end_time - now
+            backoff_opts.push(diff) if diff > 0
+          end
+
+          backoff = backoff_opts.min
+        end
+
+        raise LockTimeoutError, "Backoff timed out"
+      end
+    end
+  end
+end
+

data/lib/gcslock/version.rb

@@ -1,3 +1,3 @@
 module GCSLock
-  VERSION = '1.0.1'.freeze
+  VERSION = '1.0.2'.freeze
 end

data/spec/gcslock/mutex_spec.rb

@@ -33,13 +33,13 @@ describe GCSLock::Mutex do
       allow(@bucket).to receive(:file).and_return(@object)
     end
 
-    it 'initializes in GCS client when none provided' do
+    it 'initializes a GCS client when none provided' do
       expect(Google::Cloud::Storage).to receive(:new).once
 
       GCSLock::Mutex.new(@bucket_name, @object_name)
     end
 
-    it 'initializes in GCS client when none provided' do
+    it 'does not initialize a GCS client when none provided' do
       expect(Google::Cloud::Storage).not_to receive(:new)
 
       GCSLock::Mutex.new(@bucket_name, @object_name, client: @gcs)
@@ -75,7 +75,7 @@ describe GCSLock::Mutex do
       it 'sleeps and retry when failing on the first try_lock' do
         expect(@mutex).to receive(:owned?).once.and_return(false)
         expect(@mutex).to receive(:try_lock).once.and_return(false)
-        expect(@mutex).to receive(:sleep).once
+        expect(GCSLock::Utils).to receive(:sleep).once
         expect(@mutex).to receive(:try_lock).once.and_return(true)
 
         @mutex.lock(timeout: 2)
@@ -83,7 +83,7 @@ describe GCSLock::Mutex do
 
       it 'sleeps just the time needed to retry once at the end' do
         expect(@mutex).to receive(:owned?).once.and_return(false)
-        expect(@mutex).to receive(:sleep).at_least(2).times
+        expect(GCSLock::Utils).to receive(:sleep).at_least(2).times
         expect(@mutex).to receive(:try_lock).at_least(3).times.and_return(false)
 
         expect do
@@ -178,7 +178,6 @@ describe GCSLock::Mutex do
 
     describe '.synchronize' do
       it 'locks, yields and unlock the mutex' do
-        expect(@mutex).to receive(:owned?).once.and_return(false)
         expect(@mutex).to receive(:lock).once.and_return(true)
         expect(@mutex).to receive(:unlock).once
 
@@ -192,7 +191,6 @@ describe GCSLock::Mutex do
 
       it 'raises an error if the lock is already owned' do
         expect(@mutex).to receive(:owned?).once.and_return(true)
-        expect(@mutex).not_to receive(:lock)
         expect(@mutex).not_to receive(:unlock)
 
         has_yielded = false

data/spec/gcslock/semaphore_spec.rb

@@ -0,0 +1,401 @@
+require 'spec_helper'
+require 'gcslock/semaphore'
+
+describe GCSLock::Semaphore do
+  before do
+    @bucket_name = 'bucket'
+    @object_name = 'object'
+    @count = 5
+
+    @gcs = instance_double(Google::Cloud::Storage::Project)
+    allow(Google::Cloud::Storage).to receive(:new).and_return(@gcs)
+
+    @uuid = 'some_uuid'
+    allow(SecureRandom).to receive(:uuid).and_return(@uuid)
+  end
+
+  describe '.initialize' do
+    before do
+      @gcs = double(Google::Cloud::Storage)
+      allow(Google::Cloud::Storage).to receive(:new).and_return(@gcs)
+
+      @bucket = double(Google::Cloud::Storage::Bucket)
+      allow(@gcs).to receive(:bucket).and_return(@bucket)
+
+      @object = double(Google::Cloud::Storage::File)
+      allow(@bucket).to receive(:file).and_return(@object)
+    end
+
+    it 'initializes in GCS client when none provided' do
+      expect(Google::Cloud::Storage).to receive(:new).once
+
+      GCSLock::Semaphore.new(@bucket_name, @object_name, @count)
+    end
+
+    it 'does not initialize a GCS client when none provided' do
+      expect(Google::Cloud::Storage).not_to receive(:new)
+
+      GCSLock::Semaphore.new(@bucket_name, @object_name, @count, client: @gcs)
+    end
+
+    it 'initializes a randomly generated unique ID' do
+      expect(SecureRandom).to receive(:uuid).once
+
+      GCSLock::Semaphore.new(@bucket_name, @object_name, @count)
+    end
+  end
+
+  context 'initialized' do
+    before do
+      @sem = GCSLock::Semaphore.new(@bucket_name, @object_name, @count)
+    end
+
+    describe '.acquire' do
+      it 'sleeps and retry when failing on the first try_acquire' do
+        expect(@sem).to receive(:try_acquire).once.and_return(false)
+        expect(GCSLock::Utils).to receive(:sleep).once
+        expect(@sem).to receive(:try_acquire).once.and_return(true)
+
+        @sem.acquire(timeout: 2)
+      end
+
+      it 'sleeps just the time needed to retry once at the end' do
+        expect(GCSLock::Utils).to receive(:sleep).at_least(2).times
+        expect(@sem).to receive(:try_acquire).at_least(3).times.and_return(false)
+
+        expect do
+          @sem.acquire(timeout: 0.03)
+        end.to raise_error(GCSLock::LockTimeoutError)
+      end
+
+      it 'raises an error if unable to get a permit when reaching the timeout' do
+        expect(@sem).to receive(:try_acquire).once.and_return(false)
+
+        expect do
+          @sem.acquire(timeout: 0)
+        end.to raise_error(GCSLock::LockTimeoutError)
+      end
+
+      it 'calls try_acquire with the right value for permits_to_check if passed as argument' do
+        permits_to_check = 2
+
+        expect(@sem).to receive(:try_acquire).with(permits: 1, permits_to_check: permits_to_check).once.and_return(true)
+
+        @sem.acquire(permits_to_check: permits_to_check)
+      end
+    end
+
+    describe '.try_acquire' do
+      before do
+        @mutexes = @count.times.map do |index|
+          mutex = instance_double(GCSLock::Mutex)
+
+          allow(@sem).to receive(:mutex_object).with(index: index).and_return(mutex)
+
+          mutex
+        end
+      end
+
+      it 'returns true if permit (1) obtained, while all mutex available' do
+        @mutexes.each do |mutex|
+          allow(mutex).to receive(:try_lock).and_return(true)
+        end
+
+        expect(@sem.try_acquire).to be(true)
+      end
+
+      it 'returns true if permit (1) obtained, while only a single mutex available' do
+        @mutexes.each_with_index do |mutex, index|
+          allow(mutex).to receive(:try_lock).and_return(index == 2)
+        end
+
+        expect(@sem.try_acquire).to be(true)
+      end
+
+      it 'returns true if permit (3) obtained, while all mutex available' do
+        @mutexes.each do |mutex|
+          allow(mutex).to receive(:try_lock).and_return(true)
+        end
+
+        expect(@sem.try_acquire(permits: 3)).to be(true)
+      end
+
+      it 'returns true if permit (3) obtained, while only a single mutex available' do
+        available_mutexes = @count.times.to_a.sample(3)
+
+        @mutexes.each_with_index do |mutex, index|
+          allow(mutex).to receive(:try_lock).and_return(available_mutexes.include?(index))
+        end
+
+        expect(@sem.try_acquire(permits: 3)).to be(true)
+      end
+
+      it 'returns false if no permit available' do
+        @mutexes.each_with_index do |mutex, index|
+          allow(mutex).to receive(:try_lock).and_return(false)
+        end
+
+        expect(@sem.try_acquire).to be(false)
+      end
+
+      it 'returns false if not enough permits available' do
+        available_mutexes = @count.times.to_a.sample(2)
+
+        @mutexes.each_with_index do |mutex, index|
+          allow(mutex).to receive(:try_lock).and_return(available_mutexes.include?(index))
+          expect(mutex).to receive(:unlock).once if available_mutexes.include?(index)
+        end
+
+        expect(@sem.try_acquire(permits: 3)).to be(false)
+      end
+    end
+
+    describe '.release' do
+      before do
+        @mutexes = @count.times.map do |index|
+          mutex = instance_double(GCSLock::Mutex)
+
+          mutex
+        end
+
+        @permits = @count.times.to_a.sample(3).map { |index| @mutexes[index] }
+
+        @sem.instance_variable_set(:@permits, @permits)
+      end
+
+      it 'releases the permits (1) when called' do
+        expect(@permits.last).to receive(:unlock).once
+
+        @sem.release
+
+        expect(@sem.instance_variable_get(:@permits).size).to eq(2)
+      end
+
+      it 'releases the permits (3) when called' do
+        @permits.each do |mutex|
+          expect(mutex).to receive(:unlock).once
+        end
+
+        @sem.release(permits: 3)
+
+        expect(@sem.instance_variable_get(:@permits).size).to eq(0)
+      end
+
+      it 'raises an error when releasing more permits (4) than owned (3), but still released the owned locks' do
+        @permits.each do |mutex|
+          expect(mutex).to receive(:unlock).once
+        end
+
+        expect do
+          @sem.release(permits: 4)
+        end.to raise_error(GCSLock::LockNotOwnedError)
+
+        expect(@sem.instance_variable_get(:@permits).size).to eq(0)
+      end
+    end
+
+    describe '.release_all' do
+      before do
+        @mutexes = @count.times.map do |index|
+          mutex = instance_double(GCSLock::Mutex)
+
+          mutex
+        end
+
+        @permits = @count.times.to_a.sample(3).map { |index| @mutexes[index] }
+
+        @sem.instance_variable_set(:@permits, @permits)
+      end
+
+      it 'releases all owned permits when called' do
+        @permits.each do |mutex|
+          expect(mutex).to receive(:unlock).once
+        end
+
+        @sem.release_all
+
+        expect(@sem.instance_variable_get(:@permits).size).to eq(0)
+      end
+    end
+
+    describe '.release_all!' do
+      before do
+        @mutexes = @count.times.map do |index|
+          mutex = instance_double(GCSLock::Mutex)
+
+          allow(@sem).to receive(:mutex_object).with(index: index).and_return(mutex)
+
+          mutex
+        end
+
+        @permits = @count.times.to_a.sample(3).map { |index| @mutexes[index] }
+
+        @sem.instance_variable_set(:@permits, @permits)
+      end
+
+      it 'releases all permits when called' do
+        @mutexes.each do |mutex|
+          expect(mutex).to receive(:unlock!).once
+        end
+
+        @sem.release_all!
+
+        expect(@sem.instance_variable_get(:@permits).size).to eq(0)
+      end
+    end
+
+    describe '.drain_permits' do
+      before do
+        @mutexes = @count.times.map do |index|
+          mutex = instance_double(GCSLock::Mutex)
+
+          allow(@sem).to receive(:mutex_object).with(index: index).and_return(mutex)
+
+          mutex
+        end
+      end
+
+      it 'gets all the available permits (all)' do
+        @mutexes.each do |mutex|
+          expect(mutex).to receive(:try_lock).and_return(true)
+        end
+
+        expect(@sem.drain_permits).to eq(@count)
+
+        expect(@sem.instance_variable_get(:@permits).size).to eq(@count)
+      end
+
+      it 'gets all the available permits (2) when already owning some' do
+        owned_permits = @count.times.to_a.sample(3)
+        permits = owned_permits.map { |index| @mutexes[index] }
+        @sem.instance_variable_set(:@permits, permits)
+
+        @mutexes.each_with_index do |mutex, index|
+          expect(mutex).to receive(:try_lock).and_return(!owned_permits.include?(index))
+        end
+
+        expect(@sem.drain_permits).to eq(@count - owned_permits.size)
+
+        expect(@sem.instance_variable_get(:@permits).size).to eq(@count)
+      end
+
+      it 'gets all available permits (2) when somebody else is already owning some' do
+        owned_permits = @count.times.to_a.sample(3)
+
+        @mutexes.each_with_index do |mutex, index|
+          expect(mutex).to receive(:try_lock).and_return(!owned_permits.include?(index))
+        end
+
+        expect(@sem.drain_permits).to eq(@count - owned_permits.size)
+
+        expect(@sem.instance_variable_get(:@permits).size).to eq(@count - owned_permits.size)
+      end
+
+      it 'gets nothing when all the permits are owned' do
+        @mutexes.each_with_index do |mutex, index|
+          expect(mutex).to receive(:try_lock).and_return(false)
+        end
+
+        expect(@sem.drain_permits).to eq(0)
+
+        expect(@sem.instance_variable_get(:@permits).size).to eq(0)
+      end
+    end
+
+    describe '.available_permits' do
+      before do
+        @mutexes = @count.times.map do |index|
+          mutex = instance_double(GCSLock::Mutex)
+
+          allow(@sem).to receive(:mutex_object).with(index: index).and_return(mutex)
+
+          mutex
+        end
+      end
+
+      it 'returns the number of available permits (all)' do
+        @mutexes.each do |mutex|
+          expect(mutex).to receive(:locked?).and_return(false)
+        end
+
+        expect(@sem.available_permits).to eq(@count)
+
+        expect(@sem.instance_variable_get(:@permits).size).to eq(0)
+      end
+
+      it 'returns the number of available permits (2) when already owning some' do
+        owned_permits = @count.times.to_a.sample(3)
+        permits = owned_permits.map { |index| @mutexes[index] }
+        @sem.instance_variable_set(:@permits, permits.dup)
+
+        @mutexes.each_with_index do |mutex, index|
+          expect(mutex).to receive(:locked?).and_return(owned_permits.include?(index))
+        end
+
+        expect(@sem.available_permits).to eq(@count - owned_permits.size)
+
+        expect(@sem.instance_variable_get(:@permits)).to eq(permits)
+      end
+
+      it 'returns the number of available permits (2) when somebody else is already owning some' do
+        owned_permits = @count.times.to_a.sample(3)
+
+        @mutexes.each_with_index do |mutex, index|
+          expect(mutex).to receive(:locked?).and_return(owned_permits.include?(index))
+        end
+
+        expect(@sem.available_permits).to eq(@count - owned_permits.size)
+
+        expect(@sem.instance_variable_get(:@permits).size).to eq(0)
+      end
+
+      it 'returns 0 when all the permits are owned' do
+        @mutexes.each_with_index do |mutex, index|
+          expect(mutex).to receive(:locked?).and_return(true)
+        end
+
+        expect(@sem.available_permits).to eq(0)
+
+        expect(@sem.instance_variable_get(:@permits).size).to eq(0)
+      end
+    end
+
+    describe '.owned_permits' do
+      before do
+        @mutexes = @count.times.map do |index|
+          mutex = instance_double(GCSLock::Mutex)
+
+          mutex
+        end
+      end
+
+      it 'returns the owned permits after checking they are properly owned (all owned)' do
+        owned_permits = @count.times.to_a.sample(3)
+        permits = owned_permits.map { |index| @mutexes[index] }
+        @sem.instance_variable_set(:@permits, permits.dup)
+
+        permits.each do |mutex|
+          expect(mutex).to receive(:owned?).and_return(true)
+        end
+
+        expect(@sem.owned_permits).to eq(owned_permits.size)
+        expect(@sem.instance_variable_get(:@permits)).to eq(permits)
+      end
+
+      it 'returns the owned permits after checking they are properly owned (one not owned)' do
+        owned_permits = @count.times.to_a.sample(3)
+        permits = owned_permits.map { |index| @mutexes[index] }
+        not_really_owned = permits.sample
+        @sem.instance_variable_set(:@permits, permits.dup)
+
+        permits.each do |mutex|
+          expect(mutex).to receive(:owned?).and_return(mutex != not_really_owned)
+        end
+
+        expect(@sem.owned_permits).to eq(owned_permits.size - 1)
+        expect(@sem.instance_variable_get(:@permits)).to eq(permits.select { |mutex| mutex != not_really_owned })
+      end
+    end
+
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: gcslock
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.0.2
 platform: ruby
 authors:
 - Raphaël Beamonte
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-05-20 00:00:00.000000000 Z
+date: 2020-11-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: google-api-client
@@ -81,8 +81,11 @@ files:
 - gcslock.gemspec
 - lib/gcslock/errors.rb
 - lib/gcslock/mutex.rb
+- lib/gcslock/semaphore.rb
+- lib/gcslock/utils.rb
 - lib/gcslock/version.rb
 - spec/gcslock/mutex_spec.rb
+- spec/gcslock/semaphore_spec.rb
 - spec/spec_helper.rb
 homepage: https://github.com/XaF/gcslock-ruby
 licenses: