fiber_stream 0.1.0

data/lib/fiber_stream/pull/ractor_port_source.rb

@@ -0,0 +1,242 @@
+# frozen_string_literal: true
+
+module FiberStream
+  module Pull
+    # Pull stream for `Source.ractor_port`.
+    #
+    # Downstream demand is converted into one `RactorPort::Ack` sent to the
+    # producer-owned acknowledgment port. Blocking Ractor waits are isolated in
+    # a coordinator thread so scheduler-managed fibers do not call Ractor wait
+    # APIs directly.
+    class RactorPortSource
+      WAIT_INTERVAL = 0.001
+
+      def initialize(port, ack_port, ack_transfer, cancel)
+        @port = port
+        @ack_port = ack_port
+        @ack_transfer = ack_transfer
+        @cancel_enabled = cancel
+        @demands = Thread::SizedQueue.new(1)
+        @results = Thread::SizedQueue.new(1)
+        @shutdown_port = nil
+        @coordinator = nil
+        @state_mutex = Mutex.new
+        @started = false
+        @closed = false
+        @done = false
+        @producer_terminal = false
+        @cancel_sent = false
+      end
+
+      def next
+        return DONE if closed_or_done?
+
+        start
+        request_next_message
+        result = @results.pop
+        return DONE if result.nil?
+
+        handle_result(result)
+      end
+
+      def close
+        cancel_error = nil
+
+        should_cancel =
+          @state_mutex.synchronize do
+            return if @closed
+
+            @closed = true
+            @done = true
+            @cancel_enabled && !@producer_terminal && !@cancel_sent
+          end
+
+        cancel_error = send_cancel if should_cancel
+        wake_coordinator
+        close_result_queue
+        wait_for_coordinator
+        raise cancel_error if cancel_error
+      end
+
+      private
+
+      def closed_or_done?
+        @state_mutex.synchronize { @closed || @done }
+      end
+
+      def start
+        @state_mutex.synchronize do
+          return if @started
+
+          @started = true
+          @shutdown_port = Ractor::Port.new
+          @coordinator = Thread.new { run_coordinator }
+        end
+      end
+
+      def request_next_message
+        @demands.push(:next)
+      rescue ClosedQueueError
+        nil
+      end
+
+      def handle_result(result)
+        tag = result.fetch(0)
+
+        case tag
+        when :message
+          handle_protocol_message(result.fetch(1))
+        when :error
+          mark_done
+          raise_error(result.fetch(1))
+        when :closed
+          DONE
+        end
+      end
+
+      def handle_protocol_message(message)
+        case message
+        in RactorPort::Element[value]
+          value
+        in RactorPort::Complete
+          mark_producer_terminal
+          DONE
+        in RactorPort::Failure[String => cause_class_name, String => cause_message]
+          mark_producer_terminal
+          raise RactorPortSourceError.new(
+            kind: :producer_failure,
+            cause_class_name: cause_class_name,
+            cause_message: cause_message
+          )
+        in RactorPort::Failure
+          raise_invalid_message(message, "Failure payloads must be Strings")
+        else
+          raise_invalid_message(message, "invalid RactorPort message")
+        end
+      end
+
+      def raise_invalid_message(message, cause_message)
+        mark_done
+        raise RactorPortSourceError.new(
+          kind: :invalid_message,
+          cause_class_name: message.class.name,
+          cause_message: cause_message
+        )
+      end
+
+      def mark_done
+        @state_mutex.synchronize { @done = true }
+      end
+
+      def mark_producer_terminal
+        @state_mutex.synchronize do
+          @done = true
+          @producer_terminal = true
+        end
+      end
+
+      def raise_error(error)
+        if error.is_a?(RactorPortSourceError) && error.original_cause
+          raise error, cause: error.original_cause
+        end
+
+        raise error
+      end
+
+      def run_coordinator
+        loop do
+          demand = @demands.pop
+          break unless demand
+          break if closed?
+
+          ack_error = send_ack
+          if ack_error
+            deliver_result([:error, ack_error])
+            break
+          end
+
+          selected, message = select_message
+          break if selected == @shutdown_port || closed?
+
+          deliver_result([:message, message])
+        end
+      rescue StandardError => error
+        deliver_result([:error, build_error(:receive, error)])
+      ensure
+        deliver_result([:closed]) if closed?
+      end
+
+      def select_message
+        Ractor.select(@port, @shutdown_port)
+      end
+
+      def send_ack
+        send_control(RactorPort::Ack.new)
+        nil
+      rescue StandardError => error
+        build_error(:ack_transfer, error)
+      end
+
+      def send_cancel
+        @state_mutex.synchronize { @cancel_sent = true }
+        send_control(RactorPort::Cancel.new(:closed))
+        nil
+      rescue StandardError => error
+        build_error(:cancel_transfer, error)
+      end
+
+      def send_control(message)
+        if @ack_transfer == :move
+          @ack_port.send(message, move: true)
+        else
+          @ack_port.send(message)
+        end
+      end
+
+      def build_error(kind, error)
+        RactorPortSourceError.new(
+          kind: kind,
+          cause_class_name: error.class.name,
+          cause_message: error.message,
+          cause: error
+        )
+      end
+
+      def closed?
+        @state_mutex.synchronize { @closed }
+      end
+
+      def wake_coordinator
+        close_demand_queue
+        return unless @shutdown_port
+
+        @shutdown_port.send(:shutdown)
+      rescue StandardError
+        nil
+      end
+
+      def wait_for_coordinator
+        return unless @coordinator
+
+        sleep WAIT_INTERVAL while @coordinator.alive?
+        @coordinator.join
+      end
+
+      def deliver_result(result)
+        return if @results.closed?
+
+        @results.push(result)
+      rescue ClosedQueueError, ThreadError
+        nil
+      end
+
+      def close_demand_queue
+        @demands.close
+      end
+
+      def close_result_queue
+        @results.close
+      end
+    end
+  end
+end

