msg-batcher 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ac80b44e3f48248b2355ee73c5ed6346a492f9f5749ba670fbc18310171535cc
+  data.tar.gz: 42537898648e2e953ebb3df19fec938db4cc8da487f5014569a4477a71c666ff
+SHA512:
+  metadata.gz: 8a478b76db6a65bb7a428e01d714a76486f7d1932328b0157da799f83fb05767cab488108ae7dd16b531110e99ea3b6d5dcae15e02bd667e6e9b52e27caea955
+  data.tar.gz: fade326da9e58081a4a8d89d8f05bd368995556c97a12a805f38802974cbe481a3c54a597c1cf23764bd476463269f5b9bd41c62ea6b0d5c58829763704494bc

data/README.md

@@ -0,0 +1,73 @@
+A Ruby library that facilitates thread-safe batch processing of 
+messages. In certain situations, processing multiple messages in batch 
+is more efficient than handling them one by one.
+
+Consider a scenario where code receives events at random intervals and 
+must notify an external HTTP service about these events. The straightforward 
+approach is to issue an HTTP request with the details of each event as it is received. However, if events occur frequently, this method can lead to significant time spent on network latency. A more efficient approach is to aggregate events and send them in a single batched HTTP request.
+
+This library is designed to handle exactly that. Events are pushed into 
+the class instance, and a callback with batched data is triggered under 
+one of two conditions:
+
+* The number of messages in the batch reaches the specified maximum.
+* The batch is not yet complete, but the maximum idle time has elapsed.
+
+The latter condition is crucial for scenarios like the following: 
+suppose you've set up a *batcher* to fire after receiving 10 messages, 
+but only 9 messages are received, and no new messages are forthcoming. 
+In this case, the callback with 9 messages will fire after the 
+maximum idle time has passed.
+
+## Usage
+The following code creates a *batcher* with a maximum capacity of 10 
+messages per batch and a maximum idle time of 3 seconds. The callback 
+block simply prints the timestamp, batch size, and content.
+```
+require 'msg-batcher'
+
+batcher = MsgBatcher.new 10, 3000 do |batch|
+  now = Time.now
+  timestamp = "#{now.min}:#{now.sec}"
+  puts "[#{timestamp}] size: #{batch.size} content: #{batch.inspect}"
+end
+
+29.times do |i|
+  batcher.push i
+end
+
+sleep 5
+batcher.kill
+```
+The output is:
+```
+[10:12] size: 10 content: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
+[10:12] size: 10 content: [10, 11, 12, 13, 14, 15, 16, 17, 18, 19]
+[10:15] size: 9 content: [20, 21, 22, 23, 24, 25, 26, 27, 28]
+```
+As you can see, the first two batches, each of size 10, were created immediately, while the last incomplete batch 
+took 3 seconds to be created.
+
+Finally, it's a good idea to call the `#kill` method when you no longer need the *batcher*. 
+This method terminates the timer thread that was created during the 
+*batcher*'s initialization.
+
+## Thread-safety
+The `#push` method is thread-safe. 
+
+## Installation
+### Bundler
+Add this line to your application's Gemfile:
+```
+gem 'msg-batcher'
+```
+And then execute:
+```
+$ bundle install
+```
+### Standalone
+Or install it yourself as:
+```
+gem install msg-batcher
+```
+

