cyclotone 0.1.0 → 1.0.0

data/lib/cyclotone/scheduler.rb

@@ -1,70 +1,135 @@
 # frozen_string_literal: true
 
-require "thread"
-
 module Cyclotone
   class Scheduler
     LOOKAHEAD = 0.3
     INTERVAL = 0.05
     DEFAULT_CPS = Rational(9, 16)
+    DEFAULT_STOP_TIMEOUT = 1.0
+    SENT_RETAIN_CYCLES = 4
+    SystemClock = Struct.new(:unused, keyword_init: true) do
+      def monotonic_time
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
 
-    attr_reader :backend, :cps, :lookahead, :interval
+      def wall_time
+        Time.now.to_f
+      end
+    end
 
-    def initialize(cps: DEFAULT_CPS, backend:, lookahead: LOOKAHEAD, interval: INTERVAL, logger: nil)
+    attr_reader :backend, :cps, :lookahead, :interval, :lookahead_cycles, :interval_cycles, :metrics
+
+    def initialize(
+      backend:,
+      cps: DEFAULT_CPS,
+      lookahead: LOOKAHEAD,
+      interval: INTERVAL,
+      lookahead_cycles: nil,
+      interval_cycles: nil,
+      logger: nil,
+      retry_failed: false,
+      clock: nil
+    )
       @backend = backend
-      @cps = cps.to_f
+      @cps = normalize_cps(cps)
       @lookahead = lookahead
       @interval = interval
+      @lookahead_cycles = lookahead_cycles&.to_f
+      @interval_cycles = interval_cycles&.to_f
       @logger = logger
+      @retry_failed = retry_failed
+      @clock = clock || SystemClock.new
       @mutex = Mutex.new
       @patterns = {}
       @sent = {}
       @running = false
+      @thread = nil
+      @last_error = nil
       @start_monotonic = monotonic_time
-      @start_wall_time = Time.now.to_f
+      @start_wall_time = wall_time
       @start_cycle = 0.0
       @last_cycle = 0.0
+      @metrics = { ticks: 0, last_tick_duration: 0.0, max_tick_duration: 0.0 }
     end
 
     def start
-      return if @running
+      @mutex.synchronize do
+        return self if @running
 
-      @running = true
-      @thread = Thread.new do
-        while @running
-          begin
-            tick
-          rescue StandardError => error
-            log_runtime_error(error)
-          end
+        @running = true
+        @last_error = nil
+        @thread = Thread.new do
+          Thread.current.abort_on_exception = false
 
-          sleep(@interval)
+          while running?
+            tick_started = monotonic_time
+
+            begin
+              tick(tick_started)
+            rescue StandardError => error
+              log_runtime_error(error)
+            end
+
+            record_tick_duration(monotonic_time - tick_started)
+            sleep(current_interval)
+          end
         end
       end
+
+      self
     end
 
-    def stop
-      @running = false
-      @thread&.join
+    def stop(timeout: DEFAULT_STOP_TIMEOUT)
+      thread = @mutex.synchronize do
+        @running = false
+        @thread
+      end
+
+      thread&.join(timeout)
+
+      @mutex.synchronize do
+        @thread = nil if @thread == thread && !thread&.alive?
+      end
+
+      self
+    end
+
+    def last_error
+      @mutex.synchronize { @last_error }
     end
 
     def tick(now = monotonic_time)
       state = snapshot_state
-      logical_end = time_to_cycle(now + lookahead, state[:cps], state[:start_cycle], state[:start_monotonic])
+      current_cycle = time_to_cycle(now, state[:cps], state[:start_cycle], state[:start_monotonic])
+      logical_end = if lookahead_cycles
+                      current_cycle + lookahead_cycles
+                    else
+                      time_to_cycle(now + lookahead, state[:cps], state[:start_cycle], state[:start_monotonic])
+                    end
       dispatch_until(logical_end, state)
     end
 
-    def update_pattern(slot_id, pattern)
-      @mutex.synchronize { @patterns[slot_id] = Pattern.ensure_pattern(pattern) }
+    def update_pattern(slot_id, pattern, cps: nil, phase: 0)
+      @mutex.synchronize do
+        @patterns[slot_id] = {
+          pattern: Pattern.ensure_pattern(pattern),
+          cps: cps&.to_f,
+          phase: Pattern.to_rational(phase)
+        }
+      end
     end
 
     def remove_pattern(slot_id)
