counting_semaphore 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: cffd9d409923265971a2d4b2994a22b5a0a84ce57552f90ef3b0ce4d3ddb0c3d
+  data.tar.gz: d8ffaf1fa6d13ece63fed8d75bcd687d00450f378e93c19f06a4669f8722a457
+SHA512:
+  metadata.gz: 3c59f43dfdac58fbe4a2c660138a7f6a2d2a70ead0afa85d5acf666fd72018a064a814cf933251ea4f21858ffd6e94931a5baacf4fdca04384d2ff8c76149175
+  data.tar.gz: ffb43973632962da0194d463688e82d7125fcafef9e1546e9a89a180c5ed22670cbf4d10061fb13df5586342f4e81a7b2324c6631074aaa4e6d9f56f65103b82

data/.github/workflows/lint.yml

@@ -0,0 +1,23 @@
+name: Lint
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    
+    steps:
+    - uses: actions/checkout@v4
+    
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version-file: .ruby-version
+        bundler-cache: true
+    
+    - name: Run linter
+      run: bundle exec standardrb

data/.github/workflows/test.yml

@@ -0,0 +1,34 @@
+name: Test
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    
+    services:
+      redis:
+        image: redis:7
+        ports:
+          - 6379:6379
+        options: >-
+          --health-cmd "redis-cli ping"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+    
+    steps:
+    - uses: actions/checkout@v4
+    
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version-file: .ruby-version
+        bundler-cache: true
+    
+    - name: Run tests
+      run: bundle exec rake test

data/.gitignore

@@ -0,0 +1,56 @@
+*.gem
+*.rbc
+/.config
+/coverage/
+/InstalledFiles
+/pkg/
+/spec/reports/
+/spec/examples.txt
+/test/tmp/
+/test/version_tmp/
+/tmp/
+
+# Used by dotenv library to load environment variables.
+# .env
+
+# Ignore Byebug command history file.
+.byebug_history
+
+## Specific to RubyMotion:
+.dat*
+.repl_history
+build/
+*.bridgesupport
+build-iPhoneOS/
+build-iPhoneSimulator/
+
+## Specific to RubyMotion (use of CocoaPods):
+#
+# We recommend against adding the Pods directory to your .gitignore. However
+# you should judge for yourself, the pros and cons are mentioned at:
+# https://guides.cocoapods.org/using/using-cocoapods.html#should-i-check-the-pods-directory-into-source-control
+#
+# vendor/Pods/
+
+## Documentation cache and generated files:
+/.yardoc/
+/_yardoc/
+/doc/
+/rdoc/
+
+## Environment normalization:
+/.bundle/
+/vendor/bundle
+/lib/bundler/man/
+
+# for a library or gem, you might want to ignore these files since the code is
+# intended to run in multiple environments; otherwise, check them in:
+# Gemfile.lock
+# .ruby-version
+# .ruby-gemset
+
+# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
+.rvmrc
+
+# Used by RuboCop. Remote config files pulled in from inherit_from directive.
+# .rubocop-https?--*

data/.ruby-version

@@ -0,0 +1 @@
+3.4.2

data/AGENTS.md

@@ -0,0 +1,4 @@
+* Try to observe Rails conventions even if this is not a Rails application
+* Place your temporary scripts in scripts/ if you generate them
+* After modifying a file, run standardrb linter on it to auto-format, observe linter requirements
+* Add frozen string literal magic comment to any Ruby files you touch or create

data/Gemfile

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in counting_semaphore.gemspec
+gemspec

data/Gemfile.lock

