musa-dsl 0.42.2 → 0.42.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 12fab469b50ab2d8c92ce166859645d8c30ad655e2ae339aa9b8c0254cc59253
-  data.tar.gz: 87aa5596a08c21f0b17ed7f6758b708a3473f9e8078020b7cf564b2149f6823a
+  metadata.gz: 5b00aaa2474967b2283adc187b2bd8696b96a83ba98b5868c8479f69e1efa195
+  data.tar.gz: bf3e363b1160ae7787a9a64d1bd96cd8c2735d80a39449268f01bff1af57d8e9
 SHA512:
-  metadata.gz: 38b45b016289a63870ada189d4ea91f9749754997ad4e250b5d24b1ea47c001741696e71eef8ce13dfeb4e6753caf213f970861fbbff2edbcee8f18504a9e03e
-  data.tar.gz: 6a14e6306e5f3945fa5e5febfa223fd1aece1cbff1d0ed8533a5a54231646bfddf96489a572d8aae1adbeb6b0dbbaee1f3aa1ef9effa8095c051378b145bde9a
+  metadata.gz: 19349d6b67aac7e4e00f95d1da0c7b59b1f3d8c4bbb7ea6dd9d92d335f416b4ac0ceebc4647389d8fa901a763e3af2e6443281f5dfa7268f155be1503b2fec2a
+  data.tar.gz: e90b0fac158af0990e6fccffbb683001b5f7d641775a5678fe879d16ba905002c5817e56b089977e28632090a54f69be95ddf578f780db3c93d2caf05931dd40

data/docs/subsystems/sequencer.md

@@ -102,7 +102,11 @@ every 1/4r do ... end
 at 0.5 do ... end
 ```
 
-## Control Callbacks: `on_stop` vs `after`
+## Control Objects and `.stop`
+
+All scheduling methods (`at`, `wait`, `now`, `play`, `play_timed`, `every`, `move`) return a control object that supports `.stop` to cancel execution. Calling `.stop` on the control prevents the associated block from running at its scheduled position, or stops further iterations for series/recurring operations.
+
+### `on_stop` vs `after` callbacks
 
 The control objects returned by `every`, `play`, `play_timed`, and `move` support two types of callbacks with different semantics:
 
@@ -153,6 +157,46 @@ ctrl.on_stop { puts "Fade ended" }     # Any reason
 ctrl.after { launch :next_section }     # Only if fade completes
 ```
 
+### Stopping `at`, `wait`, `now` and `play_timed`
+
+All scheduling methods return a control object that supports `.stop`:
+
+```ruby
+# Stop a scheduled at/wait/now before it executes
+h = at 5 do
+  puts "This won't execute if stopped before bar 5"
+end
+
+at 3 do
+  h.stop  # Cancels the block scheduled at bar 5
+end
+```
+
+```ruby
+# Stop a series-based at/wait
+h = at [1, 2, 3, 4, 5] do
+  puts "Repeating at positions from series"
+end
+
+at 3.5 do
+  h.stop  # No more executions from the series after this point
+end
+```
+
+```ruby
+# Stop play_timed — same on_stop/after semantics as play/every/move
+ctrl = play_timed(timed_serie) do |values, time:, started_ago:, control:|
+  # process values
+end
+
+ctrl.on_stop { puts "Stopped (any reason)" }
+ctrl.after { launch :next_section }  # Only on natural end
+
+at 10 do
+  ctrl.stop  # on_stop fires, after does NOT
+end
+```
+
 ### Parameter form
 
 `on_stop` and `after` can also be passed as parameters:

data/lib/musa-dsl/sequencer/base-sequencer-implementation-play-timed.rb

@@ -79,7 +79,7 @@ module Musa::Sequencer
                                  last_positions,
                                  binder, control)
 
-      source_next_value = timed_serie.next_value
+      source_next_value = control.stopped? ? nil : timed_serie.next_value
 
       if source_next_value
         affected_components = component_ids.select { |_| !source_next_value[:value][_].nil? }
