fiber_stream 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 504a7400182e09bb66a5a07981bbb2cfab350397d09c23ea036e856f29afe1d2
-  data.tar.gz: 67c7ddead203d42bf869dcba7d840e7d09514d888b90b84b77d97a8cedc19e1e
+  metadata.gz: b729811e8b39efdfa4203d0e6167709105d524ec098f018fdc120986c0b73b14
+  data.tar.gz: 162a3bf8a893fe13ae994ec77c8a2df7c8c44f9c5ab11895ee3b3b0ddfe31192
 SHA512:
-  metadata.gz: f9c8d80faca53d9c6e059326bc9e6ffe7497aa8a6cbcad3b42eefe0ef3a3d8d29f08a3afbec8fc2b02b2064a745bb00ea644e816f913aa624a2ad11f1b087b99
-  data.tar.gz: 9e6f87b74cbfe2ccaaa9c32990f9786af3ee3ee3d7f2c3dd605a88efa8f3e436e4a1051d65c1eb1664859af212a2fecc82c66dc585cf9333dd799917c2a9035e
+  metadata.gz: edd97c825b99250b4169443764cb384330fd8c3176e4086c6a1a93834c67fd288b5f0583fce50b68277936de1fe9f303162063ff182523beed3af935b568d2e0
+  data.tar.gz: dcb33221af26887b3a914f428c0b58e6d8ecf8511c384c0282b889e8b74b1d17fecd6e5ba86b465dfc466252bef0bb960f9bcfd66229c9e6ccd0b12cf7b3a768

data/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## Unreleased
+
+## 0.6.0 - 2026-07-27
+
+### Added
+
+- `Flow.ractor_unordered_map(workers:)` and `Source#ractor_unordered_map` for
+  Ractor-backed CPU-bound mapping that emits results in completion order.
+- `Sink.find { |element| ... }` for predicate-based terminal search with
+  early upstream completion.
+- `Sink.any? { |element| ... }` for predicate-based existential checks with
+  early upstream completion.
+- `Sink.all? { |element| ... }` for predicate-based universal checks with
+  early upstream completion.
+- Example and benchmark coverage for unordered Ractor-backed mapping.
+
+### Changed
+
+- Added a rate-limiting tutorial covering local, shared in-process,
+  database-backed, and Redis-backed quota policies.
+- Centralized the local and release verification gates and added documentation
+  index validation.
+
 ## 0.5.0 - 2026-06-21
 
 ### Added

data/README.md

@@ -37,8 +37,9 @@ Implemented capabilities:
   observation, one-to-many expansion, limiting, predicate-based limiting and
   dropping, fixed-prefix dropping, fixed-size grouping, line splitting,
   buffering, async boundaries, throttling, ordered and unordered parallel
-  mapping, and ordered Ractor-backed mapping
-- array, first-element, count, fold, foreach, and IO sinks
+  mapping, and ordered and unordered Ractor-backed mapping
+- array, first-element, predicate search/check, count, fold, foreach, and IO
+  sinks
 - reusable flow composition and runnable pipelines
 - foreground and scheduler-backed background pipeline execution
 - public RBS signatures
@@ -309,8 +310,10 @@ responses =
 responses
 ```
 
-Use `ractor_map` for ordered CPU-bound mapping in Ractor workers. The mapper
-must be shareable, usually by creating it with `Ractor.shareable_proc`.
+Use `ractor_map` for ordered CPU-bound mapping in Ractor workers, and
+`ractor_unordered_map` when later completed CPU-bound results should not wait
+behind a slower earlier input. The mapper must be shareable, usually by
+creating it with `Ractor.shareable_proc`.
 
 ```ruby
 require "digest"
@@ -343,6 +346,19 @@ digests =
 or `output_transfer: :move` only when the moved object will not be reused by
 the sender.
 
+`ractor_unordered_map` uses the same Ractor transfer and shareability rules,
+but emits values in worker completion order:
+
+```ruby
+fastest_first =
+  FiberStream::Source.each(records)
+    .ractor_unordered_map(workers: 2, input_transfer: :move, &HASH_RECORD)
+    .run_with(FiberStream::Sink.to_a)
+
+# Results are in completion order, not necessarily input order.
+fastest_first
+```
+
 ### Sinks
 
 A `Sink` consumes the stream and returns a materialized value.