-      @mutex.synchronize { @patterns.delete(slot_id) }
+      @mutex.synchronize do
+        @patterns.delete(slot_id)
+        @sent.delete_if { |key, _| key.first == slot_id }
+      end
     end
 
     def setcps(value)
+      normalized_cps = normalize_cps(value)
       now = monotonic_time
-      wall_now = Time.now.to_f
+      wall_now = wall_time
 
       @mutex.synchronize do
         current_cycle = time_to_cycle(now, @cps, @start_cycle, @start_monotonic)
@@ -72,7 +137,7 @@ module Cyclotone
         @start_cycle = current_cycle
         @start_monotonic = now
         @start_wall_time = wall_now
-        @cps = value.to_f
+        @cps = normalized_cps
       end
     end
 
@@ -84,7 +149,7 @@ module Cyclotone
       @mutex.synchronize do
         @start_cycle = value.to_f
         @start_monotonic = monotonic_time
-        @start_wall_time = Time.now.to_f
+        @start_wall_time = wall_time
         @last_cycle = value.to_f
         @sent.clear
       end
@@ -99,25 +164,40 @@ module Cyclotone
     end
 
     def running?
-      @running
+      @mutex.synchronize { @running }
     end
 
-    def render(duration:)
+    def render(duration:, at: 0.0)
       duration_value = duration.to_f
       raise ArgumentError, "render duration must be non-negative" if duration_value.negative?
 
-      state = snapshot_state
+      state = snapshot_state.merge(start_wall_time: at.to_f)
       state[:backend].begin_capture(at: state[:start_wall_time]) if state[:backend].respond_to?(:begin_capture)
 
       logical_end = state[:start_cycle] + (duration_value * state[:cps])
       dispatch_until(logical_end, state)
+
+      state[:backend].end_capture if state[:backend].respond_to?(:end_capture)
+      state[:backend].write! if state[:backend].respond_to?(:write!)
       self
     end
 
     private
 
     def monotonic_time
-      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      @clock.respond_to?(:monotonic_time) ? @clock.monotonic_time : @clock.call(:monotonic)
+    end
+
+    def wall_time
+      @clock.respond_to?(:wall_time) ? @clock.wall_time : @clock.call(:wall)
+    end
+
+    def current_interval
+      @mutex.synchronize do
+        return @interval unless @interval_cycles
+
+        @interval_cycles / @cps
+      end
     end
 
     def snapshot_state
@@ -138,31 +218,90 @@ module Cyclotone
       return if logical_end <= state[:last_cycle]
 
       query_span = TimeSpan.new(Rational(state[:last_cycle].to_r), Rational(logical_end.to_r))
+      failed = false
+
+      state[:patterns].each do |slot_id, slot|
+        pattern = slot[:pattern]
+        scale = slot_scale(slot, state[:cps])
+        phase = slot[:phase]
+        slot_span = TimeSpan.new((query_span.start * scale) + phase, (query_span.stop * scale) + phase)
 
-      state[:patterns].each do |slot_id, pattern|
-        pattern.query_span(query_span).each do |event|
+        pattern.query_span(slot_span).each do |event|
+          event = map_slot_event(event, scale, phase)
           next unless event.onset
 
           key = [slot_id, event.onset, event.value]
-          next if @sent[key]
+          next if sent?(key)
 
           absolute_time = state[:start_wall_time] + ((event.onset.to_f - state[:start_cycle]) / state[:cps])
-          state[:backend].send_event(event, at: absolute_time, cps: state[:cps])
-          @sent[key] = true
-        rescue StandardError => error
-          log_runtime_error(error)
+
+          begin
+            state[:backend].send_event(event, at: absolute_time, cps: state[:cps], slot_id: slot_id)
+            mark_sent(key, logical_end)
+          rescue StandardError => error
+            failed = true
+            log_runtime_error(error, slot_id: slot_id)
+          end
         end
       end
 
