teek 0.1.0

data/lib/teek/demo_support.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+#
+# TeekDemo - Helper module for automated sample testing and recording
+#
+# Two independent modes:
+#   - Test mode (TK_READY_PORT): Quick verification that sample loads/runs
+#   - Record mode (TK_RECORD): Video capture with longer delays
+#
+# Usage:
+#   require_relative '../lib/teek/demo_support'
+#
+#   app = Teek::App.new
+#   TeekDemo.app = app
+#
+#   if TeekDemo.active?
+#     TeekDemo.on_visible {
+#       do_something
+#       app.after(TeekDemo.delay(test: 200, record: 500)) {
+#         TeekDemo.finish
+#       }
+#     }
+#   end
+#
+require 'socket'
+
+# @api private
+module TeekDemo
+  class << self
+    attr_accessor :app
+
+    def testing?
+      !!ENV['TK_READY_PORT']
+    end
+
+    def recording?
+      !!ENV['TK_RECORD']
+    end
+
+    def active?
+      testing? || recording?
+    end
+
+    # Get appropriate delay for current mode
+    def delay(test: 100, record: 1000)
+      recording? ? record : test
+    end
+
+    # Run block once when window becomes visible.
+    # @param window [String] Tcl path of the window to watch (default: ".")
+    def on_visible(window: '.', timeout: 60, &block)
+      return unless active?
+      raise ArgumentError, "block required" unless block
+      raise "TeekDemo.app not set" unless app
+
+      @demo_started = false
+      app.bind(window, 'Visibility') do
+        next if @demo_started
+        @demo_started = true
+
+        signal_recording_ready(window: window) if recording?
+
+        # Safety timeout
+        app.after(timeout * 1000) { finish }
+
+        app.after(50) { block.call }
+      end
+    end
+
+    # Run block once when event loop is idle.
+    # Use when window is already created before binding can be set up.
+    def after_idle(timeout: 60, &block)
+      return unless active?
+      raise ArgumentError, "block required" unless block
+      raise "TeekDemo.app not set" unless app
+
+      @demo_started = false
+      app.after_idle {
+        next if @demo_started
+        @demo_started = true
+
+        signal_recording_ready if recording?
+
+        app.after(timeout * 1000) { finish }
+
+        block.call
+      }
+    end
+
+    # Signal recording harness that window is visible and ready to record.
+    # Polls until geometry is valid, then signals via TCP.
+    def signal_recording_ready(window: '.')
+      return unless (port = ENV['TK_STOP_PORT'])
+      return if @_recording_ready_sent
+
+      try_signal = proc do
+        app.tcl_eval('update idletasks')
+        width = app.tcl_eval("winfo width #{window}").to_i
+        height = app.tcl_eval("winfo height #{window}").to_i
+
+        if width >= 10 && height >= 10
+          @_recording_ready_sent = true
+          @_initial_geometry = [width, height]
+
+          begin
+            sock = TCPSocket.new('127.0.0.1', port.to_i)
+            sock.write("R:#{width}x#{height}")
+            sock.close
+          rescue StandardError => e
+            $stderr.puts "TeekDemo: signal error: #{e.message}"
+          end
+        else
+          app.after(10) { try_signal.call }
+        end
+      end
+
+      try_signal.call
+    end
+
+    # Signal test harness that sample is ready (without exiting)
+    def signal_ready
+      $stdout.flush
+      if (port = ENV.delete('TK_READY_PORT'))
+        begin
+          TCPSocket.new('127.0.0.1', port.to_i).close
+        rescue StandardError
+        end
+      end
+    end
+
+    # Signal completion and exit cleanly.
+    # Handles TK_READY_PORT (test) and TK_STOP_PORT (record).
+    def finish
+      signal_ready
+
+      if (port = ENV['TK_STOP_PORT'])
+        Thread.new do
+          begin
+            sock = TCPSocket.new('127.0.0.1', port.to_i)
+            sock.read(1)  # Block until harness sends byte or closes
+            sock.close
+          rescue StandardError
+          end
+          app.after(0) { app.destroy('.') }
+        end
+      else
+        app.after(0) { app.destroy('.') }
+      end
+    end
+  end
+end

