Package net.paulhertz.pixelaudio.schedule

# Class AudioScheduler<H>

java.lang.Object
net.paulhertz.pixelaudio.schedule.AudioScheduler<H>

public final class AudioScheduler<H> extends Object
AudioScheduler: A sample-accurate scheduler for things that should occur at specific times in an audio stream.

Two event shapes

- PointEvent: happens once at an absolute sample time.
- SpanEvent: is active over an interval [startSample, endSample) and can report start/end offsets plus per-block callbacks while active.

Threading model

- `schedulePoint(...)` and `scheduleSpan(...)` may be called from any thread.
- `processBlock(...)` must be called exactly once per audio block on the audio thread.

Happenings

The generic type parameter `H` is a user-defined "Happening": a compact piece of information that you want to schedule in time (e.g., x/y coordinates, pan/gain, an instrument id, a brush reference, or a small command object). A Happening is carried by events and delivered to handlers at the correct time.

Sample accuracy

`processBlock(...)` reports an `offsetInBlock` for point events and span boundaries, so you can align actions to an exact sample within the current audio block. If your instrument can only start on block boundaries, you can still use this scheduler for deterministic block timing today, and later upgrade your instrument to accept offsets without changing scheduling code.

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static enum`
  `AudioScheduler.LatePolicy`
  Policy for point events whose sampleTime is already in the past when processed.
  `static final class`
  `AudioScheduler.PointEvent<H>`
  A one-shot event that occurs at an absolute sample index.
  `static interface`
  `AudioScheduler.PointHandler<H>`
  `static final class`
  `AudioScheduler.SpanEvent<H>`
  A duration event active on [startSample, endSample) where endSample is exclusive.
  `static interface`
  `AudioScheduler.SpanHandler<H>`

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `private final ConcurrentLinkedQueue<Object>`
  `inbox`
  `private AudioScheduler.LatePolicy`
  `latePolicy`
  `private final PriorityQueue<Object>`
  `queue`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `AudioScheduler()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `clear()`
  Clears all pending events (both newly scheduled and already queued).
  `private void`
  `drainInbox()`
  Called only on the audio thread.
  `AudioScheduler.LatePolicy`
  `latePolicy()`
  `void`
  `processBlock(long blockStartSample, int blockSize, AudioScheduler.PointHandler<H> pointHandler, AudioScheduler.SpanHandler<H> spanHandler)`
  Process one audio block.
  `void`
  `schedulePoint(long sampleTime, H happening)`
  Schedule a point event at an absolute sample time.
  `void`
  `scheduleSpan(long startSample, long endSample, H happening)`
  Schedule a span event active on [startSample, endSample).
  `void`
  `setLatePolicy(AudioScheduler.LatePolicy policy)`
  Set how late point events are handled.
  `private static long`
  `startSampleOf(Object o)`

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Field Details

  - ### inbox

    private final ConcurrentLinkedQueue<Object> inbox

  - ### queue

    private final PriorityQueue<Object> queue

  - ### latePolicy

    private AudioScheduler.LatePolicy latePolicy

- ## Constructor Details

  - ### AudioScheduler

    public AudioScheduler()

- ## Method Details

  - ### setLatePolicy

    public void setLatePolicy(AudioScheduler.LatePolicy policy)
    Set how late point events are handled. Default is `AudioScheduler.LatePolicy.DROP`.

  - ### latePolicy

    public AudioScheduler.LatePolicy latePolicy()

  - ### schedulePoint

    public void schedulePoint(long sampleTime, H happening)
    Schedule a point event at an absolute sample time.
    Parameters:
      `sampleTime` - absolute sample index (0-based)
      `happening` - the Happening to deliver

  - ### scheduleSpan

    public void scheduleSpan(long startSample, long endSample, H happening)
    Schedule a span event active on [startSample, endSample).
    Parameters:
      `startSample` - absolute start sample (inclusive)
      `endSample` - absolute end sample (exclusive)
      `happening` - the Happening to deliver

  - ### clear

    public void clear()
    Clears all pending events (both newly scheduled and already queued). Safe to call from any thread.

  - ### drainInbox

    private void drainInbox()
    Called only on the audio thread.

  - ### startSampleOf

    private static long startSampleOf(Object o)

  - ### processBlock

    public void processBlock(long blockStartSample, int blockSize, AudioScheduler.PointHandler<H> pointHandler, AudioScheduler.SpanHandler<H> spanHandler)
    Process one audio block. Call exactly once per block on the audio thread.

    All point events that occur within this block (or earlier, if `AudioScheduler.LatePolicy.CLAMP_TO_BLOCK_START`) will be delivered to `pointHandler`. Span events will deliver start/end callbacks (when the boundary falls within this block) and an `onBlock` callback for each block they overlap.

    Parameters:
      `blockStartSample` - absolute sample index of the first sample in this block
      `blockSize` - number of samples in this block
      `pointHandler` - handler for point events (may be null if you never schedule points)
      `spanHandler` - handler for span events (may be null if you never schedule spans)