data/lib/fiber_stream/pull/select.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module FiberStream
+  module Pull
+    # Filtering stage.
+    #
+    # A single downstream demand may pull multiple upstream elements until the
+    # predicate accepts a value or upstream completes. Rejected elements are
+    # discarded immediately and are not buffered.
+    class Select
+      def initialize(upstream, predicate)
+        @upstream = upstream
+        @predicate = predicate
+        @closed = false
+        @done = false
+      end
+
+      def next
+        return DONE if @closed || @done
+
+        loop do
+          value = @upstream.next
+          if Pull.done?(value)
+            @done = true
+            return DONE
+          end
+
+          return value if @predicate.call(value)
+        end
+      end
+
+      def close
+        return if @closed
+
+        @closed = true
+        @upstream.close
+      end
+    end
+  end
+end

data/lib/fiber_stream/pull/take.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module FiberStream
+  module Pull
+    # Limiting stage.
+    #
+    # The stage closes upstream as soon as the limit is reached, including
+    # `take(0)` on first demand. This makes early completion visible to
+    # resource-owning sources and asynchronous boundaries.
+    class Take
+      def initialize(upstream, count)
+        @upstream = upstream
+        @remaining = count
+        @closed = false
+        @done = false
+      end
+
+      def next
+        return DONE if @closed || @done
+
+        if @remaining.zero?
+          @done = true
+          close
+          return DONE
+        end
+
+        value = @upstream.next
+        if Pull.done?(value)
+          @done = true
+          return DONE
+        end
+
+        @remaining -= 1
+        close if @remaining.zero?
+
+        value
+      end
+
+      def close
+        return if @closed
+
+        @closed = true
+        @upstream.close
+      end
+    end
+  end
+end

data/lib/fiber_stream/pull.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module FiberStream
+  # Internal pull-stream runtime.
+  #
+  # Public `Source`, `Flow`, and `Sink` objects are lazy definitions. When a
+  # source is materialized, those definitions attach together into private pull
+  # stream objects from this module. Every pull stream responds to `#next` and
+  # `#close`: `#next` returns either an element or the private `DONE` sentinel,
+  # while `#close` releases upstream resources and may raise cleanup failures.
+  # The sentinel must never escape through public APIs.
+  module Pull
+    DONE = Object.new.freeze
+
+    def self.done?(value)
+      value.equal?(DONE)
+    end
+
+    def self.each(enumerable)
+      Each.new(enumerable)
+    end
+
+    def self.io(io, chunk_size, close_io)
+      IOSource.new(io, chunk_size, close_io)
+    end
+
+    def self.ractor_port(port, ack_port, ack_transfer, cancel)
+      RactorPortSource.new(port, ack_port, ack_transfer, cancel)
+    end
+
+    def self.map(upstream, transform)
+      Map.new(upstream, transform)
+    end
+
+    def self.parallel_map(upstream, concurrency, transform)
+      ParallelMapBoundary.new(upstream, concurrency, transform)
+    end
+
+    def self.ractor_map(upstream, workers, input_transfer, output_transfer, transform)
+      RactorMapBoundary.new(upstream, workers, input_transfer, output_transfer, transform)
+    end
+
+    def self.select(upstream, predicate)
+      Select.new(upstream, predicate)
+    end
+
+    def self.take(upstream, count)
+      Take.new(upstream, count)
+    end
+
+    def self.async(upstream)
+      AsyncBoundary.new(upstream)
+    end
+
+    def self.buffer(upstream, count)
+      BufferBoundary.new(upstream, count)
+    end
+
+    def self.lines(upstream, chomp, max_length)
+      Lines.new(upstream, chomp, max_length)
+    end
+
+    private_constant :DONE
+  end
+end
+
+require_relative "pull/each"
+require_relative "pull/io_source"
+require_relative "pull/ractor_port_source"
+require_relative "pull/map"
+require_relative "pull/select"
+require_relative "pull/take"
+require_relative "pull/lines"
+require_relative "pull/async_boundary"
+require_relative "pull/buffer_boundary"
+require_relative "pull/parallel_map_boundary"
+require_relative "pull/ractor_map_boundary"
+
+module FiberStream
+  module Pull
+    private_constant :Each, :IOSource, :RactorPortSource, :Map, :Select, :Take, :Lines,
+                     :AsyncBoundary, :BufferBoundary, :ParallelMapBoundary,
+                     :RactorMapBoundary
+  end
+end