@@ -361,6 +377,30 @@ FiberStream::Source.each([1, 2, 3])
 # => 3
 ```
 
+Use `Sink.find` when the stream should stop after the first matching element:
+
+```ruby
+FiberStream::Source.each([1, 2, 3, 4])
+  .run_with(FiberStream::Sink.find(&:even?))
+# => 2
+```
+
+Use `Sink.any?` when only the existence of a matching element matters:
+
+```ruby
+FiberStream::Source.each([1, 2, 3, 4])
+  .run_with(FiberStream::Sink.any?(&:even?))
+# => true
+```
+
+Use `Sink.all?` when every element must satisfy a predicate:
+
+```ruby
+FiberStream::Source.each([2, 4, 6])
+  .run_with(FiberStream::Sink.all?(&:even?))
+# => true
+```
+
 Use `Sink.foreach` when the terminal operation is a side effect and the stream
 values should not be accumulated:
 
@@ -575,6 +615,7 @@ Source convenience methods:
 - `Source#parallel_map(concurrency:) { |element| ... }`
 - `Source#parallel_unordered_map(concurrency:) { |element| ... }`
 - `Source#ractor_map(workers:, input_transfer: :copy, output_transfer: :copy) { |element| ... }`
+- `Source#ractor_unordered_map(workers:, input_transfer: :copy, output_transfer: :copy) { |element| ... }`
 - `Source#select { |element| ... }`
 - `Source#reject { |element| ... }`
 - `Source#take(count)`
@@ -602,6 +643,7 @@ Flows:
 - `FiberStream::Flow.parallel_map(concurrency:) { |element| ... }`
 - `FiberStream::Flow.parallel_unordered_map(concurrency:) { |element| ... }`
 - `FiberStream::Flow.ractor_map(workers:, input_transfer: :copy, output_transfer: :copy) { |element| ... }`
+- `FiberStream::Flow.ractor_unordered_map(workers:, input_transfer: :copy, output_transfer: :copy) { |element| ... }`
 - `FiberStream::Flow.select { |element| ... }`
 - `FiberStream::Flow.reject { |element| ... }`
 - `FiberStream::Flow.take(count)`
@@ -629,6 +671,9 @@ Sinks:
 
 - `FiberStream::Sink.to_a`
 - `FiberStream::Sink.first`
+- `FiberStream::Sink.find { |element| truthy_or_falsey }`
+- `FiberStream::Sink.any? { |element| truthy_or_falsey }`
+- `FiberStream::Sink.all? { |element| truthy_or_falsey }`
 - `FiberStream::Sink.count`
 - `FiberStream::Sink.fold(initial) { |accumulator, element| ... }`
 - `FiberStream::Sink.foreach { |element| ... }`
@@ -655,6 +700,7 @@ bundle exec ruby examples/file_copy.rb
 bundle exec ruby examples/backpressure_buffer.rb
 bundle exec ruby examples/background_execution.rb
 bundle exec ruby examples/ractor_map_hashing.rb
+bundle exec ruby examples/ractor_unordered_map_hashing.rb
 bundle exec ruby examples/ractor_producer_sources.rb
 bundle exec ruby examples/ractor_port_source.rb
 bundle exec ruby examples/ractor_merge_ports_and_map.rb
@@ -668,6 +714,9 @@ events so the difference between direct demand and bounded prefetch is visible.
 `examples/ractor_map_hashing.rb` demonstrates ordered Ractor-backed hashing
 with a shareable mapper proc and `input_transfer: :move`.
 
+`examples/ractor_unordered_map_hashing.rb` demonstrates completion-order
+Ractor-backed hashing for uneven CPU-bound work.
+
 `examples/ractor_producer_sources.rb` demonstrates high-level owned producer
 Ractors with `Source.ractor_producer` and `Source.ractor_merge_producers`.
 
@@ -705,6 +754,14 @@ Install dependencies:
 bundle install
 ```
 
+Install website dependencies when building documentation locally:
+
+```sh
+cd website
+npm ci
+cd ..
+```
+
 Run the test suite:
 
 ```sh
@@ -729,6 +786,18 @@ Run all default checks:
 bundle exec rake
 ```
 
+Run the default local verification gate explicitly:
+
+```sh
+bundle exec rake verify
+```
+
+Run the full release-readiness gate, including the website build:
+
+```sh
+bundle exec rake verify:full
+```
+
 Build the gem:
 
 ```sh

data/examples/README.md

@@ -10,6 +10,7 @@ bundle exec ruby examples/file_copy.rb
 bundle exec ruby examples/backpressure_buffer.rb
 bundle exec ruby examples/background_execution.rb
 bundle exec ruby examples/ractor_map_hashing.rb
+bundle exec ruby examples/ractor_unordered_map_hashing.rb
 bundle exec ruby examples/ractor_port_source.rb
 bundle exec ruby examples/ractor_producer_sources.rb
 bundle exec ruby examples/ractor_merge_ports_and_map.rb
