pulp::midi::MidiMessageCollector< Capacity > Class Template Reference

#include <message_collector.hpp>

Public Member Functions
	MidiMessageCollector ()=default
bool	push_now (const MidiEvent &event, double now_seconds)
	UI / producer thread — push a MidiEvent timestamped at now_seconds.
bool	push_now (const MidiEvent &event)
	Convenience overload using MidiEvent::timestamp directly.
std::size_t	drain_into (MidiBuffer &out, double block_start_seconds, int block_size_samples, double sample_rate)
	Audio / consumer thread — drain queued events into out at the correct sample offsets within the current processing block.
std::size_t	dropped_future () const
	Number of FUTURE events the consumer dropped because the pending ring was saturated at the moment they were popped.
std::uint64_t	queue_overflow_count () const
	Producer-side queue overflow count from failed push_now() attempts.
void	reset_queue_overflow_count ()
	Reset only the producer queue overflow counter.
MidiMessageCollectorTelemetry	telemetry () const
	Cheap snapshot for UI, validation, and inspector polling.
std::size_t	size_approx () const
	Approximate number of events currently queued (does NOT count the deferred-future entries in the pending ring or the consumer-side overflow slot).

Static Public Member Functions
static constexpr std::size_t	capacity ()
	Compile-time capacity of the producer queue.
static constexpr std::size_t	pending_capacity ()
	Compile-time size of the consumer-owned pending ring.

Constructor & Destructor Documentation

MidiMessageCollector()

template<std::size_t Capacity = 256>

pulp::midi::MidiMessageCollector< Capacity >::MidiMessageCollector ( )

default

Member Function Documentation

capacity()

template<std::size_t Capacity = 256>

constexpr std::size_t pulp::midi::MidiMessageCollector< Capacity >::capacity ( )

inlinestaticconstexpr

Compile-time capacity of the producer queue.

drain_into()

template<std::size_t Capacity = 256>

std::size_t pulp::midi::MidiMessageCollector< Capacity >::drain_into ( MidiBuffer & out, double block_start_seconds, int block_size_samples, double sample_rate )

inline

Audio / consumer thread — drain queued events into out at the correct sample offsets within the current processing block.

Events whose timestamps are <= block_start_seconds land at sample 0 (catch-up). Events between block_start and block_end land at the sample offset that matches their timestamp. Events strictly after block_end_seconds stay queued for the next block.

block_size_samples and sample_rate together define the block length: block_end_seconds = block_start_seconds + block_size_samples / sample_rate.

Returns the number of events drained into out this call.

dropped_future()

template<std::size_t Capacity = 256>

std::size_t pulp::midi::MidiMessageCollector< Capacity >::dropped_future ( ) const

inline

Number of FUTURE events the consumer dropped because the pending ring was saturated at the moment they were popped.

Monotonic, atomic, never reset. A non-zero value means producers buffered more events than pending_capacity() can carry across drains; either reduce producer-side look-ahead or pick a larger Capacity so the producer SPSC queue itself absorbs more in-flight events.

pending_capacity()

template<std::size_t Capacity = 256>

constexpr std::size_t pulp::midi::MidiMessageCollector< Capacity >::pending_capacity ( )

inlinestaticconstexpr

Compile-time size of the consumer-owned pending ring.

Sized to absorb realistic Pulp producer bursts (UI input + scripting look-ahead + MIDI file playback) within a single drain. A workload that exceeds this in one drain will see drops counted via dropped_future(); raising Capacity lets the producer queue itself absorb more in-flight events before they reach the consumer ring.

push_now() [1/2]

template<std::size_t Capacity = 256>

bool pulp::midi::MidiMessageCollector< Capacity >::push_now ( const MidiEvent & event )

inline

Convenience overload using MidiEvent::timestamp directly.

push_now() [2/2]

template<std::size_t Capacity = 256>

bool pulp::midi::MidiMessageCollector< Capacity >::push_now ( const MidiEvent & event, double now_seconds )

inline

UI / producer thread — push a MidiEvent timestamped at now_seconds.

Returns false when the queue is full (caller decides whether to drop, log, or back off — push_now never blocks).

queue_overflow_count()

template<std::size_t Capacity = 256>

std::uint64_t pulp::midi::MidiMessageCollector< Capacity >::queue_overflow_count ( ) const

inline

Producer-side queue overflow count from failed push_now() attempts.

Monotonic until reset explicitly by a non-audio observer.

reset_queue_overflow_count()

template<std::size_t Capacity = 256>

void pulp::midi::MidiMessageCollector< Capacity >::reset_queue_overflow_count ( )

inline

Reset only the producer queue overflow counter.

This deliberately does not reset dropped_future(), whose existing contract is monotonic for consumer-side future-event loss.

size_approx()

template<std::size_t Capacity = 256>

std::size_t pulp::midi::MidiMessageCollector< Capacity >::size_approx ( ) const

inline

Approximate number of events currently queued (does NOT count the deferred-future entries in the pending ring or the consumer-side overflow slot).

telemetry()

template<std::size_t Capacity = 256>

MidiMessageCollectorTelemetry pulp::midi::MidiMessageCollector< Capacity >::telemetry ( ) const

inline

Cheap snapshot for UI, validation, and inspector polling.

Counts the producer queue, consumer-owned pending ring, queue overflow, and future-event drops without allocating.

---

The documentation for this class was generated from the following file:

• /home/runner/work/pulp/pulp/core/midi/include/pulp/midi/message_collector.hpp