redis-single-file 0.1.2 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: edb75c9168f41403d71f413fcae1133c4bfc6bff978af32daf40d64c6ab51da0
-  data.tar.gz: 68ec43819a06ebdd69da4ac9a64c67b9c6591ef2f7fcb204883a73f833ccf6d5
+  metadata.gz: 31564fcc0baa415b72345ffc55ff089881bf8329b7cf391b44fb4cac4b57fcc3
+  data.tar.gz: aab08c49cbd524899bfc3176cdfb9e88f953d5e28b38d2a1a43de281e2283622
 SHA512:
-  metadata.gz: d9cef25d4361c94bfcb034a7dea4db8f20cfc36f0515fca827432c38b6a240db9c485af71acac6d9548536f61110ec60d7240f51ac492256c11cffa4c0d0c12f
-  data.tar.gz: 6a330862b3565e93bd6113bbc9cd9b7f04f3efc1f78e2268e14b4ee832e1b820fe8cd8588f607f4726cee1b0c3379aaae0af81667e341e74d5f537804537e503
+  metadata.gz: f4457fb73a80ff69ac740cee3bf4edcca0f986001218b90a855a56aaea7099c8ecf039ab93d8d447890833b570e6053d29426cb69bdf78a9949b52fb333a183c
+  data.tar.gz: 45eee4ae50c3793bd45619685f68b23ed3c9d50287064aefae4d3ddb1c420ae40823adfac47b2677a2572c71f5c7794c61154aca2e2de7f45f6f0cd0ada1f562

data/.rubocop.yml

@@ -41,3 +41,7 @@ RSpec/MultipleExpectations:
 # Example has too many lines. [8/5]
 RSpec/ExampleLength:
   Max: 20
+
+# Rubygems 2FA can't be used with github publish workflow
+Gemspec/RequireMFA:
+  Enabled: false

data/.ruby-version

@@ -0,0 +1 @@
+3.3.6

data/CHANGELOG.md

@@ -1,4 +1,37 @@
-## [Unreleased]
+## [0.1.3] - 2025-02-08
+
+## What's Changed
+
+**Full Changelog**: https://github.com/lifeBCE/redis-single-file/compare/v0.1.2...v0.1.3
+
+---
+<br />
+
+## [0.1.2] - 2025-02-08
+
+## What's Changed
+* publish workflow by @lifeBCE in https://github.com/lifeBCE/redis-single-file/pull/3
+* IGNORE_VERSION: "true" by @lifeBCE in https://github.com/lifeBCE/redis-single-file/pull/4
+* cluster support - v0.1.2 by @lifeBCE in https://github.com/lifeBCE/redis-single-file/pull/5
+
+**Full Changelog**: https://github.com/lifeBCE/redis-single-file/compare/v0.1.1...v0.1.2
+
+---
+<br />
+
+## [0.1.1] - 2025-02-03
+
+## What's Changed
+* github workflows by @lifeBCE in https://github.com/lifeBCE/redis-single-file/pull/1
+* badges by @lifeBCE in https://github.com/lifeBCE/redis-single-file/pull/2
+
+## New Contributors
+* @lifeBCE made their first contribution in https://github.com/lifeBCE/redis-single-file/pull/1
+
+**Full Changelog**: https://github.com/lifeBCE/redis-single-file/commits/v0.1.1
+
+---
+<br />
 
 ## [0.1.0] - 2025-01-31
 

data/README.md

