musa-dsl 0.42.5 → 0.42.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ce1f988b99c9aa0a48313adf5e0f67a1c38fedb82a1ec8f14f1b628b9a1658d0
-  data.tar.gz: 3415ebc9842ee9fbe09f586206ac241efe0560a98e1170e5b9115247883a2c23
+  metadata.gz: 88eb7916fe255e3b5d72520d25d4057252c41f24926975659712668a43c0cc41
+  data.tar.gz: 7fbe17e6453b42f4729104e47392c7b4819436de0bf0e64fd28505f0e936e76f
 SHA512:
-  metadata.gz: 3a886f0ad181adf8cc0fbb11da1677539a488a54f5b61502ef53c29b9a0ebd2483c79ea5a5031d22a04f1269f5c5979eb1fd6af80c21bd7e4fc937c58198ebeb
-  data.tar.gz: efb5db224fc2bea5439c136d7981c342b98c587a7c2ee50865ffa0677d638d4065c9a1dfb1ea7570c267fec1a2b46bd7cdec1b9a763928fa37742696b94caeb4
+  metadata.gz: 25514b23a820ff8ec8f2f99c6e607dcec8879db85d030e3d3e19398a26ea63f3c81752d7e839eefb27e6a640b355aa0b58fb0a43b6f076f79b59e2303bf00e8d
+  data.tar.gz: f89fbbf88a3f62f455dcf6cb342f47f324c1c4c93c225fcc45ba86f766e31a3300cacd7a3ff379698e97a201594a0e1610357cd20e843a4d797997c551b9c758

data/docs/subsystems/transport.md

@@ -89,13 +89,15 @@ dummy_clock = Musa::Clock::DummyClock.new(100)
 
 ### Clean Shutdown
 
-To cleanly terminate a transport using TimerClock:
+`transport.stop` triggers the complete lifecycle shutdown sequence, consistently across all clock types:
 
-1. Call `transport.stop` from within a scheduled event
-2. This calls `clock.terminate` internally
-3. The clock's run loop exits
-4. `transport.start` returns
-5. Your code continues after `transport.start` for cleanup
+1. `transport.stop` calls `clock.terminate`
+2. `clock.terminate` calls `clock.stop` (fires `on_stop` callbacks)
+3. Transport's `on_stop` handler executes `after_stop` callbacks
+4. Sequencer is reset
+5. `before_begin` callbacks run (preparing for potential restart)
+6. Clock's run loop exits
+7. `transport.start` returns
 
 ```ruby
 # Example: Self-terminating composition
@@ -109,9 +111,12 @@ puts "Cleanup..."  # Executes after stop
 output.close
 ```
 
-**Note:** For `InputMidiClock`, stop/start cycles are controlled by the DAW
-and don't terminate the process. The `terminate` method can be used explicitly
-if you need the run loop to exit.
+**Clock `stop` vs `terminate` contract:**
+
+- **`stop`**: Fires `on_stop` callbacks. Idempotent (second call is a no-op). All clocks implement it.
+- **`terminate`**: Calls `stop` first (guarantees callbacks), then exits the run loop. All clocks implement it.
+
+**Note:** For `InputMidiClock`, MIDI Stop messages from the DAW also trigger `clock.stop` (and thus `on_stop` callbacks). To fully exit the run loop, call `clock.terminate` or `transport.stop`.
 
 **Key methods:**
 - `start` - Start playback (blocks while running)

data/lib/musa-dsl/transport/clock.rb

@@ -42,13 +42,15 @@ module Musa
     # Concrete clocks must:
     #
     # 1. Implement `run(&block)` - Start generating ticks, yield for each tick
-    # 2. Implement `terminate` - Stop the clock
-    # 3. Call registered callbacks at appropriate times
+    # 2. Override `stop` if additional cleanup is needed (call super)
+    # 3. Override `terminate` to call `stop` then exit the run loop
     # 4. Manage @run state properly