data/lib/teek/ractor_support.rb

@@ -0,0 +1,246 @@
+# frozen_string_literal: true
+
+# Ractor and background work support for Teek applications.
+#
+# This module provides a unified API across Ruby versions:
+# - Ruby 4.x: Uses Ractor::Port, Ractor.shareable_proc for true parallelism
+# - Ruby 3.x: Ractor mode NOT supported (falls back to thread mode)
+# - Thread fallback: Always available, works everywhere
+#
+# The implementation is selected automatically based on Ruby version.
+
+require_relative 'background_thread'
+
+if Ractor.respond_to?(:shareable_proc)
+  require_relative 'background_ractor4x'
+end
+
+module Teek
+
+  # Unified background work API. Delegates to a mode-specific implementation
+  # selected via the +mode:+ parameter.
+  #
+  # Modes:
+  # - +:thread+ — traditional threading; best for I/O-bound work where the GVL
+  #   is released during blocking calls. Always available.
+  # - +:ractor+ — true parallel execution via Ractor (Ruby 4.x+ only); best
+  #   for CPU-bound work.
+  #
+  # @example Basic usage
+  #   task = Teek::BackgroundWork.new(app, data, mode: :thread) do |t, d|
+  #     d.each { |item| t.yield(process(item)) }
+  #   end
+  #   task.on_progress { |r| update_ui(r) }
+  #       .on_done { puts "Finished" }
+  #
+  # @example Pause / resume / stop
+  #   task.pause
+  #   task.resume
+  #   task.stop
+  #
+  # @example Configuration
+  #   Teek::BackgroundWork.poll_ms = 16
+  #   Teek::BackgroundWork.drop_intermediate = true
+  #   Teek::BackgroundWork.abort_on_error = false
+  class BackgroundWork
+    class << self
+      # @return [Integer] UI poll interval in milliseconds (default 16)
+      attr_accessor :poll_ms
+      # @return [Boolean] when true, only the latest progress value per poll
+      #   cycle is delivered (default true)
+      attr_accessor :drop_intermediate
+      # @return [Boolean] when true, raise on ractor errors instead of warning
+      #   (default false)
+      attr_accessor :abort_on_error
+    end
+    self.poll_ms = 16
+    self.drop_intermediate = true
+    self.abort_on_error = false
+
+    # @return [Boolean] whether Ractor mode is available (Ruby 4.x+)
+    RACTOR_SUPPORTED = Ractor.respond_to?(:shareable_proc)
+
+    # @api private
+    @background_modes = {}
+
+    # @api private
+    def self.register_background_mode(name, klass)
+      @background_modes[name.to_sym] = klass
+    end
+
+    # @api private
+    def self.background_modes
+      @background_modes
+    end
+
+    # @api private
+    def self.background_mode_class(name)
+      @background_modes[name.to_sym]
+    end
+
+    # Register built-in modes
+    register_background_mode :thread, Teek::BackgroundThread::BackgroundWork
+
+    # Ractor mode only available on Ruby 4.x+
+    if RACTOR_SUPPORTED
+      register_background_mode :ractor, Teek::BackgroundRactor4x::BackgroundWork
+    end
+
+    # @return [String, nil] optional name for this task
+    attr_accessor :name
+
+    # @param app [Teek::App] the application instance
+    # @param data [Object] data passed to the worker block
+    # @param mode [Symbol] +:thread+ or +:ractor+
+    # @param worker [Class, nil] optional worker class (must respond to +#call(task, data)+)
+    # @yield [task, data] block executed in the background
+    # @yieldparam task [BackgroundThread::BackgroundWork::TaskContext, BackgroundRactor4x::BackgroundWork::TaskContext]
+    # @yieldparam data [Object]
+    # @raise [ArgumentError] if mode is unknown
+    def initialize(app, data, mode: :thread, worker: nil, &block)
+      impl_class = self.class.background_mode_class(mode)
+      unless impl_class
+        available = self.class.background_modes.keys.join(', ')
+        raise ArgumentError, "Unknown mode: #{mode}. Available: #{available}"
+      end
+
+      @impl = impl_class.new(app, data, worker: worker, &block)
+      @mode = mode
+      @name = nil
+    end
+
+    # @return [Symbol] the active mode (+:thread+ or +:ractor+)
+    def mode
+      @mode
+    end
+
+    # @return [Boolean]
+    def done?
+      @impl.done?
+    end
+
+    # @return [Boolean]
+    def paused?
+      @impl.paused?
+    end
+
+    # @yield [value] called on the main thread with each result
+    # @return [self]
+    def on_progress(&block)
+      @impl.on_progress(&block)
+      self
+    end
+
+    # @yield called on the main thread when the worker completes
+    # @return [self]
+    def on_done(&block)
+      @impl.on_done(&block)
+      self
+    end
+
+    # @yield [msg] called on the main thread with custom worker messages
+    # @return [self]
+    def on_message(&block)
+      @impl.on_message(&block)
+      self
+    end
+
+    # Send a message to the worker.
+    # @param msg [Object] any value (must be Ractor-shareable in +:ractor+ mode)
+    # @return [self]
+    def send_message(msg)
+      @impl.send_message(msg)
+      self
+    end
+
+    # Pause the worker.
+    # @return [self]
+    def pause
+      @impl.pause
+      self
+    end
+
+    # Resume a paused worker.
+    # @return [self]
+    def resume
+      @impl.resume
+      self
+    end
+
+    # Request the worker to stop.
+    # @return [self]
+    def stop
+      @impl.stop
+      self
+    end
+
+    # Force-close the worker and associated resources.
+    # @return [self]
+    def close
+      @impl.close if @impl.respond_to?(:close)
+      self
+    end
+
+    # Explicitly start the worker. Called automatically by {#on_progress}
+    # and {#on_done}.
+    # @return [self]
+    def start
+      @impl.start
+      self
+    end
+  end
+
+  # Simplified streaming API without pause/resume support.
+  # Uses Ractor on Ruby 4.x+, falls back to threads on 3.x.
+  #
+  # @example
+  #   Teek::RactorStream.new(app, files) do |yielder, data|
+  #     data.each { |f| yielder.yield(process(f)) }
+  #   end.on_progress { |r| update_ui(r) }
+  #      .on_done { puts "Done!" }
+  class RactorStream
+    def initialize(app, data, &block)
+      # Ruby 4.x: use Ractor with shareable_proc for true parallelism
+      # Ruby 3.x: use threads (Ractor mode not supported)
+      if BackgroundWork::RACTOR_SUPPORTED
+        shareable_block = Ractor.shareable_proc(&block)
+        wrapped_block = Ractor.shareable_proc do |task, d|
+          yielder = StreamYielder.new(task)
+          shareable_block.call(yielder, d)
+        end
+        @impl = Teek::BackgroundRactor4x::BackgroundWork.new(app, data, &wrapped_block)
+      else
+        wrapped_block = proc do |task, d|
+          yielder = StreamYielder.new(task)
+          block.call(yielder, d)
+        end
+        @impl = Teek::BackgroundThread::BackgroundWork.new(app, data, &wrapped_block)
+      end
+    end
+
+    def on_progress(&block)
+      @impl.on_progress(&block)
+      self
+    end
+
+    def on_done(&block)
+      @impl.on_done(&block)
+      self
+    end
+
+    def cancel
+      @impl.stop
+    end
+
+    # Adapter for old yielder API
+    class StreamYielder
+      def initialize(task)
+        @task = task
+      end
+
+      def yield(value)
+        @task.yield(value)
+      end
+    end
+  end
+end

data/lib/teek/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Teek
+  VERSION = "0.1.0"
+end