@@ -0,0 +1,76 @@
+PATH
+  remote: .
+  specs:
+    counting_semaphore (0.1.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    ast (2.4.3)
+    connection_pool (2.5.4)
+    json (2.15.1)
+    language_server-protocol (3.17.0.5)
+    lint_roller (1.1.0)
+    minitest (5.26.0)
+    parallel (1.27.0)
+    parser (3.3.9.0)
+      ast (~> 2.4.1)
+      racc
+    prism (1.6.0)
+    racc (1.8.1)
+    rainbow (3.1.1)
+    rake (13.3.0)
+    redis (5.4.1)
+      redis-client (>= 0.22.0)
+    redis-client (0.26.1)
+      connection_pool
+    regexp_parser (2.11.3)
+    rubocop (1.80.2)
+      json (~> 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      parallel (~> 1.10)
+      parser (>= 3.3.0.2)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.46.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.47.1)
+      parser (>= 3.3.7.2)
+      prism (~> 1.4)
+    rubocop-performance (1.25.0)
+      lint_roller (~> 1.1)
+      rubocop (>= 1.75.0, < 2.0)
+      rubocop-ast (>= 1.38.0, < 2.0)
+    ruby-progressbar (1.13.0)
+    standard (1.51.1)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.0)
+      rubocop (~> 1.80.2)
+      standard-custom (~> 1.0.0)
+      standard-performance (~> 1.8)
+    standard-custom (1.0.2)
+      lint_roller (~> 1.0)
+      rubocop (~> 1.50)
+    standard-performance (1.8.0)
+      lint_roller (~> 1.1)
+      rubocop-performance (~> 1.25.0)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.1.0)
+
+PLATFORMS
+  arm64-darwin-24
+  ruby
+
+DEPENDENCIES
+  connection_pool (~> 2.4)
+  counting_semaphore!
+  minitest (~> 5.0)
+  rake (~> 13.0)
+  redis (~> 5.0)
+  standard (>= 1.35.1)
+
+BUNDLED WITH
+   2.6.9

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Julik Tarkhanov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,88 @@
+# counting_semaphore
+
+A counting semaphore implementation for Ruby with local and distributed (Redis) variants.
+
+> [!TIP]
+> This gem was created for [Cora,](https://cora.computer/) 
+> your personal e-mail assistant. 
+> Send them some love for allowing me to share it.
+
+## What is it for?
+
+When you have a metered and limited resource that only supports a certain number of simultaneous operations you need a [semaphore](https://en.wikipedia.org/wiki/Semaphore_(programming)) primitive. In Ruby, a semaphore usually controls access to "one whole resource":
+
+```ruby
+sem = Semaphore.new
+sem.with_lease do
+  # Critical section where you hold access to the resource
+end
+```
+
+This is well covered - for example - by POSIX semaphores if you are within one machine, or by the venerable [redis-semaphore](https://github.com/dv/redis-semaphore)
+
+The problem comes if you need to hold access to a certain _amount_ of a resource. For example, you know that you are doing 5 expensive operations in bulk, and you know that your entire application can only be doing 20 in total - governed by the API access limits. For that, you need a [counting semaphore](https://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/Semaphore.html#acquire-instance_method) - such a semaphore is provided by [concurrent-ruby](https://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/Semaphore.html#acquire-instance_method) for example. It allows you to acquire a certain number of _permits_ and then release them.
+
+This library does the same and also has a simple `LocalSemaphore` which can be used across threads or fibers. This allows for coordination if you are only running one process/Ractor. It is thread-safe and fairly simple in operation:
+
+```ruby
+require "counting_semaphore"
+
+# Create a semaphore that allows up to 10 concurrent operations
+semaphore = CountingSemaphore::LocalSemaphore.new(10)
+
+# Do an operation that occupies 2 slots
+semaphore.with_lease(2) do
+  # This block can only run when 2 tokens are available
+  # Do your work here
+  puts "Doing work that requires 2 tokens"
+end
+```
+
+However, we also include a Redis based _shared counting semaphore_ which you can use for resource access control across processes and across machines - provided they have access to a shared Redis server. The semaphore is identified by a _namespace_ - think of it as the `id` of the semaphore. Leases are obtained and released using Redis blocking operations and Lua scripts (for atomicity):
+
+```ruby
+require "counting_semaphore"
+require "redis"  # Redis is required for RedisSemaphore
+
+# Create a Redis semaphore using Redis
+# You can also pass your ConnectionPool instance.
+redis = Redis.new
+semaphore = CountingSemaphore::RedisSemaphore.new(10, "api_ratelimit", redis:)
+
+# and then use it the same as the LocalSemaphore
+semaphore.with_lease(3) do
+  # This block can only run when 3 tokens are available
+  # Works across multiple processes/machines
+  puts "Doing distributed work"
+end
+```
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "counting_semaphore"
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install counting_semaphore
+
+There are no dependencies (but you need the `redis` gem for development - or you can feed a compatible object instead).
+
+## Development
+
+Do a fresh checkout and run `bundle install`. Then run tests and linting using `bundle exec rake`.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/julik/counting_semaphore.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,12 @@
+require "bundler/gem_tasks"
+require "rake/testtask"
+require "standard/rake"
+
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+  t.verbose = true
+end
+
+task default: [:test, :standard]

data/lib/counting_semaphore/local_semaphore.rb

@@ -0,0 +1,94 @@
+# A counting semaphore that allows up to N concurrent operations.
+# When capacity is exceeded, operations block until resources become available.
+module CountingSemaphore
+  class LocalSemaphore
+    SLEEP_WAIT_SECONDS = 0.25
+
+    # @return [Integer]
+    attr_reader :capacity
+
+    # Initialize the semaphore with a maximum capacity.
+    #
+    # @param capacity [Integer] Maximum number of concurrent operations allowed
+    # @param logger [Logger] the logger
+    # @raise [ArgumentError] if capacity is not positive
+    def initialize(capacity, logger: CountingSemaphore::NullLogger)
+      raise ArgumentError, "Capacity must be positive, got #{capacity}" unless capacity > 0
+      @capacity = capacity.to_i
+      @leased = 0
+      @mutex = Mutex.new
+      @condition = ConditionVariable.new
+      @logger = logger
+    end
+
+    # Acquire a lease for the specified number of tokens and execute the block.
+    # Blocks until sufficient resources are available.
+    #
+    # @param token_count [Integer] Number of tokens to acquire
+    # @param timeout_seconds [Integer] Maximum time to wait for lease acquisition (default: 30 seconds)
+    # @yield The block to execute while holding the lease
+    # @return The result of the block
+    # @raise [ArgumentError] if token_count is negative or exceeds the semaphore capacity
+    # @raise [CountingSemaphore::LeaseTimeout] if lease cannot be acquired within timeout
+    def with_lease(token_count_num = 1, timeout_seconds: 30)
+      token_count = token_count_num.to_i
+      raise ArgumentError, "Token count must be non-negative, got #{token_count}" if token_count < 0
+      if token_count > @capacity
+        raise ArgumentError, "Cannot lease #{token_count} slots as we only allow #{@capacity}"
+      end
+
+      # Handle zero tokens case - no waiting needed
+      return yield if token_count.zero?
+
+      did_accept = false
+      start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+      loop do
+        # Check timeout
+        elapsed_time = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
+        if elapsed_time >= timeout_seconds
+          raise CountingSemaphore::LeaseTimeout.new(token_count, timeout_seconds, self)
+        end
+
+        did_accept = @mutex.synchronize do
+          if (@capacity - @leased) >= token_count
+            @leased += token_count
+            true
+          else
+            false
+          end
+        end
+
+        if did_accept
+          @logger.debug { "Leased #{token_count} and now in use #{@leased}/#{@capacity}" }
+          return yield
+        end
+
+        @logger.debug { "Unable to lease #{token_count}, #{@leased}/#{@capacity} waiting" }
+
+        # Wait on condition variable with remaining timeout
+        remaining_timeout = timeout_seconds - elapsed_time
+        if remaining_timeout > 0
+          @mutex.synchronize do
+            @condition.wait(@mutex, remaining_timeout)
+          end
+        end
+      end
+    ensure
+      if did_accept
+        @logger.debug { "Returning #{token_count} leased slots" }
+        @mutex.synchronize do
+          @leased -= token_count
+          @condition.broadcast # Signal waiting threads
+        end
+      end
+    end
+
+    # Get the current number of tokens currently leased
+    #
+    # @return [Integer] Number of tokens currently in use
+    def currently_leased
+      @mutex.synchronize { @leased }
+    end
+  end
+end

data/lib/counting_semaphore/null_logger.rb

@@ -0,0 +1,32 @@
+module CountingSemaphore
+  # A null logger that discards all log messages
+  # Provides the same interface as a real logger but does nothing
+  # Only yields blocks when ENV["RUN_ALL_LOGGER_BLOCKS"] is set to "yes",
+  # which is useful in testing. Block form for Logger calls allows you
+  # to skip block evaluation if the Logger level is higher than your
+  # call, and thus bugs can nest in those Logger blocks. During
+  # testing it is helpful to excercise those blocks unconditionally.
+  module NullLogger
+    def debug(message = nil, &block)
+      yield if block_given? && ENV["RUN_ALL_LOGGER_BLOCKS"] == "yes"
+    end
+
+    def info(message = nil, &block)
+      yield if block_given? && ENV["RUN_ALL_LOGGER_BLOCKS"] == "yes"
+    end
+
+    def warn(message = nil, &block)
+      yield if block_given? && ENV["RUN_ALL_LOGGER_BLOCKS"] == "yes"
+    end
+
+    def error(message = nil, &block)
+      yield if block_given? && ENV["RUN_ALL_LOGGER_BLOCKS"] == "yes"
+    end
+
+    def fatal(message = nil, &block)
+      yield if block_given? && ENV["RUN_ALL_LOGGER_BLOCKS"] == "yes"
+    end
+
+    extend self
+  end
+end