@@ -44,6 +45,10 @@ the foreground fiber keeps doing scheduler-managed work.
 `input_transfer: :move` because the input records are not reused after the
 pipeline runs.
 
+`ractor_unordered_map_hashing.rb` hashes independent payloads in Ractor workers
+and emits results as workers finish. It shows how a slower earlier input no
+longer holds back later completed CPU-bound work.
+
 `ractor_port_source.rb` demonstrates a producer Ractor connected to
 `Source.ractor_port`. The producer creates its acknowledgment port, waits for
 `RactorPort::Ack`, and sends one typed `RactorPort::Element` per downstream

data/examples/ractor_unordered_map_hashing.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+
+require "digest"
+require "fiber_stream"
+
+records = [
+  { name: "slow-alpha.bin", payload: +"A" * 160_000, rounds: 1_200 },
+  { name: "fast-bravo.bin", payload: +"B" * 120_000, rounds: 120 },
+  { name: "fast-charlie.bin", payload: +"C" * 140_000, rounds: 120 },
+  { name: "medium-delta.bin", payload: +"D" * 100_000, rounds: 450 }
+]
+
+HASH_RECORD =
+  Ractor.shareable_proc do |record|
+    payload = record.fetch(:payload)
+    digest = Digest::SHA256.hexdigest(payload)
+
+    record.fetch(:rounds).times do
+      digest = Digest::SHA256.hexdigest(digest)
+    end
+
+    {
+      name: record.fetch(:name),
+      bytes: payload.bytesize,
+      rounds: record.fetch(:rounds),
+      sha256: digest
+    }
+  end
+
+puts "Input order"
+records.each.with_index(1) do |record, index|
+  puts format(
+    "%<index>2d. %-16<name>s %4<rounds>d rounds",
+    index: index,
+    name: record.fetch(:name),
+    rounds: record.fetch(:rounds)
+  )
+end
+
+digests =
+  FiberStream::Source.each(records)
+    .ractor_unordered_map(workers: 2, input_transfer: :move, &HASH_RECORD)
+    .run_with(FiberStream::Sink.to_a)
+
+puts
+puts "Completion order"
+digests.each.with_index(1) do |digest, index|
+  puts format(
+    "%<index>2d. %-16<name>s %7<bytes>d bytes %4<rounds>d rounds  %<sha256>s",
+    index: index,
+    name: digest.fetch(:name),
+    bytes: digest.fetch(:bytes),
+    rounds: digest.fetch(:rounds),
+    sha256: digest.fetch(:sha256)
+  )
+end
+
+puts
+puts "Results are emitted as Ractor workers finish, not by input position."
+puts "input_transfer: :move is safe here because the input records are not reused."

data/lib/fiber_stream/flow.rb

@@ -111,6 +111,26 @@ module FiberStream
       new { |upstream| Pull.ractor_map(upstream, workers, input_transfer, output_transfer, block) }
     end
 
+    # Creates an unordered Ractor-backed mapping flow.
+    #
+    # The mapper runs inside worker ractors and must be shareable, typically
+    # created with `Ractor.shareable_proc`. Results are emitted in worker
+    # completion order, and at most `workers` upstream elements are pulled but
+    # not yet emitted. `input_transfer` and `output_transfer` must be `:copy`
+    # or `:move` and are passed to Ractor message sends for element and result
+    # transfer.
+    def self.ractor_unordered_map(workers:, input_transfer: :copy, output_transfer: :copy, &block)
+      raise ArgumentError, "missing block" unless block
+      raise TypeError, "workers must be an Integer" unless workers.is_a?(Integer)
+      raise ArgumentError, "workers must be positive" unless workers.positive?
+
+      Internal::RactorTransferPolicy.validate!(:input_transfer, input_transfer)
+      Internal::RactorTransferPolicy.validate!(:output_transfer, output_transfer)
+      raise TypeError, "block must be shareable" unless Ractor.shareable?(block)
+
+      new { |upstream| Pull.ractor_unordered_map(upstream, workers, input_transfer, output_transfer, block) }
+    end
+
     # Creates a filtering flow.
     #
     # The block is called for upstream elements until it returns a truthy value

data/lib/fiber_stream/pull/ractor_unordered_map_boundary.rb