@@ -109,11 +109,13 @@ module Musa::Sequencer
           end
 
           _numeric_at _quantize_position(start_position + time, warn: true), control do
-            binder.call(values,
-                        **extra_attributes,
-                        time: start_position + time,
-                        started_ago: started_ago,
-                        control: control)
+            unless control.stopped?
+              binder.call(values,
+                          **extra_attributes,
+                          time: start_position + time,
+                          started_ago: started_ago,
+                          control: control)
+            end
 
             _play_timed_step(hash_mode,
                              component_ids, extra_attribute_names,

data/lib/musa-dsl/sequencer/base-sequencer-implementation.rb

@@ -19,12 +19,21 @@ module Musa::Sequencer
     #
     #    - Shifts command from queue
     #    - Deletes timeslot if queue becomes empty
-    #    - Pushes parent_control to event handler stack if present
-    #    - Executes command block with parameters (mutex-protected)
+    #    - Pushes parent_control to event handler stack if present and not stopped
+    #    - If command has skip_if_stopped and control is stopped, skips block execution
+    #    - Otherwise executes command block with parameters (mutex-protected)
     #    - Pops parent_control from stack
     #
     # 4. Yields to other threads
     #
+    # ## skip_if_stopped
+    #
+    # Commands scheduled with `skip_if_stopped: true` (via `_numeric_at`) are
+    # silently skipped when their control is stopped. Used by `at`, `wait`, `now`
+    # and `_serie_at` which have no cleanup logic. Not used by `play`, `every`,
+    # `move` or `play_timed` whose blocks mix user callbacks with cleanup/recursion
+    # that must execute even when stopped.
+    #
     # @param position_to_run [Rational] position to execute events at
     #
     # @return [void]
@@ -43,8 +52,10 @@ module Musa::Sequencer
 
           @event_handlers.push(command[:parent_control]) if push_parent
 
-          @tick_mutex.synchronize do
-            command[:block]&.call *command[:value_parameters], **command[:key_parameters]
+          unless command[:skip_if_stopped] && command[:parent_control]&.stopped?
+            @tick_mutex.synchronize do
+              command[:block]&.call *command[:value_parameters], **command[:key_parameters]
+            end
           end
 
           @event_handlers.pop if push_parent
@@ -65,7 +76,7 @@ module Musa::Sequencer
     # @param force_first [Boolean] if true, insert at front of queue
     # @yield block to execute at position
     #
-    # @return [nil]
+    # @return [void]
     #
     # @example Force execution order
     #   _raw_numeric_at(1r) { puts "second" }
@@ -115,9 +126,23 @@ module Musa::Sequencer
     # - **Past position**: Warns and ignores
     # - **nil position** (tickless before first event): Allows scheduling
     #
+    # ## skip_if_stopped
+    #
+    # When `skip_if_stopped: true`, the block is silently skipped if `control`
+    # is stopped at execution time. This applies both for immediate execution
+    # (current position) and for future execution (checked in `_tick`).
+    # Used by `at`, `wait`, `now` and `_serie_at` for clean cancellation
+    # without wrapper procs or extra SmartProcBinder overhead.
+    #
+    # Not suitable for `play`/`every`/`move`/`play_timed` whose scheduled
+    # blocks contain cleanup logic (do_on_stop, do_after) that must run
+    # even when stopped.
+    #
     # @param at_position [Rational] position to schedule at
     # @param control [EventHandler] parent control for hierarchy
     # @param debug [Boolean, nil] enable debug callbacks
+    # @param skip_if_stopped [Boolean, nil] when true, skip block execution
+    #   if control is stopped. Used by at/wait/now/_serie_at.
     # @yield block to execute at position (may accept control:)
     #
     # @return [nil]
@@ -125,7 +150,7 @@ module Musa::Sequencer
     # @raise [ArgumentError] if at_position is nil or block not given
     #
     # @api private
-    private def _numeric_at(at_position, control, debug: nil, &block)
+    private def _numeric_at(at_position, control, debug: nil, skip_if_stopped: nil, &block)
       raise ArgumentError, "'at_position' parameter cannot be nil" if at_position.nil?
       raise ArgumentError, 'Yield block is mandatory' unless block
 
@@ -140,11 +165,13 @@ module Musa::Sequencer
       if at_position == @position
         @on_debug_at.each(&:call) if @logger.sev_threshold >= ::Logger::Severity::DEBUG
 
-        begin
-          locked = @tick_mutex.try_lock
-          block_key_parameters_binder._call(nil, key_parameters)
-        ensure
-          @tick_mutex.unlock if locked
+        unless skip_if_stopped && control.stopped?
+          begin
+            locked = @tick_mutex.try_lock
+            block_key_parameters_binder._call(nil, key_parameters)
+          ensure
+            @tick_mutex.unlock if locked
+          end
         end
 
       elsif @position.nil? || at_position > @position
@@ -159,7 +186,8 @@ module Musa::Sequencer
 
         @timeslots[at_position] << { parent_control: control,
                                      block: block_key_parameters_binder,
-                                     key_parameters: key_parameters }
+                                     key_parameters: key_parameters,
+                                     skip_if_stopped: skip_if_stopped }
       else
         @logger.warn('BaseSequencer') { "._numeric_at: ignoring past 'at' command for #{at_position}" }
       end