-      @mutex.synchronize { @last_cycle = logical_end }
+      @mutex.synchronize { @last_cycle = logical_end unless failed && @retry_failed }
+    end
+
+    def sent?(key)
+      @mutex.synchronize { @sent.key?(key) }
+    end
+
+    def mark_sent(key, logical_end)
+      @mutex.synchronize do
+        @sent[key] = logical_end
+        prune_sent(logical_end)
+      end
+    end
+
+    def prune_sent(logical_end)
+      retain_after = logical_end - SENT_RETAIN_CYCLES
+      @sent.delete_if { |_key, cycle| cycle < retain_after }
+    end
+
+    def record_tick_duration(duration)
+      @mutex.synchronize do
+        @metrics = {
+          ticks: @metrics[:ticks] + 1,
+          last_tick_duration: duration,
+          max_tick_duration: [@metrics[:max_tick_duration], duration].max
+        }
+      end
+    end
+
+    def slot_scale(slot, global_cps)
+      slot_cps = slot[:cps]
+      return Rational(1) unless slot_cps&.positive?
+
+      Rational(slot_cps.to_r) / Rational(global_cps.to_r)
+    end
+
+    def map_slot_event(event, scale, phase)
+      return event if scale == 1 && phase.zero?
+
+      Pattern.map_event(event) { |time| (time - phase) / scale }
+    end
+
+    def normalize_cps(value)
+      normalized = value.to_f
+      raise ArgumentError, "cps must be positive" unless normalized.positive?
+
+      normalized
     end
 
     def time_to_cycle(time, cps_value, start_cycle, start_monotonic)
       start_cycle + ((time - start_monotonic) * cps_value)
     end
 
-    def log_runtime_error(error)
-      @logger&.call("[Cyclotone::Scheduler] #{error.class}: #{error.message}")
+    def log_runtime_error(error, slot_id: nil)
+      @mutex.synchronize { @last_error = error }
+      slot = slot_id ? " slot=#{slot_id}" : ""
+      @logger&.call("[Cyclotone::Scheduler#{slot}] #{error.class}: #{error.message}")
     end
   end
 end

data/lib/cyclotone/state.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require "singleton"
-require "thread"
 
 module Cyclotone
   class State

data/lib/cyclotone/stream.rb

@@ -1,34 +1,60 @@
 # frozen_string_literal: true
 
-require "singleton"
 require "set"
 
 module Cyclotone
   class Stream
-    include Singleton
     include Transition
 
-    attr_reader :scheduler
+    class << self
+      def instance
+        @instance ||= new
+      end
+    end
+
+    attr_reader :scheduler, :fallback_error
 
-    def initialize
+    NullBackend = Backends::NullBackend
+
+    def initialize(backend: nil, scheduler: nil)
       @slots = {}
+      @slot_options = {}
+      @transitions = {}
       @muted = Set.new
       @soloed = Set.new
-      @scheduler = Scheduler.new(backend: Backends::OSCBackend.new(socket: UDPSocket.new))
-    rescue StandardError
-      @scheduler = Scheduler.new(backend: NullBackend.new)
-    end
-
-    def d(slot_id, pattern)
-      assign(normalize_d_slot_id(slot_id), pattern)
-    end
-
-    def p(name, pattern)
-      assign(normalize_slot_reference(name), pattern)
-    end
+      @fallback_error = nil
+      @scheduler = scheduler || Scheduler.new(backend: backend || default_backend)
+    rescue StandardError => error
+      @fallback_error = error
+      @scheduler = Scheduler.new(backend: Backends::NullBackend.new)
+    end
+
+    def d(slot_id, pattern, cps: nil, phase: 0)
+      assign(normalize_d_slot_id(slot_id), pattern, cps: cps, phase: phase)
+    end
+
+    def p(name, pattern, cps: nil, phase: 0)
+      assign(normalize_slot_reference(name), pattern, cps: cps, phase: phase)
+    end
+
+    def hush(mode: :silence)
+      case mode
+      when :silence
+        @slots.each_key { |slot_id| assign(slot_id, Pattern.silence) }
+      when :mute
+        @muted.merge(@slots.keys)
+        sync_scheduler
+      when :clear
+        @slots.each_key { |slot_id| @scheduler.remove_pattern(slot_id) }
+        @slots.clear
+        @slot_options.clear
+        @transitions.clear
+        @muted.clear
+        @soloed.clear
+      else
+        raise ArgumentError, "unknown hush mode #{mode}"
+      end
 
-    def hush
-      @slots.keys.each { |slot_id| assign(slot_id, Pattern.silence) }
       self
     end
 
@@ -95,7 +121,9 @@ module Cyclotone
     end
 
     def mtrigger(period)