@@ -0,0 +1,521 @@
+# frozen_string_literal: true
+
+module FiberStream
+  module Pull
+    # Unordered Ractor-backed worker boundary for
+    # `Flow.ractor_unordered_map`.
+    #
+    # Upstream is pulled by the downstream caller, while blocking waits for
+    # Ractor worker messages are isolated in a coordinator thread. Downstream
+    # emits worker results in completion order and admission stays bounded by
+    # the number of workers.
+    class RactorUnorderedMapBoundary
+      Job = ::Data.define(:sequence, :value)
+      Shutdown = ::Data.define
+      Ready = ::Data.define(:worker_id)
+      WorkerValue = ::Data.define(:worker_id, :sequence, :value)
+      WorkerFailure = ::Data.define(:worker_id, :sequence, :kind, :cause_class_name, :cause_message)
+      Stopped = ::Data.define(:worker_id)
+      ResultValue = ::Data.define(:sequence, :value)
+      ResultDone = ::Data.define
+      ResultCloseError = ::Data.define(:sequence, :error)
+      ResultError = ::Data.define(:sequence, :error)
+
+      private_constant :Job, :Shutdown, :Ready, :WorkerValue, :WorkerFailure, :Stopped
+      private_constant :ResultValue, :ResultDone, :ResultCloseError, :ResultError
+
+      def initialize(upstream, workers, input_transfer, output_transfer, transform)
+        @upstream = upstream
+        @workers_count = workers
+        @input_transfer = input_transfer
+        @output_transfer = output_transfer
+        @transform = transform
+        @result_port = nil
+        @ready_workers = Thread::SizedQueue.new(workers)
+        @results = Thread::SizedQueue.new(workers)
+        @workers = []
+        @active_sequences = {}
+        @worker_state_mutex = Mutex.new
+        @coordinator = nil
+        @next_sequence = 0
+        @outstanding_jobs = 0
+        @terminal_message = nil
+        @started = false
+        @closed = false
+        @done = false
+        @admission_closed = false
+        @worker_shutdown_sent = false
+        @upstream_closed = false
+        @upstream_close_error = nil
+      end
+
+      def next
+        return DONE if @closed || @done
+
+        start
+        next_message
+      end
+
+      def close
+        return if @closed
+
+        @closed = true
+        @done = true
+        close_error = close_upstream
+        close_admission(close_upstream: false)
+        close_ready_queue
+        close_result_queue
+        request_worker_shutdown
+        wait_for_workers
+        close_error ||= @upstream_close_error
+        raise close_error if close_error
+      end
+
+      private
+
+      def start
+        return if @started
+
+        @started = true
+        @result_port = Ractor::Port.new
+        @workers_count.times do |worker_id|
+          @workers << self.class.spawn_worker(
+            worker_id,
+            @result_port,
+            @transform,
+            @output_transfer
+          )
+        end
+        @coordinator = Thread.new { run_coordinator }
+      end
+
+      def next_message
+        return emit_terminal(@terminal_message) if terminal_ready?
+
+        ready = take_result(block: false)
+        return emit(ready) if ready
+
+        ready = fill_capacity
+        return emit(ready) if ready
+
+        return emit_terminal(@terminal_message) if terminal_ready?
+
+        message = take_result(block: true)
+        return complete unless message
+
+        emit(message)
+      end
+
+      def fill_capacity
+        return if @admission_closed
+
+        while @outstanding_jobs < @workers_count
+          ready = take_result(block: false)
+          return ready if ready
+
+          worker = take_ready_worker(block: @outstanding_jobs.zero? && @terminal_message.nil?)
+          break unless worker
+
+          message = pull_job_message
+          if message.is_a?(Job)
+            @outstanding_jobs += 1
+            break unless deliver_job(worker, message)
+          elsif upstream_failure?(message)
+            fail_with_error(message.sequence, message.error)
+          else
+            close_admission(close_upstream: false)
+            @terminal_message = message
+            break
+          end
+        end
+
+        nil
+      end
+
+      def pull_job_message
+        value = @upstream.next
+        return terminal_done_message if Pull.done?(value)
+
+        sequence = @next_sequence
+        @next_sequence += 1
+        Job.new(sequence, value)
+      rescue StandardError => error
+        close_upstream(record_error: false)
+        ResultError.new(sequence: @next_sequence, error:)
+      end
+
+      def terminal_done_message
+        close_error = close_upstream
+        if close_error
+          ResultCloseError.new(sequence: @next_sequence, error: close_error)
+        else
+          ResultDone.new
+        end
+      end
+
+      def deliver_job(worker, message)
+        sequence = message.sequence
+        track_worker_job(worker, sequence)
+
+        if @input_transfer == :move
+          worker.send(message, move: true)
+        else
+          worker.send(message)
+        end
+        true
+      rescue StandardError => error
+        clear_worker_job(worker)
+        deliver_result(ResultError.new(sequence:, error: build_ractor_map_error(sequence, :input_transfer, error)))
+        close_admission
+        request_worker_shutdown
+        false
+      end
+
+      def take_ready_worker(block:)
+        if block
+          loop do
+            worker = @ready_workers.pop
+            return worker if worker || @closed || @admission_closed || @ready_workers.closed?
+          end
+        else
+          @ready_workers.pop(true)
+        end
+      rescue ThreadError, ClosedQueueError
+        nil
+      end
+
+      def take_result(block:)
+        block ? @results.pop : @results.pop(true)
+      rescue ThreadError, ClosedQueueError
+        nil
+      end
+
+      def emit(message)
+        case message
+        in ResultValue[_sequence, value]
+          emit_value(value)
+        in ResultError[sequence:, error:]
+          fail_with_error(sequence, error)
+        end
+      end
+
+      def emit_value(value)
+        @outstanding_jobs -= 1 if @outstanding_jobs.positive?
+        value
+      end
+
+      def terminal_ready?
+        @terminal_message && @outstanding_jobs.zero?
+      end
+
+      def emit_terminal(message)
+        case message
+        in ResultDone
+          complete
+        in ResultCloseError[sequence:, error:]
+          fail_with_error(sequence, error, close_admission: false)
+        in ResultError[sequence:, error:]
+          fail_with_error(sequence, error, close_admission: false)
+        end
+      end
+
+      def upstream_failure?(message)
+        message.is_a?(ResultError)
+      end
+
+      def fail_with_error(_sequence, error, close_admission: true)
+        @done = true
+        close_admission() if close_admission
+        close_result_queue
+        request_worker_shutdown
+        if error.is_a?(RactorMapError) && error.original_cause
+          raise error, cause: error.original_cause
+        end
+
+        raise error
+      end
+
+      def complete
+        @done = true
+        request_worker_shutdown
+        DONE
+      end
+
+      def run_coordinator
+        stopped = 0
+        live_workers = @workers.dup
+
+        until stopped == @workers_count
+          selected, message = select_worker_message(live_workers)
+          if selected == :worker_remote_error
+            stopped += 1
+          elsif selected == @result_port
+            stopped += handle_worker_message(message, live_workers)
+          else
+            live_workers.delete(selected)
+            handle_worker_termination(selected)
+            stopped += 1
+          end
+        end
+      ensure
+        close_ready_queue
+        close_result_queue if @closed
+      end
+
+      def select_worker_message(live_workers)
+        Ractor.select(@result_port, *live_workers)
+      rescue Ractor::RemoteError => error
+        worker = remote_error_worker(error, live_workers) || failed_worker_for_remote_error(live_workers)
+        live_workers.delete(worker) if worker
+        handle_worker_remote_error(worker, error)
+        [:worker_remote_error, nil]
+      end
+
+      def remote_error_worker(error, live_workers)
+        return unless error.respond_to?(:ractor)
+
+        worker = error.ractor
+        live_workers.include?(worker) ? worker : nil
+      end
+
+      def failed_worker_for_remote_error(live_workers)
+        @worker_state_mutex.synchronize do
+          live_workers
+            .select { |worker| @active_sequences.key?(worker) }
+            .min_by { |worker| @active_sequences.fetch(worker) }
+        end || live_workers.first
+      end
+
+      def handle_worker_remote_error(worker, error)
+        sequence = worker ? clear_worker_job(worker) : nil
+        sequence ||= @next_sequence
+        return if @closed || @worker_shutdown_sent
+
+        deliver_worker_termination_error(worker, sequence, cause: error)
+      end
+
+      def handle_worker_message(message, live_workers)
+        case message
+        in Ready[worker_id]
+          deliver_ready_worker(worker_id)
+          0
+        in WorkerValue
+          handle_worker_value_message(message)
+          0
+        in WorkerFailure
+          handle_worker_error_message(message)
+          0
+        in Stopped
+          handle_worker_stopped_message(message, live_workers)
+        end
+      end
+
+      def handle_worker_value_message(message)
+        worker = worker_for_id(message.worker_id)
+
+        clear_worker_job(worker)
+        deliver_result(ResultValue.new(sequence: message.sequence, value: message.value))
+      end
+
+      def handle_worker_error_message(message)
+        worker = worker_for_id(message.worker_id)
+
+        clear_worker_job(worker)
+        deliver_result(normalize_worker_error_message(message))
+      end
+
+      def handle_worker_stopped_message(message, live_workers)
+        worker = worker_for_id(message.worker_id)
+        live_workers.delete(worker)
+        sequence = clear_worker_job(worker)
+        deliver_worker_termination_error(worker, sequence) if sequence && !@closed && !@worker_shutdown_sent
+        1
+      end
+
+      def handle_worker_termination(worker)
+        sequence = clear_worker_job(worker) || @next_sequence
+        return if @closed || @worker_shutdown_sent
+
+        deliver_worker_termination_error(worker, sequence)
+      end
+
+      def deliver_worker_termination_error(worker, sequence, cause: nil)
+        close_ready_queue
+        error =
+          RactorMapError.new(
+            sequence: sequence,
+            kind: :worker_termination,
+            cause_class_name: cause&.class&.name || worker.class.name,
+            cause_message: cause&.message || "worker terminated without a lifecycle message",
+            cause: cause
+          )
+
+        deliver_result(ResultError.new(sequence:, error:))
+      end
+
+      def deliver_ready_worker(worker_id)
+        return if @closed
+
+        push_until_delivered_or_closed(@ready_workers, worker_for_id(worker_id))
+      end
+
+      def deliver_result(message)
+        return if @closed
+
+        push_until_delivered_or_closed(@results, message)
+      end
+
+      def push_until_delivered_or_closed(queue, message)
+        return if @closed
+
+        queue.push(message)
+      rescue ThreadError, ClosedQueueError
+        nil
+      end
+
+      def normalize_worker_error_message(message)
+        sequence = message.sequence
+        error =
+          RactorMapError.new(
+            sequence: sequence,
+            kind: message.kind,
+            cause_class_name: message.cause_class_name,
+            cause_message: message.cause_message
+          )
+
+        ResultError.new(sequence:, error:)
+      end
+
+      def worker_for_id(worker_id)
+        @workers.fetch(worker_id)
+      end
+
+      def track_worker_job(worker, sequence)
+        @worker_state_mutex.synchronize do
+          @active_sequences[worker] = sequence
+        end
+      end
+
+      def clear_worker_job(worker)
+        @worker_state_mutex.synchronize do
+          @active_sequences.delete(worker)
+        end
+      end
+
+      def close_admission(close_upstream: true)
+        return if @admission_closed
+
+        @admission_closed = true
+        close_upstream(record_error: false) if close_upstream
+      end
+
+      def request_worker_shutdown
+        return unless @started
+        return if @worker_shutdown_sent
+
+        @worker_shutdown_sent = true
+        @workers.each do |worker|
+          worker.send(Shutdown.new)
+        rescue StandardError
+          nil
+        end
+      end
+
+      def wait_for_workers
+        return unless @coordinator
+
+        @coordinator.join
+      end
+
+      def close_upstream(record_error: true)
+        return nil if @upstream_closed
+
+        @upstream_closed = true
+        @upstream.close
+        nil
+      rescue StandardError => error
+        @upstream_close_error ||= error if record_error
+        error
+      end
+
+      def close_ready_queue
+        @ready_workers.close
+      end
+
+      def close_result_queue
+        @results.close
+      end
+
+      def build_ractor_map_error(sequence, kind, error)
+        RactorMapError.new(
+          sequence: sequence,
+          kind: kind,
+          cause_class_name: error.class.name,
+          cause_message: error.message,
+          cause: error
+        )
+      end
+
+      class << self
+        def spawn_worker(worker_id, result_port, transform, output_transfer) # :nodoc:
+          Ractor.new(worker_id, result_port, transform, output_transfer) do |id, port, mapper, transfer|
+            current_sequence = nil
+            send_control =
+              lambda do |message|
+                port.send(message)
+                true
+              rescue Exception # rubocop:disable Lint/RescueException
+                false
+              end
+            send_failure =
+              lambda do |sequence, kind, error|
+                send_control.call(WorkerFailure.new(id, sequence, kind, error.class.name, error.message))
+              rescue Exception # rubocop:disable Lint/RescueException
+                false
+              end
+
+            begin
+              if send_control.call(Ready.new(id))
+                loop do
+                  message = Ractor.receive
+                  case message
+                  in Shutdown
+                    break
+                  in Job[sequence, value]
+                    current_sequence = sequence
+                  else
+                    raise TypeError, "invalid ractor_unordered_map worker message: #{message.class}"
+                  end
+
+                  begin
+                    mapped_value = mapper.call(value)
+                  rescue Exception => error # rubocop:disable Lint/RescueException
+                    break unless send_failure.call(current_sequence, :worker, error)
+                  else
+                    begin
+                      if transfer == :move
+                        port.send(WorkerValue.new(id, current_sequence, mapped_value), move: true)
+                      else
+                        port.send(WorkerValue.new(id, current_sequence, mapped_value))
+                      end
+                    rescue Exception => error # rubocop:disable Lint/RescueException
+                      break unless send_failure.call(current_sequence, :output_transfer, error)
+                    end
+                  end
+
+                  current_sequence = nil
+                  break unless send_control.call(Ready.new(id))
+                end
+              end
+            rescue Exception => error # rubocop:disable Lint/RescueException
+              sequence = current_sequence || -1
+              send_failure.call(sequence, :worker_termination, error)
+            ensure
+              send_control.call(Stopped.new(id))
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/fiber_stream/pull.rb