data/lib/fiber_stream/ractor_port.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module FiberStream
+  # Typed message envelopes for `Source.ractor_port`.
+  #
+  # Producers send `Element`, `Complete`, and `Failure` messages to the data
+  # port. FiberStream sends `Ack` and `Cancel` messages to the producer-owned
+  # acknowledgment port. The envelopes keep stream values distinct from control
+  # messages and support Ruby pattern matching.
+  module RactorPort
+    Element = ::Data.define(:value)
+    Complete = ::Data.define
+    Failure = ::Data.define(:cause_class_name, :cause_message)
+    Ack = ::Data.define
+    Cancel = ::Data.define(:reason)
+  end
+end

data/lib/fiber_stream/running_pipeline.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+module FiberStream
+  class RunningPipeline
+    def initialize(scheduler, &run)
+      @scheduler = scheduler
+      @completion = nil
+      @waiters = []
+      @mutex = Mutex.new
+      @cancel_requested = false
+      @cancellation_error = nil
+      @fiber = Fiber.schedule { run_background(run) }
+    end
+
+    # Waits for the background pipeline to complete.
+    #
+    # On success, returns the sink materialized value. On stream failure,
+    # re-raises the original exception. If cancellation interrupts the
+    # background materialization, raises `PipelineCancelledError`. Waiting
+    # before completion requires a scheduler-backed non-blocking fiber; waiting
+    # after completion replays the stored result without requiring a scheduler.
+    def wait
+      message = nil
+      waiter = nil
+
+      @mutex.synchronize do
+        if @completion
+          message = @completion
+        else
+          validate_scheduler!("RunningPipeline#wait")
+          waiter = Thread::Queue.new
+          @waiters << waiter
+        end
+      end
+
+      message ||= waiter.pop
+      deliver(message)
+    end
+
+    # Requests cancellation of the background pipeline.
+    #
+    # Cancellation is cooperative and uses the scheduler captured when
+    # `Pipeline#run_async` started the background fiber. The method is
+    # idempotent. If the captured scheduler cannot interrupt fibers, this
+    # method raises `NotImplementedError` without recording a cancellation
+    # request.
+    def cancel
+      fiber = nil
+      cancellation_error = nil
+
+      @mutex.synchronize do
+        return self if @completion
+        return self if @cancel_requested
+
+        unless @scheduler.respond_to?(:fiber_interrupt)
+          raise NotImplementedError, "scheduler does not support fiber_interrupt"
+        end
+
+        cancellation_error = PipelineCancelledError.new("pipeline cancelled")
+        @cancellation_error = cancellation_error
+        @cancel_requested = true
+        fiber = @fiber
+      end
+
+      interrupt(fiber, cancellation_error)
+      self
+    end
+
+    # Returns true when the background run has completed with success, failure,
+    # or cancellation.
+    def done?
+      @mutex.synchronize { !@completion.nil? }
+    end
+
+    # Returns true after `cancel` successfully records a cancellation request.
+    def cancel_requested?
+      @mutex.synchronize { @cancel_requested }
+    end
+
+    private_class_method :new
+
+    private
+
+    def run_background(run)
+      complete([:value, run.call])
+    rescue Exception => error # rubocop:disable Lint/RescueException
+      complete(classify_error(error))
+    end
+
+    def classify_error(error)
+      if cancellation_error?(error)
+        [:cancelled, error]
+      else
+        [:error, error]
+      end
+    end
+
+    def cancellation_error?(error)
+      @mutex.synchronize { @cancellation_error.equal?(error) }
+    end
+
+    def complete(message)
+      waiters = []
+
+      @mutex.synchronize do
+        return if @completion
+
+        @completion = message
+        waiters = @waiters
+        @waiters = []
+      end
+
+      waiters.each { |waiter| waiter << message }
+    end
+
+    def deliver(message)
+      case message.fetch(0)
+      when :value
+        message.fetch(1)
+      when :error, :cancelled
+        raise message.fetch(1)
+      end
+    end
+
+    def interrupt(fiber, cancellation_error)
+      return unless fiber&.alive?
+
+      @scheduler.fiber_interrupt(fiber, cancellation_error)
+    rescue NotImplementedError, StandardError
+      clear_cancellation_request(cancellation_error)
+      raise
+    end
+
+    def clear_cancellation_request(cancellation_error)
+      @mutex.synchronize do
+        return unless @cancellation_error.equal?(cancellation_error)
+        return if @completion
+
+        @cancellation_error = nil
+        @cancel_requested = false
+      end
+    end
+
+    def validate_scheduler!(operation)
+      return if Fiber.scheduler && !Fiber.current.blocking?
+
+      message =
+        if Fiber.scheduler
+          "#{operation} requires a non-blocking fiber"
+        else
+          "#{operation} requires Fiber.scheduler"
+        end
+      raise SchedulerRequiredError, message
+    end
+  end
+end