+    # 5. Reset `@stopped = false` at the start of `run` (and in `start` if applicable)
     #
     # @example Creating a simple clock subclass
     #   class SimpleClock < Clock
     #     def run
+    #       @stopped = false
     #       @run = true
     #       @on_start.each(&:call)
     #
@@ -57,11 +59,12 @@ module Musa
     #         sleep 0.1
     #       end
     #
-    #       @on_stop.each(&:call)
+    #       stop  # Fires on_stop callbacks (idempotent)
     #     end
     #
     #     def terminate
-    #       @run = false
+    #       stop         # Ensures on_stop callbacks fire
+    #       @run = false # Exits the run loop
     #     end
     #   end
     #
@@ -70,6 +73,7 @@ module Musa
       # Initializes the clock with empty callback collections.
       def initialize
         @run = nil
+        @stopped = false
         @on_start = []
         @on_stop = []
         @on_change_position = []
@@ -82,6 +86,20 @@ module Musa
         @run
       end
 
+      # Stops the clock and fires on_stop callbacks.
+      #
+      # Idempotent: calling stop multiple times only fires callbacks once.
+      # Subclasses that need additional stop logic (e.g., pausing a timer)
+      # should override and call super.
+      #
+      # @return [void]
+      def stop
+        return if @stopped
+
+        @stopped = true
+        @on_stop.each(&:call)
+      end
+
       # Registers a callback to be called when the clock starts.
       #
       # Multiple callbacks can be registered and will be called in order.
@@ -132,6 +150,9 @@ module Musa
       # This method should block and yield once per tick. Subclasses must
       # implement this method.
       #
+      # Subclasses should reset `@stopped = false` at the start of `run`
+      # to allow stop/start cycles.
+      #
       # @yield Called once per tick to advance the sequencer.
       # @return [void]
       #
@@ -139,20 +160,22 @@ module Musa
       #
       # @note This method typically runs in a loop until {#terminate} is called.
       # @note Subclasses should call @on_start callbacks when starting.
-      # @note Subclasses should call @on_stop callbacks when stopping.
+      # @note Subclasses should call {#stop} (not @on_stop directly) when stopping.
       def run
         raise NotImplementedError
       end
 
       # Stops the clock and terminates the run loop.
       #
-      # Subclasses must implement this method to cleanly stop the clock.
+      # Calls {#stop} to ensure on_stop callbacks fire, then exits the run loop.
+      # Subclasses must implement this method.
       #
       # @return [void]
       #
       # @raise [NotImplementedError] if not overridden by subclass.
       #
       # @note After calling this, {#run} should exit.
+      # @note Must call {#stop} to guarantee on_stop callbacks fire.
       def terminate
         raise NotImplementedError
       end

data/lib/musa-dsl/transport/dummy-clock.rb

@@ -89,7 +89,7 @@ module Musa
       #
       # Calls on_start callbacks, then yields while the condition is true.
       # Uses Thread.pass instead of sleep for fast operation.
-      # Calls on_stop callbacks when done.
+      # Calls {#stop} when done (idempotent).
       #
       # @yield Called once per tick
       # @return [void]
@@ -98,6 +98,7 @@ module Musa
       def run
         @on_start.each(&:call)
         @run = true
+        @stopped = false
 
         while @run && eval_condition
           yield if block_given?
@@ -105,14 +106,25 @@ module Musa
           Thread.pass  # Cooperate with other threads
         end
 
-        @on_stop.each(&:call)
+        stop  # Idempotent: if terminate already called stop, this is a no-op
+      end
+
+      # Stops the clock and fires on_stop callbacks.
+      #
+      # @return [void]
+      def stop
+        @run = false
+        super
       end
 
       # Terminates the clock loop.
       #
+      # Calls {#stop} to ensure on_stop callbacks fire, then ensures the
+      # run loop exits.
+      #
       # @return [void]
       def terminate
-        @run = false
+        stop
       end
 
       private

data/lib/musa-dsl/transport/external-tick-clock.rb