@@ -113,6 +113,10 @@ module FiberStream
       RactorMapBoundary.new(upstream, workers, input_transfer, output_transfer, transform)
     end
 
+    def self.ractor_unordered_map(upstream, workers, input_transfer, output_transfer, transform)
+      RactorUnorderedMapBoundary.new(upstream, workers, input_transfer, output_transfer, transform)
+    end
+
     def self.select(upstream, predicate)
       Select.new(upstream, predicate)
     end
@@ -198,12 +202,14 @@ require_relative "pull/throttle"
 require_relative "pull/parallel_map_boundary"
 require_relative "pull/parallel_unordered_map_boundary"
 require_relative "pull/ractor_map_boundary"
+require_relative "pull/ractor_unordered_map_boundary"
 
 module FiberStream
   module Pull
     private_constant :Each, :IOSource, :RactorPortSource, :RactorMergePortsSource, :RactorProducerSource, :Concat,
                      :Zip, :Merge, :Map, :FilterMap, :Compact, :MapConcat, :Tap, :Select, :Reject, :Take, :Drop,
                      :Grouped, :Scan, :TakeWhile, :DropWhile, :Lines, :Split, :AsyncBoundary, :BufferBoundary,
-                     :Throttle, :ParallelMapBoundary, :ParallelUnorderedMapBoundary, :RactorMapBoundary
+                     :Throttle, :ParallelMapBoundary, :ParallelUnorderedMapBoundary, :RactorMapBoundary,
+                     :RactorUnorderedMapBoundary
   end
 end

