Class: Musa::Clock::Clock Abstract

Inherits:
Object show all
Defined in:
lib/musa-dsl/transport/clock.rb

Overview

This class is abstract.

Subclass and implement #run and #terminate

Abstract base class for all clock implementations.

This class defines the interface and callback infrastructure that all concrete clock implementations must follow. Subclasses must implement the run and terminate methods.

Callback System

Clocks maintain three callback collections:

  • on_start: Called when clock starts running
  • on_stop: Called when clock stops
  • on_change_position: Called when position changes (seek/jump)

Subclass Responsibilities

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
  4. Manage @run state properly

Examples:

Creating a simple clock subclass

class SimpleClock < Clock
  def run
    @run = true
    @on_start.each(&:call)

    while @run
      yield if block_given?  # Generate tick
      sleep 0.1
    end

    @on_stop.each(&:call)
  end

  def terminate
    @run = false
  end
end

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Clock

Initializes the clock with empty callback collections.



71
72
73
74
75
76
 
# File 'lib/musa-dsl/transport/clock.rb', line 71

def initialize
  @run = nil
  @on_start = []
  @on_stop = []
  @on_change_position = []
end

Instance Method Details

#on_change_position {|bars, beats, midi_beats| ... } ⇒ void

This method returns an undefined value.

Registers a callback to be called when playback position changes.

This is typically used for handling seek/jump operations where the transport position changes non-linearly.

Examples:

clock.on_change_position do |bars:, beats:, midi_beats:|
  puts "Position changed to bar #{bars}"
end

Yields:

  • (bars, beats, midi_beats) —

    Position change information

Yield Parameters:

  • bars (Rational, nil) —

    new position in bars

  • beats (Rational, nil) —

    new position in beats

  • midi_beats (Integer, nil) —

    new position in MIDI beats (for MIDI Clock)



126
127
128
 
# File 'lib/musa-dsl/transport/clock.rb', line 126

def on_change_position(&block)
  @on_change_position << block
end

#on_start { ... } ⇒ void

This method returns an undefined value.

Registers a callback to be called when the clock starts.

Multiple callbacks can be registered and will be called in order.

Examples:

clock.on_start { puts "Clock started!" }

Yields:

  • Called when clock starts running.



94
95
96
 
# File 'lib/musa-dsl/transport/clock.rb', line 94

def on_start(&block)
  @on_start << block
end

#on_stop { ... } ⇒ void

This method returns an undefined value.

Registers a callback to be called when the clock stops.

Multiple callbacks can be registered and will be called in order.

Examples:

clock.on_stop { puts "Clock stopped!" }

Yields:

  • Called when clock stops running.



107
108
109
 
# File 'lib/musa-dsl/transport/clock.rb', line 107

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

#run { ... } ⇒ void

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.

This method returns an undefined value.

Starts the clock running and generates ticks.

This method should block and yield once per tick. Subclasses must implement this method.

Yields:

  • Called once per tick to advance the sequencer.

Raises:

  • (NotImplementedError) —

    if not overridden by subclass.



143
144
145
 
# File 'lib/musa-dsl/transport/clock.rb', line 143

def run
  raise NotImplementedError
end

#running? ⇒ Boolean

Checks if the clock is currently running.

Returns:

  • (Boolean) —

    true if clock is running, false otherwise.



81
82
83
 
# File 'lib/musa-dsl/transport/clock.rb', line 81

def running?
  @run
end

#terminate ⇒ void

Note:

After calling this, #run should exit.

This method returns an undefined value.

Stops the clock and terminates the run loop.

Subclasses must implement this method to cleanly stop the clock.

Raises:

  • (NotImplementedError) —

    if not overridden by subclass.



156
157
158
 
# File 'lib/musa-dsl/transport/clock.rb', line 156

def terminate
  raise NotImplementedError
end