ractor-pipeline 0.2.0

data/examples/perf.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+# Performance demos of Ractor::Pipeline. Self-contained (synthetic data).
+#
+#   ruby -I lib examples/perf.rb
+#
+# Note: speedup ceilings depend heavily on the machine (P/E core mix,
+# all-core clock drop, etc.), and allocation-heavy stage blocks scale worse
+# than pure computation.
+
+Warning[:experimental] = false # suppress "Ractor API is experimental"
+
+require "ractor/pipeline"
+
+include Ractor::Pipeline
+
+def section(title)
+  puts
+  puts "== #{title}"
+  yield
+end
+
+def bench
+  t = Time.now
+  result = yield
+  [result, Time.now - t]
+end
+
+def report(label, dt, base = nil)
+  if base
+    printf "  %-36s %8.3fs  (x%.2f)\n", label, dt, base / dt
+  else
+    printf "  %-36s %8.3fs\n", label, dt
+  end
+end
+
+def fib(n) = n < 2 ? n : fib(n - 1) + fib(n - 2)
+
+section "CPU-bound scaling: 16 x fib(30), pipe(lanes: n)" do
+  items = 16
+
+  expected, base = bench{ (1..items).sum{ fib(30) } }
+  report "serial", base
+
+  [1, 2, 4, 8, 16].each do |n|
+    result, dt = bench do
+      stream(1..items).
+        pipe(lanes: n){ fib(30) }.
+        reduce(0){ |acc, v| acc + v }
+    end
+    raise "mismatch" unless result == expected
+    report "pipe(lanes: #{n})", dt, base
+  end
+end
+
+# Synthetic corpus for the text-processing demos.
+WORDS = %w[Ractor pipeline port stream lane stage worker copy share value].freeze
+
+def make_corpus(docs, lines_per_doc)
+  rng = Random.new(42)
+  Array.new(docs) do
+    Array.new(lines_per_doc) do
+      Array.new(8){ WORDS[rng.rand(WORDS.size)] }.join(" ")
+    end
+  end
+end
+
+def word_tally(lines)
+  tally = Hash.new(0)
+  lines.each do |line|
+    line.scan(/\w+/){ |w| tally[w] += 1 }
+  end
+  tally
+end
+
+section "map-reduce: word ranking, 1 document = 1 message" do
+  corpus = make_corpus(160, 2_000)
+
+  serial_top, base = bench do
+    corpus.map{ word_tally(it) }.
+          reduce(Hash.new(0)){ |acc, t| t.each{ |w, n| acc[w] += n }; acc }.
+          max_by(3){ |_, n| n }
+  end
+  report "serial (#{corpus.size} docs)", base
+
+  parallel_top, dt = bench do
+    stream(corpus).
+      pipe(lanes: 8){ word_tally(it) }.
+      reduce(Hash.new(0)){ |acc, t| t.each{ |w, n| acc[w] += n }; acc }.
+      max_by(3){ |_, n| n }
+  end
+  report "pipe(lanes: 8) + reduce", dt, base
+
+  raise "mismatch" unless serial_top == parallel_top
+  puts "  top words: " + serial_top.map{ |w, n| "#{w}(#{n})" }.join(", ")
+end
+
+MW, MH, MITER = 78, 48, 3000
+
+# Allocation-light row computation: allocation-heavy stage blocks scale
+# worse across Ractors than pure computation.
+def mandel_row(y)
+  ci = -1.0 + 2.0 * y / MH
+  row = String.new(capacity: MW)
+  x = 0
+  while x < MW
+    cr = -2.2 + 3.2 * x / MW
+    zr = zi = 0.0
+    n = 0
+    while n < MITER && zr * zr + zi * zi < 4.0
+      zr, zi = zr * zr - zi * zi + cr, 2 * zr * zi + ci
+      n += 1
+    end
+    row << (n == MITER ? "*" : " ")
+    x += 1
+  end
+  row
+end
+
+section "mandelbrot: rows in parallel, reassembled by row index" do
+  serial_pic, base = bench{ (0...MH).map{ mandel_row(it) } }
+  report "serial (#{MW}x#{MH}, iter=#{MITER})", base
+
+  # lanes: 8 is unordered, so carry the row index and reassemble.
+  parallel_pic, dt = bench do
+    stream(0...MH).
+      pipe(lanes: 8){ [it, mandel_row(it)] }.
+      reduce(Array.new(MH)){ |acc, (y, row)| acc[y] = row; acc }
+  end
+  report "pipe(lanes: 8)", dt, base
+
+  raise "mismatch" unless serial_pic == parallel_pic
+  puts parallel_pic.map{ |row| "  |#{row}|" }
+end
+
+section "granularity: per-line vs per-chunk messages" do
+  # Fine-grained messages (1 line = 1 message) are dominated by
+  # copy/communication cost; chunking restores the speedup.
+  lines = make_corpus(1, 20_000).first
+
+  serial_count, base = bench{ lines.count{ it.include?("Ractor") } }
+  report "serial (#{lines.size} lines)", base
+
+  line_count, dt = bench do
+    stream(lines).
+      filter_pipe(lanes: 4){ it.include?("Ractor") }.
+      count
+  end
+  report "per-line filter_pipe(lanes: 4)", dt, base
+
+  chunk_count, dt = bench do
+    stream(lines.each_slice(1000)).
+      pipe(lanes: 4){ it.count{ |line| line.include?("Ractor") } }.
+      reduce(0){ |acc, n| acc + n }
+  end
+  report "1000-line chunks, pipe(lanes: 4)", dt, base
+
+  batch_count, dt = bench do
+    stream(lines, batch: 1000).
+      filter_pipe(lanes: 4){ it.include?("Ractor") }.
+      count
+  end
+  report "batch: 1000 (transparent)", dt, base
+
+  raise "mismatch" unless serial_count == line_count && serial_count == chunk_count && serial_count == batch_count
+  puts "  matching lines: #{serial_count}"
+end
+
+def busy(n) = (i = 0; i += 1 while i < n; i)
+
+section "load balancing: one heavy element among light ones (lanes: 4)" do
+  # Demand-driven distribution: no new work is assigned to the worker
+  # that is stuck on the heavy element.
+  jobs = [40_000_000] + [4_000_000] * 31
+
+  _, base = bench{ jobs.each{ busy(it) } }
+  report "serial", base
+
+  _, dt = bench{ stream(jobs).pipe(lanes: 4){ busy(it) }.each{} }
+  report "pipe(lanes: 4)", dt, base
+end
+
+puts
+puts "done."