@@ -91,6 +91,7 @@ module Musa
       #
       # @note This method does NOT block
       def run(&block)
+        @stopped = false
         @on_start.each(&:call)
         @run = true
         @block = block
@@ -111,12 +112,21 @@ module Musa
         end
       end
 
-      # Terminates the clock and calls on_stop callbacks.
+      # Stops the clock and fires on_stop callbacks.
       #
       # @return [void]
-      def terminate
-        @on_stop.each(&:call)
+      def stop
         @run = false
+        super
+      end
+
+      # Terminates the clock.
+      #
+      # Delegates to {#stop} which fires on_stop callbacks and sets @run to false.
+      #
+      # @return [void]
+      def terminate
+        stop
       end
     end
   end

data/lib/musa-dsl/transport/input-midi-clock.rb

@@ -146,6 +146,7 @@ module Musa
       # @note Waits if no input assigned
       def run
         @run = true
+        @stopped = false
 
         while @run
           if @input
@@ -218,10 +219,21 @@ module Musa
         end
       end
 
+      # Stops the clock and fires on_stop callbacks.
+      #
+      # @return [void]
+      def stop
+        @started = false
+        super
+      end
+
       # Terminates the MIDI Clock processing loop.
       #
+      # Calls {#stop} to ensure on_stop callbacks fire, then exits the run loop.
+      #
       # @return [void]
       def terminate
+        stop
         @run = false
       end
 
@@ -235,6 +247,7 @@ module Musa
       def process_start
         @logger.debug('InputMidiClock') { 'processing Start...' }
 
+        @stopped = false
         @on_start.each(&:call)
         @started = true
 
@@ -259,10 +272,7 @@ module Musa
 
         when 'Stop'
           @logger.debug('InputMidiClock') { 'processing Stop...' }
-
-          @on_stop.each(&:call)
-          @started = false
-
+          stop
           @logger.debug('InputMidiClock') { 'processing Stop... done' }
 
         when 'Continue'

data/lib/musa-dsl/transport/timer-clock.rb

@@ -195,6 +195,7 @@ module Musa
       # @note Clock begins paused; call {#start} to begin ticking
       def run
         @run = true
+        @stopped = false
 
         while @run
           @timer = Timer.new(@period,
@@ -221,6 +222,7 @@ module Musa
       # @note Calls registered on_start callbacks
       def start
         unless @started
+          @stopped = false
           @on_start.each(&:call)
           @started = true
           @paused = false
@@ -230,20 +232,19 @@ module Musa
 
       # Stops the clock and resets to initial state.
       #
-      # Triggers @on_stop callbacks and marks clock as not started.
-      # Has no effect if not currently started.
+      # Stops the internal timer, resets state flags, and fires on_stop
+      # callbacks via super (idempotent).
       #
       # @return [void]
       #
-      # @note Calls registered on_stop callbacks
       # @note Different from {#pause}: stop resets to initial state
       def stop
         if @started
           @timer.stop
           @started = false
           @paused = false
-          @on_stop.each(&:call)
         end
+        super
       end
 
       # Pauses the clock without stopping it.
@@ -279,13 +280,14 @@ module Musa
 
       # Terminates the clock's run loop.
       #
-      # Causes {#run} to exit by setting the run flag to false and terminating
-      # the internal timer. This is the clean shutdown mechanism.
+      # Calls {#stop} to ensure on_stop callbacks fire, then exits the run loop
+      # by terminating the internal timer.
       #
       # @return [void]
       #
       # @note After calling this, {#run} will exit and {Musa::Transport::Transport#start} will return
       def terminate
+        stop
         @run = false
         @timer&.terminate
       end

data/lib/musa-dsl/version.rb

@@ -1,3 +1,3 @@
 module Musa
-  VERSION = '0.42.5'.freeze
+  VERSION = '0.42.6'.freeze
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: musa-dsl
 version: !ruby/object:Gem::Version
-  version: 0.42.5
+  version: 0.42.6
 platform: ruby
 authors:
 - Javier Sánchez Yeste