Class: Musa::Sequencer::BaseSequencer::EveryControl

Inherits:
EventHandler show all
Defined in:
lib/musa-dsl/sequencer/base-sequencer-implementation-every.rb

Overview

Control object for every loops.

Manages lifecycle of every loop including stopping conditions, callbacks, and execution tracking. Extends EventHandler to support event-based control (e.g., launching custom events).

Stopping Conditions

  • duration: Maximum loop duration in bars
  • till: Absolute position to stop at
  • condition: Proc returning true to continue, false to stop
  • manual stop: Call control.stop to halt loop

Callbacks

  • on_stop: Called when loop stops (any reason, including manual stop)
  • after: Called only on natural termination (duration/till/condition/nil-interval), NOT on manual stop

Execution Tracking

  • _start_position: Position when loop started
  • _execution_counter: Number of iterations executed

Examples:

Dynamic control

seq = Musa::Sequencer::BaseSequencer.new(4, 24)
pulses = []
finished = false
after_at = nil

control = seq.every(1r, duration: 4r) { pulses << seq.position }
control.on_stop { finished = true }
control.after(2r) { after_at = seq.position }

seq.run

pulses    # => [(95/96), (191/96), (287/96), (383/96)]
finished  # => true
after_at  # => (575/96)

# `duration: 4r` counts bars of pulsing, so four pulses. `after` is
# measured from where the pulsing STOPPED -- 383/96 plus two bars --
# and not from the last pulse.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(parent, duration: nil, till: nil, condition: nil, on_stop: nil, after_bars: nil, after: nil) ⇒ EveryControl

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Creates every loop control.

Parameters:

  • parent (EventHandler) —

    parent event handler

  • duration (Rational, nil) (defaults to: nil) —

    maximum duration in bars

  • till (Rational, nil) (defaults to: nil) —

    absolute stop position

  • condition (Proc, nil) (defaults to: nil) —

    continuation condition

  • on_stop (Proc, nil) (defaults to: nil) —

    stop callback

  • after_bars (Rational, nil) (defaults to: nil) —

    delay for after callback

  • after (Proc, nil) (defaults to: nil) —

    after callback block



143
144
145
146
147
148
149
150
151
152
153
154
155
156
 
# File 'lib/musa-dsl/sequencer/base-sequencer-implementation-every.rb', line 143

def initialize(parent, duration: nil, till: nil, condition: nil, on_stop: nil, after_bars: nil, after: nil)
  super parent

  @duration_value = duration
  @till_value = till
  @condition_block = condition

  @do_on_stop = []
  @do_after = []

  @do_on_stop << on_stop if on_stop

  self.after after_bars, &after if after
end

Instance Attribute Details

#_execution_counter ⇒ Integer

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns number of iterations executed.

Returns:

  • (Integer) —

    number of iterations executed



130
131
132
 
# File 'lib/musa-dsl/sequencer/base-sequencer-implementation-every.rb', line 130

def _execution_counter
  @_execution_counter
end

#_start_position ⇒ Rational

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns position when loop started.

Returns:

  • (Rational) —

    position when loop started



127
128
129
 
# File 'lib/musa-dsl/sequencer/base-sequencer-implementation-every.rb', line 127

def _start_position
  @_start_position
end

#condition_block ⇒ Proc? (readonly)

Returns condition block (returns true to continue).

Returns:

  • (Proc, nil) —

    condition block (returns true to continue)



119
120
121
 
# File 'lib/musa-dsl/sequencer/base-sequencer-implementation-every.rb', line 119

def condition_block
  @condition_block
end

#do_after ⇒ Array<Hash> (readonly)

Returns after callbacks with delays.

Returns:

  • (Array<Hash>) —

    after callbacks with delays



123
124
125
 
# File 'lib/musa-dsl/sequencer/base-sequencer-implementation-every.rb', line 123

def do_after
  @do_after
end

#do_on_stop ⇒ Array<Proc> (readonly)

Returns callbacks when loop stops.

Returns:

  • (Array<Proc>) —

    callbacks when loop stops



121
122
123
 
# File 'lib/musa-dsl/sequencer/base-sequencer-implementation-every.rb', line 121

def do_on_stop
  @do_on_stop
end

#duration_value ⇒ Rational? (readonly)

Returns maximum duration in bars.

Returns:

  • (Rational, nil) —

    maximum duration in bars



115
116
117
 
# File 'lib/musa-dsl/sequencer/base-sequencer-implementation-every.rb', line 115

def duration_value
  @duration_value
end

#till_value ⇒ Rational? (readonly)

Returns absolute position to stop at.

Returns:

  • (Rational, nil) —

    absolute position to stop at



117
118
119
 
# File 'lib/musa-dsl/sequencer/base-sequencer-implementation-every.rb', line 117

def till_value
  @till_value
end

Instance Method Details

#after(bars = nil) { ... } ⇒ void

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Registers callback to execute after loop terminates naturally. NOT called on manual stop (.stop).

Examples:

Immediate after callback

control.after { puts "Done" }

Delayed after callback

control.after(2r) { puts "2 bars after stop" }

Parameters:

  • bars (Numeric, nil) (defaults to: nil) —

    delay in bars after natural termination (default: 0)

Yields:

  • after callback block



217
218
219
220
 
# File 'lib/musa-dsl/sequencer/base-sequencer-implementation-every.rb', line 217

def after(bars = nil, &block)
  bars ||= 0
  @do_after << { bars: bars.rationalize, block: block }
end

#condition { ... } ⇒ void

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Sets continuation condition.

Yields:

  • condition block (returns true to continue, false to stop)



187
188
189
 
# File 'lib/musa-dsl/sequencer/base-sequencer-implementation-every.rb', line 187

def condition(&block)
  @condition_block = block
end

#duration(value) ⇒ void

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Sets maximum loop duration.

Parameters:

  • value (Numeric) —

    duration in bars



165
166
167
 
# File 'lib/musa-dsl/sequencer/base-sequencer-implementation-every.rb', line 165

def duration(value)
  @duration_value = value.rationalize
end

#on_stop { ... } ⇒ void

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Registers callback for when loop stops (any reason, including manual stop).

Yields:

  • stop callback block



198
199
200
 
# File 'lib/musa-dsl/sequencer/base-sequencer-implementation-every.rb', line 198

def on_stop(&block)
  @do_on_stop << block
end

#till(value) ⇒ void

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Sets absolute stop position.

Parameters:

  • value (Numeric) —

    position to stop at



176
177
178
 
# File 'lib/musa-dsl/sequencer/base-sequencer-implementation-every.rb', line 176

def till(value)
  @till_value = value.rationalize
end