data/lib/msg-batcher.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+# Important!:
+# If release method is called by timer thread, all other pushes will wait until release callback is finished by
+# timer thread. If release is issued by pushers, the release callback would be ran by last pushing thread
+# but other push threads would not wait for it to finish (which is good).
+
+
+class MsgBatcher
+  DEBUG = false
+
+  class Error < StandardError; end
+
+  def initialize(max_length, max_time_msecs, on_error=nil, &block)
+    @max_length = max_length
+    @max_time_msecs = max_time_msecs
+    @on_error = on_error
+    @on_error ||= lambda { |ex| raise ex }
+    @block = block
+
+    @closed = false
+
+    @storage = []
+    @m = Mutex.new
+    @m2 = Mutex.new # used besides @m mutex. Used because of timer thread.
+
+    @timer_start_cv = ConditionVariable.new
+    @timer_started_cv = ConditionVariable.new
+    @timer_full_cycle_cv = ConditionVariable.new
+    @timer_release_cv = ConditionVariable.new
+
+
+    # It is important that push invocation start after full completion of this method.
+    # So initialize instance of this class first and only then start pushing.
+    start_timer
+  end
+
+  def kill
+    @closed = true
+    @timer_thread.exit
+  end
+
+  # Thread-safe
+  # @raise [Error] when invoked when batcher has been closed
+  def push(entry)
+    raise Error, "Batcher is closed - cannot push" if @closed
+
+    @m.lock
+    @m2.lock
+
+    # Start timer
+    # Timer thread must be in TT1 position
+    if @storage.empty?
+      @timer_start_cv.signal
+      @timer_started_cv.wait @m2 # waiting for timer thread to be in position TT2
+    end
+
+    @storage.push entry
+    # curr_size = @storage.inject(0) { |sum, e| s}
+    if @storage.size == @max_length
+      # unlocks @m inside release method
+      release
+    else
+      @m2.unlock
+      @m.unlock
+    end
+  end
+
+  private
+
+  def dputs(str)
+    puts str if DEBUG
+  end
+
+  def release(from_push=true)
+    # inside @m lock
+    temp = @storage
+    @storage = []
+
+    @already_released = true
+    dputs "kill timer"
+    @timer_release_cv.signal # informing timer that release is happening
+
+    # Now interesting happens
+    # We are releasing @m2 lock and waiting for @timer_full_cycle_cv
+    # No other thread but timer thread would acquire @m2 lock, as other threads that are pushing
+    # are locked on @m.
+    # So as @m2 is acquired by timer thread, it starts new loop cycle and signals @timer_full_cycle_cv
+    # So this release method stops waiting and tries to lock @m2 again. But it cannot until timer
+    # thread releases it. It releases it on line @timer_start_cv.wait @m2.
+    # So now we can be sure that timer is at the beginning, ready to wait for @timer_start_cv signal.
+
+    if from_push
+      dputs "--------before wait m2"
+      @timer_full_cycle_cv.wait @m2
+      @m2.unlock
+      dputs "-----22222"
+      @m.unlock
+      dputs "---- unlock all"
+    end
+
+    begin
+      @block.call temp
+    rescue
+      @on_error.call $!
+    end
+
+  end
+
+  def start_timer
+    @m2.lock
+
+    @timer_thread = Thread.new do
+      @m2.lock
+      while true
+        @already_released = false
+        # informing release that timer is at the beginning
+        @timer_full_cycle_cv.signal
+        dputs "sdlkfjsd"
+
+
+
+        # Position: TT1
+        # Wait for invocation from push
+        # Each release invocation finishes when timer thread are below (waiting for @timer_start_cv)
+
+        dputs "TT1"
+        @timer_start_cv.wait @m2
+        dputs "TT1 after wait"
+        @timer_started_cv.signal
+
+        dputs "TT2"
+        # then wait either time to elapse or signal that data has been released
+        @timer_release_cv.wait @m2, @max_time_msecs / 1000.0
+
+        dputs "timer end #{@m2.owned?}"
+
+        # @m2 is locked here!
+
+        unless @already_released
+          dputs "timer's release"
+          release(false)
+        end
+      end
+    end
+    # wait for timer to be in waiting state
+    @timer_full_cycle_cv.wait @m2
+    @m2.unlock
+  end
+end

metadata

@@ -0,0 +1,46 @@
+--- !ruby/object:Gem::Specification
+name: msg-batcher
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- ertygiq
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2023-11-10 00:00:00.000000000 Z
+dependencies: []
+description: A Ruby library that facilitates thread-safe batch processing of messages.
+  In certain situations, processing multiple messages in batch is more efficient than
+  handling them one by one.
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/msg-batcher.rb
+homepage: https://github.com/ertygiq/msg-batcher
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.10
+signing_key:
+specification_version: 4
+summary: A Ruby Library for Thread-Safe Batch Processing of Events
+test_files: []