-      normalized_period = [period.to_i, 1].max
+      normalized_period = period.to_i
+      raise ArgumentError, "mtrigger period must be positive" unless normalized_period.positive?
+
       current_cycle = @scheduler.current_cycle
       next_cycle = current_cycle.ceil
       remainder = next_cycle % normalized_period
@@ -105,43 +133,71 @@ module Cyclotone
     end
 
     def slot(slot_id)
-      @slots[normalize_slot_reference(slot_id)]
+      normalized = normalize_slot_reference(slot_id)
+      simplify_completed_transition(normalized)
+      @slots[normalized]
     end
 
     private
 
-    def assign(slot_id, pattern)
+    def assign(slot_id, pattern, cps: nil, phase: 0)
       @slots[slot_id] = normalize_pattern(pattern)
+      @slot_options[slot_id] = { cps: cps, phase: phase }
+      @transitions.delete(slot_id)
       sync_scheduler
       @slots[slot_id]
     end
 
-    def normalize_pattern(pattern)
-      return pattern if pattern.is_a?(Pattern)
-      return Pattern.mn(pattern) if pattern.is_a?(String)
+    def assign_transition(slot_id, pattern, replacement:, finish_cycle:)
+      @slots[slot_id] = normalize_pattern(pattern)
+      @transitions[slot_id] = { replacement: replacement, finish_cycle: finish_cycle }
+      sync_scheduler
+      @slots[slot_id]
+    end
 
-      Pattern.pure(pattern)
+    def pattern_for_transition(slot_id)
+      simplify_completed_transition(slot_id)
+      @slots[slot_id] || Pattern.silence
     end
 
-    def normalize_d_slot_id(slot_id)
-      raw = slot_id.to_s
-      return raw.to_sym if raw.match?(/\Ad\d+\z/)
-      return :"d#{raw}" if raw.match?(/\A\d+\z/)
+    def simplify_completed_transition(slot_id)
+      transition = @transitions[slot_id]
+      return unless transition
+      return if @scheduler.current_cycle < transition[:finish_cycle].to_f
+
+      @slots[slot_id] = transition[:replacement]
+      @transitions.delete(slot_id)
+      sync_scheduler
+    end
+
+    def normalize_pattern(pattern)
+      Pattern.ensure_pattern(pattern, strings: :mini_notation)
+    end
 
-      :"d#{raw}"
+    def normalize_d_slot_id(slot_id)
+      normalize_slot_id(slot_id, force_d: true)
     end
 
     def normalize_slot_reference(slot_id)
+      normalize_slot_id(slot_id, force_d: false)
+    end
+
+    def normalize_slot_id(slot_id, force_d:)
       raw = slot_id.to_s
       return raw.to_sym if raw.match?(/\Ad\d+\z/)
       return :"d#{raw}" if raw.match?(/\A\d+\z/)
 
-      raw.to_sym
+      force_d ? :"d#{raw}" : raw.to_sym
+    end
+
+    def default_backend
+      Backends::OSCBackend.new(socket: UDPSocket.new)
     end
 
     def sync_scheduler
       active_slots.each do |slot_id, pattern|
-        @scheduler.update_pattern(slot_id, pattern)
+        options = @slot_options.fetch(slot_id, {})
+        @scheduler.update_pattern(slot_id, pattern, cps: options[:cps], phase: options[:phase] || 0)
       end
 
       inactive_slots.each do |slot_id|
@@ -153,7 +209,7 @@ module Cyclotone
 
     def active_slots
       if @soloed.empty?
-        @slots.reject { |slot_id, _| @muted.include?(slot_id) }
+        @slots.except(*@muted)
       else
         @slots.select { |slot_id, _| @soloed.include?(slot_id) && !@muted.include?(slot_id) }
       end
@@ -164,22 +220,12 @@ module Cyclotone
     end
 
     def wait_until_cycle(target_cycle)
+      return self unless @scheduler.running?
+
       cycles_remaining = target_cycle.to_f - @scheduler.current_cycle
       seconds = cycles_remaining / @scheduler.cps
       sleep(seconds) if seconds.positive?
       self
     end
-
-    class NullBackend
-      attr_reader :events
-
-      def initialize
-        @events = []
-      end
-
-      def send_event(event, at:, **options)
-        @events << { event: event, at: at, options: options }
-      end
-    end
   end
 end

data/lib/cyclotone/support/deterministic.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "digest"
+
 module Cyclotone
   module Support
     module Deterministic