@@ -201,9 +229,9 @@ module Musa::Sequencer
       bar_position = position_or_serie.next_value
 
       if bar_position
-        _numeric_at bar_position, control, debug: debug, &block
+        _numeric_at bar_position, control, debug: debug, skip_if_stopped: true, &block
 
-        _numeric_at bar_position, control, debug: false do
+        _numeric_at bar_position, control, debug: false, skip_if_stopped: true do
           _serie_at position_or_serie, control, debug: debug, &block
         end
       else

data/lib/musa-dsl/sequencer/base-sequencer.rb

@@ -522,13 +522,22 @@ module Musa
 
       # Schedules block relative to current position.
       #
+      # Returns a control object whose `.stop` method cancels execution:
+      # the block will not run if the control is stopped before its scheduled
+      # position. For series-based delays, `.stop` also prevents further
+      # elements from being scheduled.
+      #
       # @param bars_delay [Numeric, Series, Array] delay from current position
       # @param debug [Boolean] enable debug logging
       # @yield block to execute at position + delay
-      # @return [EventHandler] control object
+      # @return [EventHandler] control object (supports .stop to cancel)
       #
-      # @example
+      # @example Basic wait
       #   seq.wait(2) { puts "2 beats later" }
+      #
+      # @example Cancelling a scheduled wait
+      #   h = seq.wait(4) { puts "won't run" }
+      #   h.stop
       def wait(bars_delay, debug: nil, &block)
         debug ||= false
 
@@ -536,7 +545,7 @@ module Musa
         @event_handlers.push control
 
         if bars_delay.is_a? Numeric
-          _numeric_at position + bars_delay.rationalize, control, debug: debug, &block
+          _numeric_at position + bars_delay.rationalize, control, debug: debug, skip_if_stopped: true, &block
         else
           bars_delay = Series::S(*bars_delay) if bars_delay.is_a?(Array)
           bars_delay = bars_delay.instance if bars_delay
@@ -551,8 +560,12 @@ module Musa
 
       # Schedules block at current position (immediate execution on next tick).
       #
+      # Returns a control object whose `.stop` method cancels execution
+      # if the block hasn't run yet (e.g., scheduled at current position
+      # but not yet reached by the tick loop).
+      #
       # @yield block to execute at current position
-      # @return [EventHandler] control object
+      # @return [EventHandler] control object (supports .stop to cancel)
       #
       # @example
       #   seq.now { puts "Executes now" }
@@ -560,7 +573,7 @@ module Musa
         control = EventHandler.new @event_handlers.last
         @event_handlers.push control
 
-        _numeric_at position, control, &block
+        _numeric_at position, control, skip_if_stopped: true, &block
 
         @event_handlers.pop
 