data/lib/fiber_stream/sink.rb

@@ -29,6 +29,58 @@ module FiberStream
       end
     end
 
+    # Creates a sink that returns the first element matching a predicate.
+    #
+    # The sink pulls upstream until the block returns a truthy value or
+    # upstream completes. It returns the original matching element, or `nil`
+    # when no element matches. Matching `nil` elements are returned as `nil`,
+    # following Ruby's `Enumerable#find` ambiguity.
+    def self.find(&block)
+      raise ArgumentError, "missing block" unless block
+
+      new do |stream|
+        loop do
+          value = stream.next
+          break nil if Pull.done?(value)
+          break value if block.call(value)
+        end
+      end
+    end
+
+    # Creates a sink that returns whether any element matches a predicate.
+    #
+    # The sink pulls upstream until the block returns a truthy value or upstream
+    # completes. It returns `true` after a truthy predicate result and `false`
+    # when no element matches.
+    def self.any?(&block)
+      raise ArgumentError, "missing block" unless block
+
+      new do |stream|
+        loop do
+          value = stream.next
+          break false if Pull.done?(value)
+          break true if block.call(value)
+        end
+      end
+    end
+
+    # Creates a sink that returns whether all elements match a predicate.
+    #
+    # The sink pulls upstream until the block returns false or nil, or upstream
+    # completes. It returns `false` after a falsey predicate result and `true`
+    # when every predicate result is truthy, including for empty upstream.
+    def self.all?(&block)
+      raise ArgumentError, "missing block" unless block
+
+      new do |stream|
+        loop do
+          value = stream.next
+          break true if Pull.done?(value)
+          break false unless block.call(value)
+        end
+      end
+    end
+
     # Creates a sink that counts all stream elements.
     #
     # The sink consumes upstream until normal completion and returns the number