data/examples/readme_bench.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+# Collects the numbers quoted in README (min of 3 runs each) and prints
+# them as a markdown table.
+#
+#   ruby -I lib examples/readme_bench.rb
+
+Warning[:experimental] = false
+
+require "ractor/pipeline"
+require "json"
+
+include Ractor::Pipeline
+
+LANES = [2, 4, 8, 16].freeze
+
+def fib(n) = n < 2 ? n : fib(n - 1) + fib(n - 2)
+def busy(n) = (i = 0; i += 1 while i < n; i)
+
+def best(times = 5)
+  times.times.map { t = Time.now; yield; Time.now - t }.min
+end
+
+MW, MH, MITER = 78, 48, 3000
+
+def mandel_row(y)
+  ci = -1.0 + 2.0 * y / MH
+  row = String.new(capacity: MW)
+  x = 0
+  while x < MW
+    cr = -2.2 + 3.2 * x / MW
+    zr = zi = 0.0
+    n = 0
+    while n < MITER && zr * zr + zi * zi < 4.0
+      zr, zi = zr * zr - zi * zi + cr, 2 * zr * zi + ci
+      n += 1
+    end
+    row << (n == MITER ? "*" : " ")
+    x += 1
+  end
+  row
+end
+
+def agg(lines)
+  st = {}
+  lines.each do |l|
+    r = JSON.parse(l)
+    s = (st[r["path"]] ||= [0, 0, 0.0])
+    s[0] += 1
+    s[1] += 1 if r["status"] >= 500
+    s[2] += r["ms"]
+  end
+  st
+end
+
+puts RUBY_DESCRIPTION
+
+rows = []
+
+# 1. CPU-bound: 32 x fib(28)
+items = 32
+expected = (1..items).sum{ fib(28) }
+base = best{ raise unless (1..items).sum{ fib(28) } == expected }
+speedups = LANES.map do |n|
+  dt = best{ raise unless stream(1..items).pipe(lanes: n){ fib(28) }.reduce(0){ |a, v| a + v } == expected }
+  base / dt
+end
+rows << ["fib(28) x 32 (uniform)", base, speedups]
+
+# 2. skewed load: 1 heavy + 31 light
+jobs = [40_000_000] + [4_000_000] * 31
+base = best{ jobs.each{ busy(it) } }
+speedups = LANES.map do |n|
+  dt = best{ stream(jobs).pipe(lanes: n){ busy(it) }.each{} }
+  base / dt
+end
+rows << ["skewed load (1 heavy + 31 light)", base, speedups]
+
+# 3. mandelbrot rows (uneven cost, ordered reassembly)
+base = best{ (0...MH).map{ mandel_row(it) } }
+speedups = LANES.map do |n|
+  dt = best{ stream(0...MH).pipe(lanes: n){ [it, mandel_row(it)] }.reduce(Array.new(MH)){ |a, (y, r)| a[y] = r; a } }
+  base / dt
+end
+rows << ["mandelbrot (48 rows, uneven)", base, speedups]
+
+# 4. JSONL aggregation (allocation-bound), chunk-aggregate style
+rng = Random.new(42)
+paths = ["/", "/api/users", "/api/items", "/api/search", "/login", "/assets/app.js"]
+lines = Array.new(400_000) do
+  %({"path":"#{paths[rng.rand(paths.size)]}","status":#{rng.rand(100) < 3 ? 500 : 200},"ms":#{(rng.rand * 300).round(1)}})
+end
+chunks = lines.each_slice(1000).to_a
+base = best{ chunks.each{ agg(it) } }
+speedups = LANES.map do |n|
+  dt = best do
+    stream(chunks).
+      pipe(lanes: n){ agg(it) }.
+      reduce({}){ |a, st| st.each{ |k, (q, e, m)| x = (a[k] ||= [0, 0, 0.0]); x[0] += q; x[1] += e; x[2] += m }; a }
+  end
+  base / dt
+end
+rows << ["JSONL aggregation (400k lines, alloc-bound)", base, speedups]
+
+puts
+puts "| workload (serial time) | " + LANES.map{ "lanes #{it}" }.join(" | ") + " |"
+puts "|---|" + LANES.map{ "---" }.join("|") + "|"
+rows.each do |name, base, speedups|
+  puts "| #{name} (#{"%.2fs" % base}) | " + speedups.map{ "x%.2f" % it }.join(" | ") + " |"
+end
+
+# 5. granularity (per-line vs batch)
+gl = lines.first(100_000)
+base = best{ gl.count{ it.include?(%("status":500)) } }
+per_line = best{ stream(gl).filter_pipe(lanes: 4){ it.include?(%("status":500)) }.count }
+batched  = best{ stream(gl, batch: 1000).filter_pipe(lanes: 4){ it.include?(%("status":500)) }.count }
+puts
+printf "granularity: serial %.4fs / per-line %.3fs / batch1000 %.4fs\n", base, per_line, batched
+
+# 6. throttling
+class CountingSource
+  attr_reader :n
+
+  def initialize = @n = 0
+  def each = loop{ yield (@n += 1) }
+end
+cs = CountingSource.new
+stream(cs).pipe(lanes: 2){ it }.first(3)
+printf "throttle: source reads = %d (first(3), infinite source)\n", cs.n

data/examples/vs_parallel.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+# Compare Ractor::Pipeline with the parallel gem (process/thread based)
+# on the map-shaped workloads from README.
+#
+#   gem install parallel
+#   ruby -I lib examples/vs_parallel.rb
+#
+# Note the models differ: Parallel.map is a data-parallel map over a
+# ready-made collection (fork/IPC per job set); Ractor::Pipeline is an
+# in-process streaming topology. This compares only the overlap.
+
+Warning[:experimental] = false
+
+require "ractor/pipeline"
+require "json"
+begin
+  require "parallel"
+rescue LoadError
+  abort "parallel gem not installed (gem install parallel)"
+end
+
+include Ractor::Pipeline
+
+def fib(n) = n < 2 ? n : fib(n - 1) + fib(n - 2)
+def busy(n) = (i = 0; i += 1 while i < n; i)
+
+def best(times = 3)
+  times.times.map { t = Time.now; yield; Time.now - t }.min
+end
+
+def row(label, base, dt)
+  printf "  %-32s %8.3fs  (x%.2f)\n", label, dt, base / dt
+end
+
+puts RUBY_DESCRIPTION
+puts "parallel #{Parallel::VERSION}"
+
+section = ->(title){ puts; puts "== #{title}" }
+
+# -- 1. uniform CPU: 32 x fib(28) ----------------------------------------
+section.call "uniform CPU: 32 x fib(28)"
+items = (1..32).to_a
+expected = items.sum{ fib(28) }
+base = best{ raise unless items.sum{ fib(28) } == expected }
+printf "  %-32s %8.3fs\n", "serial", base
+[8, 16].each do |n|
+  dt = best{ raise unless stream(items).pipe(lanes: n){ fib(28) }.reduce(0){ |a, v| a + v } == expected }
+  row "Ractor::Pipeline lanes: #{n}", base, dt
+end
+[8, 16].each do |n|
+  dt = best{ raise unless Parallel.map(items, in_processes: n){ fib(28) }.sum == expected }
+  row "Parallel in_processes: #{n}", base, dt
+end
+dt = best{ raise unless Parallel.map(items, in_threads: 8){ fib(28) }.sum == expected }
+row "Parallel in_threads: 8 (GVL)", base, dt
+
+# -- 2. skewed load: 1 heavy + 31 light ----------------------------------
+section.call "skewed load: 1 heavy (~0.3s) + 31 light (~30ms)"
+jobs = [40_000_000] + [4_000_000] * 31
+base = best{ jobs.each{ busy(it) } }
+printf "  %-32s %8.3fs\n", "serial", base
+dt = best{ stream(jobs).pipe(lanes: 4){ busy(it) }.each{} }
+row "Ractor::Pipeline lanes: 4", base, dt
+dt = best{ Parallel.each(jobs, in_processes: 4){ busy(it) } }
+row "Parallel in_processes: 4", base, dt
+
+# -- 3. JSONL aggregation (allocation-bound) ------------------------------
+section.call "JSONL aggregation: 400k lines, 1000-line chunks"
+rng = Random.new(42)
+paths = ["/", "/api/users", "/api/items", "/api/search", "/login", "/assets/app.js"]
+lines = Array.new(400_000) do
+  %({"path":"#{paths[rng.rand(paths.size)]}","status":#{rng.rand(100) < 3 ? 500 : 200},"ms":#{(rng.rand * 300).round(1)}})
+end
+chunks = lines.each_slice(1000).to_a
+
+def agg(lines)
+  st = {}
+  lines.each do |l|
+    r = JSON.parse(l)
+    s = (st[r["path"]] ||= [0, 0, 0.0])
+    s[0] += 1
+    s[1] += 1 if r["status"] >= 500
+    s[2] += r["ms"]
+  end
+  st
+end
+
+def merge_all(stats_list)
+  stats_list.each_with_object({}) do |st, a|
+    st.each{ |k, (q, e, m)| x = (a[k] ||= [0, 0, 0.0]); x[0] += q; x[1] += e; x[2] += m }
+  end
+end
+
+base = best{ merge_all(chunks.map{ agg(it) }) }
+printf "  %-32s %8.3fs\n", "serial", base
+dt = best do
+  stream(chunks).
+    pipe(lanes: 8){ agg(it) }.
+    reduce({}){ |a, st| st.each{ |k, (q, e, m)| x = (a[k] ||= [0, 0, 0.0]); x[0] += q; x[1] += e; x[2] += m }; a }
+end
+row "Ractor::Pipeline lanes: 8", base, dt
+dt = best{ merge_all(Parallel.map(chunks, in_processes: 8){ agg(it) }) }
+row "Parallel in_processes: 8", base, dt
+dt = best{ merge_all(Parallel.map(chunks, in_threads: 8){ agg(it) }) }
+row "Parallel in_threads: 8 (GVL)", base, dt
+
+# -- 4. per-job overhead: tiny jobs ---------------------------------------
+section.call "per-job overhead: 10k trivial jobs (it + 1)"
+tiny = (1..10_000).to_a
+base = best{ tiny.sum{ it + 1 } }
+printf "  %-32s %8.3fs\n", "serial", base
+dt = best{ raise unless stream(tiny, batch: 500).pipe(lanes: 4){ it + 1 }.count == 10_000 }
+row "Ractor::Pipeline lanes:4 batch:500", base, dt
+dt = best{ raise unless Parallel.map(tiny, in_processes: 4){ it + 1 }.size == 10_000 }
+row "Parallel in_processes: 4", base, dt

data/lib/ractor/pipeline/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+class Ractor
+  module Pipeline
+    VERSION = "0.2.0"
+  end
+end