@@ -7,10 +9,14 @@ module Cyclotone
 
       def seed_for(*parts)
         parts.flatten.compact.reduce(17) do |memo, part|
-          ((memo * 31) ^ normalize(part).hash) & 0xFFFFFFFF
+          ((memo * 31) ^ stable_hash(normalize(part))) & 0xFFFFFFFF
         end
       end
 
+      def canonical_key(value)
+        canonical_dump(normalize(value))
+      end
+
       def random(*parts)
         Random.new(seed_for(*parts))
       end
@@ -37,6 +43,36 @@ module Cyclotone
           value
         end
       end
+
+      private_class_method def self.stable_hash(value)
+        Digest::SHA256.digest(canonical_dump(value)).unpack1("N")
+      end
+
+      private_class_method def self.canonical_dump(value)
+        case value
+        when NilClass
+          "nil"
+        when TrueClass, FalseClass
+          "bool:#{value}"
+        when Integer
+          "int:#{value}"
+        when Float
+          "float:#{value}"
+        when Symbol
+          "sym:#{value}"
+        when String
+          "str:#{value.bytesize}:#{value}"
+        when Array
+          "arr:[#{value.map { |entry| canonical_dump(entry) }.join(",")}]"
+        when Hash
+          entries = value.sort_by { |key, _| canonical_dump(key) }.map do |key, entry|
+            "#{canonical_dump(key)}=>#{canonical_dump(entry)}"
+          end
+          "hash:{#{entries.join(",")}}"
+        else
+          "#{value.class.name}:#{value.inspect}"
+        end
+      end
     end
   end
 end

data/lib/cyclotone/time_span.rb

@@ -26,8 +26,9 @@ module Cyclotone
     end
 
     def intersection(other)
-      intersection_start = [start, other.start].max
-      intersection_stop = [stop, other.stop].min
+      other_span = coerce_span(other)
+      intersection_start = [start, other_span.start].max
+      intersection_stop = [stop, other_span.stop].min
 
       return nil if intersection_start >= intersection_stop
 
@@ -39,19 +40,27 @@ module Cyclotone
       start <= normalized_time && normalized_time < stop
     end
 
-    def cycle_spans
-      return [] if duration.zero?
+    def each_cycle_span(max_cycles: nil)
+      return enum_for(:each_cycle_span, max_cycles: max_cycles) unless block_given?
+      return self if duration.zero?
 
-      spans = []
       current_start = start
+      emitted = 0
 
       while current_start < stop
+        raise ArgumentError, "span crosses more than #{max_cycles} cycles" if max_cycles && emitted >= max_cycles
+
         cycle_boundary = [Rational(current_start.floor + 1), stop].min
-        spans << self.class.new(current_start, cycle_boundary)
+        yield self.class.new(current_start, cycle_boundary)
         current_start = cycle_boundary
+        emitted += 1
       end
 
-      spans
+      self
+    end
+
+    def cycle_spans(max_cycles: nil)
+      each_cycle_span(max_cycles: max_cycles).to_a
     end
 
     def shift(amount)
@@ -62,6 +71,7 @@ module Cyclotone
 
     def scale(factor)
       normalized_factor = coerce_time(factor)
+      raise ArgumentError, "scale factor must be non-negative" if normalized_factor.negative?
 
       self.class.new(start * normalized_factor, stop * normalized_factor)
     end
@@ -69,6 +79,8 @@ module Cyclotone
     def reverse_within(cycle_start, cycle_length = 1)
       normalized_start = coerce_time(cycle_start)
       normalized_length = coerce_time(cycle_length)
+      raise ArgumentError, "cycle length must be positive" unless normalized_length.positive?
+
       mirror = (normalized_start * 2) + normalized_length
 
       self.class.new(mirror - stop, mirror - start)
@@ -92,8 +104,18 @@ module Cyclotone
 
     def coerce_time(value)
       return value if value.is_a?(Rational)
+      return Rational(value.to_s) if value.is_a?(Float)
 
       Rational(value)
+    rescue ArgumentError, TypeError => error
+      raise ArgumentError, "invalid time value #{value.inspect}: #{error.message}"
+    end
+
+    def coerce_span(value)
+      return value if value.is_a?(self.class)
+      return self.class.new(value.fetch(0), value.fetch(1)) if value.respond_to?(:fetch)
+
+      raise ArgumentError, "expected #{self.class}, got #{value.class}"
     end
   end
 end