data/lib/fiber_stream/source.rb

@@ -246,6 +246,25 @@ module FiberStream
       )
     end
 
+    # Returns a new source definition that maps elements in Ractor workers and
+    # emits mapped values as workers complete.
+    #
+    # This is a convenience wrapper around
+    # `via(FiberStream::Flow.ractor_unordered_map(workers:) { ... })` and
+    # preserves the same shareable mapper requirement, unordered delivery,
+    # transfer policy, bounded upstream run-ahead, and cooperative worker
+    # shutdown behavior.
+    def ractor_unordered_map(workers:, input_transfer: :copy, output_transfer: :copy, &block)
+      via(
+        Flow.ractor_unordered_map(
+          workers: workers,
+          input_transfer: input_transfer,
+          output_transfer: output_transfer,
+          &block
+        )
+      )
+    end
+
     # Returns a new source definition that keeps elements matching `block`.
     #
     # This is a convenience wrapper around

data/lib/fiber_stream/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module FiberStream
-  VERSION = "0.5.0"
+  VERSION = "0.6.0"
 end

data/sig/fiber_stream.rbs

@@ -87,6 +87,7 @@ module FiberStream
     def parallel_map: [Out] (concurrency: Integer) { (Elem) -> Out } -> Source[Out]
     def parallel_unordered_map: [Out] (concurrency: Integer) { (Elem) -> Out } -> Source[Out]
     def ractor_map: [Out] (workers: Integer, ?input_transfer: ractor_transfer_policy, ?output_transfer: ractor_transfer_policy) { (Elem) -> Out } -> Source[Out]
