ractor_mgr 1.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b0ce6bb9fff5fc074a6fef8418cf1ebd0c68ecc5b93b0fb3879303d36136e80f
+  data.tar.gz: b5fc847cee9599d221ddd0f20f88bc6fff55655b05dd19659f4d212c653f1089
+SHA512:
+  metadata.gz: accd93b787253f2a77a9c385b51c36ee62e1424c12995e01a38d6228059a1667f5b799e65444bc854f87e5cd7e50fa31752a77485ade87a224312c071a777304
+  data.tar.gz: 2f807db78d0f1fa0a3095aea97870bf6cb66e814fb99de6b1ca9b7fcc081df0c9caa7406dc7743eabb26326537a34f0849dff4856b352626715068fd07829d5c

data/lib/ractor_mgr.rb

@@ -0,0 +1,150 @@
+require 'tiny_eta'
+
+# RactorMgr is a job queue combined with a monitor for a list of Ractors. the
+# job of a RactorMgr is:
+#
+# 1. store the list of jobs to be completed
+# 2. feed the worker Ractors with jobs
+# 3. when a worker completes a job give it another job (if there's more work to
+#   do)
+# 4. generally monitor the workers to see how many jobs have been completed, as
+#   well as providing status of current Ractors (:idle, :working)
+#
+# you create your own worker Ractors, and the RactorMgr takes care of making
+# sure those workers stay as busy as possible.
+#
+# Usage:
+#
+#   # make some workers
+#   workers = 5.times.map do
+#     Ractor.new do
+#       loop do
+#         Ractor.yield(Ractor.receive * 2)
+#       end
+#     end
+#   end
+#
+#   # create some jobs
+#   jobs = [1] * 1_000_000; nil
+#
+#   # feed the jobs to the workers via the RactorMgr
+#   rm = RactorMgr.new(
+#     jobs: jobs,
+#     workers: workers
+#   )
+#   rm.join             # optional, if you want to wait
+#
+# NOTE on Ractor interface: the RactorMgr expects to send a worker a job, and
+# then be able to call #take on that Ractor. it is assumed that as soon as the
+# worker returns a value from #take that that worker is available for another
+# job. this means you should implement your Ractors as an infinite loop where:
+# - the Ractor takes in a job definition
+# - the Ractor yields some value when the job is done
+#
+# ... thus the worker Ractor will continue accepting jobs as long as the
+# RactorMgr keeps feeding it jobs.
+#
+# WARN: while the RactorMgr is running the job list should not be altered.
+#
+# status:
+#   - :idle if the RactorMgr is finished
+#   - :running if the RactorMgr is running
+# join: calls #join on the internal Thread, blocking until all jobs have
+#   finished
+class RactorMgr
+  attr_reader :status,
+              :results
+
+  def initialize(jobs:, workers:)
+    @status = :idle
+    @jobs = jobs
+    @workers = workers
+    @job_index = 0
+    @jobs_finished = 0
+    @results = []
+
+    ##
+    # start work
+    @start_time = Time.now
+
+    # initial job fill
+    @workers.each do |w|
+      w.send(@jobs[@job_index])
+      @job_index += 1
+    end
+
+    # Thread for feeding workers
+    @mgr_thread = Thread.new do
+      @status = :running
+
+      loop do
+        break if @job_index == @jobs.length
+
+        w, r = Ractor.select(*@workers)
+        @results << r
+        @jobs_finished += 1
+        w.send(@jobs[@job_index])
+        @job_index += 1
+      end
+
+      @workers.map do |w|
+        @results << w.take
+        @jobs_finished += 1
+      end
+
+      @status = :idle
+    end
+  end
+
+  def done?
+    jobs_finished == @jobs.length
+  end
+
+  # the total number of jobs that will be run
+  def jobs_total
+    @jobs.length
+  end
+
+  # the number of jobs that have finished
+  def jobs_finished
+    @jobs_finished
+  end
+
+  # the number of jobs currently running
+  def jobs_running
+    @job_index - @jobs_finished
+  end
+
+  # the number of jobs remaining
+  def jobs_remaining
+    jobs_total - jobs_finished
+  end
+
+  # percentage complete as a Float in the range of 0.0..1.0
+  def percent_complete_f(digits=0)
+    (jobs_finished / jobs_total.to_f)
+  end
+
+  # percentage complete (a floating point number between 0.0..100.0)
+  def percent_complete_s(digits=0)
+    ((jobs_finished / jobs_total.to_f) * 100).round(digits)
+  end
+
+  # returns a TinyEta string for ETA time
+  #
+  # see: https://github.com/jefflunt/tiny_eta
+  def eta
+    TinyEta.eta(Time.now - @start_time, percent_complete_f)
+  end
+
+  # just like Thread#join, blocks until all jobs are complete
+  def join
+    @mgr_thread.join
+    nil
+  end
+
+  # out-of-the-box monitoring
+  def to_s
+    "RactorMgr #{jobs_running} running, progress: #{jobs_finished}/#{jobs_total} #{percent_complete_s(1)}% (ETA #{eta})"
+  end
+end

metadata

@@ -0,0 +1,58 @@
+--- !ruby/object:Gem::Specification
+name: ractor_mgr
+version: !ruby/object:Gem::Version
+  version: 1.2.0
+platform: ruby
+authors:
+- Jeff Lunt
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2023-01-09 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: tiny_eta
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.0.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.0.1
+description: a job queue and monitor for Ractors
+email: jefflunt@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/ractor_mgr.rb
+homepage: https://github.com/jefflunt/ractor_mgr
+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.1
+signing_key:
+specification_version: 4
+summary: want to have a job queue for a list of identical Ractors, and have a little
+  manager that feeds them work as they become availble? then this library is for you
+test_files: []