@@ -1,8 +1,7 @@
 [![Build Status](https://github.com/lifeBCE/redis-single-file/actions/workflows/build.yml/badge.svg)](https://github.com/lifeBCE/redis-single-file/actions/workflows/build.yml)
 [![RSpec Status](https://github.com/lifeBCE/redis-single-file/actions/workflows/rspec.yml/badge.svg)](https://github.com/lifeBCE/redis-single-file/actions/workflows/rspec.yml)
-[![CodeQL Status](https://github.com/lifeBCE/redis-single-file/actions/workflows/codeql.yml/badge.svg)](https://github.com/lifeBCE/redis-single-file/actions/workflows/codeql.yml)
 [![Rubocop Status](https://github.com/lifeBCE/redis-single-file/actions/workflows/rubocop.yml/badge.svg)](https://github.com/lifeBCE/redis-single-file/actions/workflows/rubocop.yml)
-[![Benchmark Status](https://github.com/lifeBCE/redis-single-file/actions/workflows/benchmark.yml/badge.svg)](https://github.com/lifeBCE/redis-single-file/actions/workflows/benchmark.yml)
+[![CodeQL Status](https://github.com/lifeBCE/redis-single-file/actions/workflows/codeql.yml/badge.svg)](https://github.com/lifeBCE/redis-single-file/actions/workflows/codeql.yml)
 
 # Redis Single File - Distributed Execution Synchronization
 
@@ -37,6 +36,7 @@ RedisSingleFile.configuration do |config|
   # config.port = '6379'
   # config.name = 'default'
   # config.expire_in = 300
+  # config.concurrency = 1
 end
 ```
 
@@ -66,6 +66,14 @@ end
    end
 ```
 
+#### Support concurrent worker processing
+```ruby
+   semaphore = RedisSingleFile.new(name: :concurrent_queue)
+   semaphore.synchronize(concurrency: 3) do
+      # synchronized logic defined here...
+   end
+```
+
 #### Use your own redis client instance
 ```ruby
    redis = Redis.new(...)
@@ -79,27 +87,29 @@ end
 
 ### Distributed Queue Design
 
-The redis `blpop` command will attempt to pop (delete and return) a value from
-a queue but will block when no values are present in the queue. A timeout can
-be provided to prevent deadlock situations.
-
-To unblock (unlock) an instance, add/push an item to the queue. This is done
-one at a time to controll the serialization of the distrubuted execution. Redis
-selects the instance waiting the longest each time a new token is added.
+> [!IMPORTANT]
+> The redis `blpop` command will attempt to pop (delete and return) a value from
+> a queue but will block when no values are present in the queue. A timeout can
+> be provided to prevent deadlock situations.
+>
+> To unblock (unlock) an instance, add/push an item to the queue. This is done
+> one at a time to controll the serialization of the distrubuted execution. Redis
+> selects the instance waiting the longest each time a new token is added.
 
 ### Auto Expiration
 
-All redis keys are expired and automatically removed after a certain period
-but will be recreated again on the next use. Each new client should face one
-of two scenarios when entering synchronization.
-
-1. The mutex key is not set causing the client to create the keys and prime
-   the queue with its first token unlocking it for the first execution.
-
-2. The mutex key is already set so the client will skip the priming and enter
-   directly into the queue where it should immediately find a token left by
-   the last client upon completion or block waiting for the current client to
-   finish execution.
+> [!NOTE]
+> All redis keys are expired and automatically removed after a certain period
+> but will be recreated again on the next use. Each new client should face one
+> of two scenarios when entering synchronization.
+>
+> 1. The mutex key is not set causing the client to create the keys and prime
+>    the queue with its first token unlocking it for the first execution.
+>
+> 2. The mutex key is already set so the client will skip the priming and enter
+>    directly into the queue where it should immediately find a token left by
+>    the last client upon completion or block waiting for the current client to
+>    finish execution.
 
 ### Considerations over redlock approach
 
@@ -178,6 +188,95 @@ Comparison:
         forked (10x):       56.6 i/s - 76.90x  slower
 ```
 
+## Cluster Management
+
+After installing redis locally, you can use the provided `bin/cluster` script to manage a local cluster. To customize your local cluster, edit the `bin/cluster` script to provide your own values for the following script variables.
+
+```bash
+#
+# configurable settings
+#
+HOST=127.0.0.1
+PORT=30000
+MASTERS=3  # min 3 for cluster
+REPLICAS=2 # replicas per master
+TIMEOUT=2000
+PROTECTED_MODE=yes
+ADDITIONAL_OPTIONS=""
+```
+
+<details>
+<summary><strong>Start cluster nodes</strong></summary>
+
+    $ bin/cluster start
+
+```console
+Starting 30001
+Starting 30002
+Starting 30003
+Starting 30004
+Starting 30005
+Starting 30006
+Starting 30007
+Starting 30008
+Starting 30009
+```
+</details>
+
+<details>
+<summary><strong>Create cluster configuration</strong></summary>
+
+    $ bin/cluster create -f
+
+```console
+>>> Performing hash slots allocation on 9 nodes...
+Master[0] -> Slots 0 - 5460
+Master[1] -> Slots 5461 - 10922
+Master[2] -> Slots 10923 - 16383
+Adding replica 127.0.0.1:30005 to 127.0.0.1:30001
+Adding replica 127.0.0.1:30006 to 127.0.0.1:30001
+Adding replica 127.0.0.1:30007 to 127.0.0.1:30002
+Adding replica 127.0.0.1:30008 to 127.0.0.1:30002
+Adding replica 127.0.0.1:30009 to 127.0.0.1:30003
+Adding replica 127.0.0.1:30004 to 127.0.0.1:30003
+```
+</details>
+
+<details>
+<summary><strong>Stop cluster nodes</strong></summary>
+
+    $ bin/cluster stop
+
+```console
+Stopping 30001
+Stopping 30002
+Stopping 30003
+Stopping 30004
+Stopping 30005
+Stopping 30006
+Stopping 30007
+Stopping 30008
+Stopping 30009
+```
+</details>
+
+<details>
+<summary><strong>Clean local cluster files</strong></summary>
+
+    $ bin/cluster clean
+
+```console
+Cleaning *.log
+Cleaning appendonlydir-*
+Cleaning dump-*.rdb
+Cleaning nodes-*.conf
+```
+</details>
+
+After the cluster is running and configured, you can direct the `test.rb` and `benchmark.rb` scripts at the cluster by setting the port on execution.
+
+    $ REDIS_PORT=30001 bundle exec ruby benchmark.rb
+
 ## Disclaimer
 
 > [!WARNING]

data/benchmark.rb

@@ -3,7 +3,7 @@
 require 'benchmark/ips'
 require 'redis_single_file'
 
-PORT = ENV['WORKFLOW_PORT'] || 6379
+PORT = ENV['REDIS_PORT'] || 6379
 
 scenario_1_semaphore = RedisSingleFile.new(name: :scenario1, port: PORT)
 scenario_2_semaphore = RedisSingleFile.new(name: :scenario2, port: PORT)

data/lib/redis_single_file/cluster_client_builder.rb

@@ -15,7 +15,7 @@ module RedisSingleFile
       #
       # Delegates class method calls to instance method
       #
-      # @param [...] params passes directly to constructor
+      # @param [...] params passed directly to constructor
       # @return [Redis::Cluster] redis cluster instance
       def call(...) = new(...).call
     end
@@ -40,15 +40,21 @@ module RedisSingleFile
     def call
       raise ClusterDisabledError, 'cluster not detected' unless cluster_enabled?
 
-      # use extracted client options with parsed nodes
-      Redis::Cluster.new(**client_options, nodes:)
+      # use extracted client options with parsed master nodes
+      Redis::Cluster.new(**client_options, nodes: master_nodes)
     end
 
     private # ==================================================================
 
     attr_reader :redis
 
-    def nodes
+    def cluster_enabled?
+      redis.info('cluster')['cluster_enabled'] == '1'
+    rescue Redis::CommandError
+      false # assume cluster mode is disabled
+    end
+
+    def master_nodes
       cluster_nodes.filter_map do |node|
         next unless node[:flags].include?('master')
 
@@ -56,10 +62,18 @@ module RedisSingleFile
       end
     end
 
-    def cluster_enabled?
-      redis.info('cluster')['cluster_enabled'] == '1'
-    rescue Redis::CommandError
-      false # assume cluster mode is disabled
+    def client_options
+      config = redis._client.config
+      params = %i[
+        db ssl host port path custom username password protocol
+        ssl_params read_timeout write_timeout connect_timeout
+      ]
+
+      params_hash = params.each.with_object({}) do |key, memo|
+        memo[key] = config.public_send(key)
+      end
+
+      params_hash.merge(url: config.server_url)
     end
 
     def cluster_nodes
@@ -82,19 +96,5 @@ module RedisSingleFile
         }
       end
     end
-
-    def client_options
-      config = redis._client.config
-      params = %i[
-        db ssl host port path custom username password protocol
-        ssl_params read_timeout write_timeout connect_timeout
-      ]
-
-      params_hash = params.each.with_object({}) do |key, memo|
-        memo[key] = config.public_send(key)
-      end
-
-      params_hash.merge(url: config.server_url)
-    end
   end
 end

data/lib/redis_single_file/configuration.rb

@@ -25,6 +25,7 @@ module RedisSingleFile
     DEFAULT_EXPIRE_IN = 300 # 5 mins
     DEFAULT_MUTEX_KEY = 'RedisSingleFile/Mutex/%s'
     DEFAULT_QUEUE_KEY = 'RedisSingleFile/Queue/%s'
+    DEFAULT_CONCURRENCY = 1 # single slot enabled
 
     # class delegation methods to singleton instance
     #
@@ -33,13 +34,21 @@ module RedisSingleFile
     #   Configuration.port => Configuration.instance.port
     #
     class << self
-      %i[host port name expire_in mutex_key queue_key].each do |attr|
+      %i[
+        host
+        port
+        name
+        expire_in
+        concurrency
+        mutex_key
+        queue_key
+      ].each do |attr|
         define_method(attr) { instance.send(attr) }
       end
     end
 
     # writers used in config block to set new values
-    attr_writer :host, :port, :name, :expire_in
+    attr_writer :host, :port, :name, :expire_in, :concurrency
 
     # @return [String] redis server hostname value
     def host = @host || DEFAULT_HOST
@@ -53,6 +62,9 @@ module RedisSingleFile
     # @return [String] redis keys expiration value
     def expire_in = @expire_in || DEFAULT_EXPIRE_IN
 
+    # @return [String] redis lock concurrency value
+    def concurrency = @concurrency || DEFAULT_CONCURRENCY
+
     # @note This attr is not configurable
     # @return [String] synchronization mutex key name
     def mutex_key = @mutex_key || DEFAULT_MUTEX_KEY

data/lib/redis_single_file/semaphore.rb

@@ -12,6 +12,7 @@ module RedisSingleFile
   # @attr name [String] custom sync queue name
   # @attr host [String] host for redis server
   # @attr port [String] port for redis server
+  # @attr concurrency [Integer] simultaneous slots allowed
   #
   # @example Default lock name and infinite blocking
   #   semaphore = RedisSingleFile::Semaphore.new
@@ -65,23 +66,26 @@ module RedisSingleFile
       redis: nil,               # provide your own redis instance
       name: Configuration.name, # designate queue name per session
       host: Configuration.host, # designate redis host per session
-      port: Configuration.port  # designate redis port per session
+      port: Configuration.port, # designate redis port per session
+      concurrency: Configuration.concurrency # concurrent workers
     )
       @redis = redis || Redis.new(host:, port:)
 
       @mutex_val = name
       @mutex_key = format(Configuration.mutex_key, @mutex_val)
       @queue_key = format(Configuration.queue_key, @mutex_val)
+      @concurrency = concurrency.to_i
     end
 
     # Queues up client and waits for turn to execute. Returns nil
     # when queue wait time expires.
     #
     # @param timeout [Integer] seconds for client to wait in queue
+    # @param concurrency [Integer] override concurrent workers
     # @yieldreturn [...] response from synchronized block execution
     # @return [nil] redis blpop timeout
-    def synchronize(timeout: 0, &)
-      synchronize!(timeout:, &)
+    def synchronize(timeout: 0, concurrency: @concurrency, &)
+      synchronize!(timeout:, concurrency:, &)
     rescue QueueTimeoutError => _e
       nil
     end
@@ -90,14 +94,15 @@ module RedisSingleFile
     # when queue wait time expires.
     #
     # @param timeout [Integer] seconds for blpop to wait in queue
+    # @param concurrency [Integer] override concurrent workers
     # @yieldreturn [...] response from synchronized block execution
     # @raise [QueueTimeoutError] redis blpop timeout
-    def synchronize!(timeout: 0)
+    def synchronize!(timeout: 0, concurrency: @concurrency)
       return unless block_given?
 
       with_retry_protection do
-        prime_queue unless redis.getset(mutex_key, mutex_val)
-        raise QueueTimeoutError unless redis.blpop(queue_key, timeout:)
+        prime_queue(concurrency) unless redis.getset(mutex_key, mutex_val)
+        raise QueueTimeoutError  unless redis.blpop(queue_key, timeout:)
 
         redis.multi do
           redis.persist(mutex_key) # unexpire during execution
@@ -108,7 +113,7 @@ module RedisSingleFile
       yield
     ensure
       # always cycle the queue when exiting
-      unlock_queue if block_given?
+      unlock_queue(concurrency) if block_given?
     end
 
     private #===================================================================
@@ -119,20 +124,22 @@ module RedisSingleFile
       @expire_in ||= Configuration.expire_in
     end
 
-    def prime_queue
+    def prime_queue(concurrency)
       with_retry_protection do
         redis.multi do
-          redis.del(queue_key)        # remove existing queue
-          redis.lpush(queue_key, '1') # create and prime new queue
+          redis.del(queue_key) # remove existing queue
+          concurrency.times do # create and prime new queue
+            redis.lpush(queue_key, '1')
+          end
         end
       end
     end
 
-    def unlock_queue
+    def unlock_queue(concurrency)
       with_retry_protection do
         redis.multi do
-          # queue next client execution if queue is empty
-          redis.lpush(queue_key, '1') if redis.llen(queue_key) == 0
+          # queue next client execution if queue has space (concurrency)
+          redis.lpush(queue_key, '1') if redis.llen(queue_key) < concurrency
           redis.expire(mutex_key, expire_in) # set expiration for auto removal
           redis.expire(queue_key, expire_in) # set expiration for auto removal
         end

data/lib/redis_single_file/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RedisSingleFile
-  VERSION = '0.1.2'
+  VERSION = '0.1.3'
 end

data/test.rb

@@ -1,15 +1,17 @@
 #!/usr/bin/env ruby
 
 require 'pry'
+require 'securerandom'
 require 'redis_single_file'
 
-RUN_ID = 'same-same' #SecureRandom.uuid
+PORT = ENV['REDIS_PORT'] || 6379
+RUN_ID = SecureRandom.uuid
 
 ITERATIONS = (ARGV[0] || 10).to_i
 WORK_LOAD  = (ARGV[1] || 1).to_i
 TIMEOUT    = ITERATIONS * WORK_LOAD
 
-#semaphore = RedisSingleFile.new(name: RUN_ID, port: 30001)
+#semaphore = RedisSingleFile.new(name: RUN_ID, port: PORT)
 #semaphore.synchronize!(timeout: 10) do
 #  puts "Hello World!"
 #  sleep 1
@@ -19,7 +21,7 @@ TIMEOUT    = ITERATIONS * WORK_LOAD
 
 #10.times.map do
 #  fork do
-#    semaphore = RedisSingleFile.new(name: RUN_ID)
+#    semaphore = RedisSingleFile.new(name: RUN_ID, port: PORT)
 #    semaphore.synchronize!(timeout: TIMEOUT) do
 #      puts "Hello World!"
 #      sleep WORK_LOAD
@@ -35,7 +37,7 @@ TIMEOUT    = ITERATIONS * WORK_LOAD
 
 threads = ITERATIONS.times.map do
   thread = Thread.new do
-    semaphore = RedisSingleFile.new(name: RUN_ID, port: 30001)
+    semaphore = RedisSingleFile.new(name: RUN_ID, port: PORT)
     semaphore.synchronize(timeout: TIMEOUT) do
       puts "Hello World!"
       sleep WORK_LOAD

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: redis-single-file
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.3
 platform: ruby
 authors:
 - LifeBCE
-bindir: exe
+autorequire:
+bindir: bin
 cert_chain: []
-date: 2025-02-08 00:00:00.000000000 Z
+date: 2025-10-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: redis
@@ -46,6 +47,7 @@ extra_rdoc_files: []
 files:
 - ".rspec"
 - ".rubocop.yml"
+- ".ruby-version"
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
@@ -63,7 +65,10 @@ licenses:
 - MIT
 metadata:
   homepage_uri: https://github.com/lifeBCE/redis-single-file
-  rubygems_mfa_required: 'true'
+  allowed_push_host: https://rubygems.org
+  changelog_uri: https://github.com/lifeBCE/redis-single-file/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'false'
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -78,7 +83,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.3
+rubygems_version: 3.5.22
+signing_key:
 specification_version: 4
 summary: Distributed semaphore implementation with redis.
 test_files: []