+    def ractor_unordered_map: [Out] (workers: Integer, ?input_transfer: ractor_transfer_policy, ?output_transfer: ractor_transfer_policy) { (Elem) -> Out } -> Source[Out]
     def filter_map: [Out] () { (Elem) -> (Out | false | nil) } -> Source[Out]
     def compact: () -> Source[Elem]
     def map_concat: [Out] () { (Elem) -> Enumerable[Out] } -> Source[Out]
@@ -113,6 +114,7 @@ module FiberStream
     def self.parallel_map: [In, Out] (concurrency: Integer) { (In) -> Out } -> Flow[In, Out]
     def self.parallel_unordered_map: [In, Out] (concurrency: Integer) { (In) -> Out } -> Flow[In, Out]
     def self.ractor_map: [In, Out] (workers: Integer, ?input_transfer: ractor_transfer_policy, ?output_transfer: ractor_transfer_policy) { (In) -> Out } -> Flow[In, Out]
+    def self.ractor_unordered_map: [In, Out] (workers: Integer, ?input_transfer: ractor_transfer_policy, ?output_transfer: ractor_transfer_policy) { (In) -> Out } -> Flow[In, Out]
     def self.filter_map: [In, Out] () { (In) -> (Out | false | nil) } -> Flow[In, Out]
     def self.compact: [Elem] () -> Flow[Elem, Elem]
     def self.map_concat: [In, Out] () { (In) -> Enumerable[Out] } -> Flow[In, Out]
@@ -136,6 +138,9 @@ module FiberStream
   class Sink[In, Mat]
     def self.to_a: [Elem] () -> Sink[Elem, Array[Elem]]
     def self.first: [Elem] () -> Sink[Elem, Elem?]
+    def self.find: [Elem] () { (Elem) -> boolish } -> Sink[Elem, Elem?]
+    def self.any?: [Elem] () { (Elem) -> boolish } -> Sink[Elem, bool]
+    def self.all?: [Elem] () { (Elem) -> boolish } -> Sink[Elem, bool]
     def self.count: [Elem] () -> Sink[Elem, Integer]
     def self.fold: [Elem, Acc] (Acc initial) { (Acc, Elem) -> Acc } -> Sink[Elem, Acc]
     def self.foreach: [Elem] () { (Elem) -> void } -> Sink[Elem, Integer]

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: fiber_stream
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Dai Akatsuka
@@ -120,6 +120,7 @@ files:
 - examples/ractor_merge_ports_and_map.rb
 - examples/ractor_port_source.rb
 - examples/ractor_producer_sources.rb
+- examples/ractor_unordered_map_hashing.rb
 - lib/fiber_stream.rb
 - lib/fiber_stream/errors.rb
 - lib/fiber_stream/flow.rb
@@ -146,6 +147,7 @@ files:
 - lib/fiber_stream/pull/ractor_merge_ports_source.rb
 - lib/fiber_stream/pull/ractor_port_source.rb
 - lib/fiber_stream/pull/ractor_producer_source.rb
+- lib/fiber_stream/pull/ractor_unordered_map_boundary.rb
 - lib/fiber_stream/pull/reject.rb
 - lib/fiber_stream/pull/scan.rb
 - lib/fiber_stream/pull/select.rb
@@ -169,7 +171,7 @@ licenses:
 metadata:
   allowed_push_host: https://rubygems.org
   homepage_uri: https://github.com/dakatsuka/fiber_stream
-  source_code_uri: https://github.com/dakatsuka/fiber_stream/tree/v0.5.0
+  source_code_uri: https://github.com/dakatsuka/fiber_stream/tree/v0.6.0
   changelog_uri: https://github.com/dakatsuka/fiber_stream/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'true'
 rdoc_options: []