@@ -582,16 +595,25 @@ module Musa
 
       # Schedules block at absolute position.
       #
+      # Returns a control object whose `.stop` method cancels execution:
+      # the block will not run if the control is stopped before the scheduled
+      # position. For series-based positions, `.stop` also prevents further
+      # elements from being scheduled.
+      #
       # @param bar_position [Numeric, Series, Array] absolute position(s)
       # @param debug [Boolean] enable debug logging
       # @yield block to execute at position
-      # @return [EventHandler] control object
+      # @return [EventHandler] control object (supports .stop to cancel)
       #
       # @example Single position
       #   seq.at(4) { puts "At beat 4" }
       #
       # @example Series of positions
       #   seq.at([1, 2, 3.5, 4]) { |pos| puts "At #{pos}" }
+      #
+      # @example Cancelling a scheduled at
+      #   h = seq.at(8) { puts "won't run" }
+      #   h.stop
       def at(bar_position, debug: nil, &block)
         debug ||= false
 
@@ -599,7 +621,7 @@ module Musa
         @event_handlers.push control
 
         if bar_position.is_a? Numeric
-          _numeric_at bar_position.rationalize, control, debug: debug, &block
+          _numeric_at bar_position.rationalize, control, debug: debug, skip_if_stopped: true, &block
         else
           bar_position = Series::S(*bar_position) if bar_position.is_a? Array
           bar_position = bar_position.instance if bar_position

data/lib/musa-dsl/sequencer/sequencer-dsl.rb

@@ -222,7 +222,7 @@ module Musa
       #   @param value_parameters [Array] parameters to pass to block
       #   @param key_parameters [Hash] keyword parameters
       #   @yield block to execute now
-      #   @return [void]
+      #   @return [EventHandler] control object
 
       # @!method at(position, *value_parameters, **key_parameters, &block)
       #   Schedules block to execute at specified position.
@@ -233,7 +233,7 @@ module Musa
       #   @param value_parameters [Array] parameters to pass to block
       #   @param key_parameters [Hash] keyword parameters
       #   @yield block to execute at position
-      #   @return [void]
+      #   @return [EventHandler] control object
 
       # @!method wait(duration, *value_parameters, **key_parameters, &block)
       #   Schedules block after waiting specified duration.
@@ -244,7 +244,7 @@ module Musa
       #   @param value_parameters [Array] parameters to pass to block
       #   @param key_parameters [Hash] keyword parameters
       #   @yield block to execute after wait
-      #   @return [void]
+      #   @return [EventHandler] control object
 
       # @!method play(serie, decoder: nil, mode: nil, **options, &block)
       #   Plays a series using the decoder.
@@ -596,7 +596,7 @@ module Musa
         # @param value_parameters [Array] parameters to pass to block
         # @param key_parameters [Hash] keyword parameters
         # @yield block to execute at current position
-        # @return [void]
+        # @return [EventHandler] control object
         def now(*value_parameters, **key_parameters, &block)
           block ||= proc {}
 
@@ -612,7 +612,7 @@ module Musa
         # @param value_parameters [Array] parameters (first is position)
         # @param key_parameters [Hash] keyword parameters
         # @yield block to execute at position
-        # @return [void]
+        # @return [EventHandler] control object
         def at(*value_parameters, **key_parameters, &block)
           block ||= proc {}
 
@@ -628,7 +628,7 @@ module Musa
         # @param value_parameters [Array] parameters (first is duration)
         # @param key_parameters [Hash] keyword parameters
         # @yield block to execute after wait
-        # @return [void]
+        # @return [EventHandler] control object
         def wait(*value_parameters, **key_parameters, &block)
           block ||= proc {}
           @sequencer.wait *value_parameters, **key_parameters do |*values, **key_values|

data/lib/musa-dsl/version.rb

@@ -1,3 +1,3 @@
 module Musa
-  VERSION = '0.42.2'.freeze
+  VERSION = '0.42.3'.freeze
 end

metadata

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