pub struct EventList { /* private fields */ }Expand description
Ordered list of events within a process block.
events is the per-block event ring; sysex_pool is the
variable-byte arena that EventBody::SysEx entries index into.
Both are pre-allocated by EventList::with_capacity and reset
(length only - backing memory preserved) by Self::clear, so
steady-state operation is allocation-free.
Implementations§
Source§impl EventList
impl EventList
Sourcepub fn with_capacity(capacity: usize) -> Self
pub fn with_capacity(capacity: usize) -> Self
Construct an EventList with backing capacity already reserved.
Format wrappers build their per-instance event lists at
construction time and reuse them across blocks via clear().
Without this, the first push after EventList::default() hits
the global allocator on the audio thread; pre-allocating with
the max event count an audio block is likely to carry keeps
the first block alloc-free.
The SysEx byte pool is sized to SYSEX_POOL_PREALLOC
regardless of capacity - capacity controls the event ring
only.
Sourcepub fn push(&mut self, event: Event)
pub fn push(&mut self, event: Event)
Append an event. Note: sample_offset is not bounds-checked
against any block size - callers that build event lists per
block must validate sample_offset < num_samples themselves
(the audio thread can’t recover from an out-of-range offset, so
we treat that as a contract violation rather than panicking).
Sourcepub fn ensure_sorted_by_offset(&mut self)
pub fn ensure_sorted_by_offset(&mut self)
Sort the list by sample_offset if it isn’t already, keeping
the push order of equal-offset events (a recentre bend must stay
ahead of the note-off it precedes). Hosts require output queues
ordered by time; wrappers call this before draining so a plugin
that pushed block-level events after per-event ones can’t hand
the host an unsorted queue; wrappers also sort the merged
input stream before processing. Audio-thread safe: the
common already-sorted case is one linear scan, and the fix-up
is an in-place insertion sort - no allocation (sort_by_key
is a std stable sort that allocates past ~20 elements;
sort_unstable would reorder equal offsets, and stability is
load-bearing: “note-on then CC on the same sample” must stay
in push order). Reorders Event entries only; SysEx pool
offsets stay valid because the pool’s bytes aren’t moved.
Sourcepub fn push_sysex(
&mut self,
sample_offset: u32,
data: &[u8],
) -> Result<(), PushError>
pub fn push_sysex( &mut self, sample_offset: u32, data: &[u8], ) -> Result<(), PushError>
Append a SysEx event whose payload is copied into the pool.
data is the inner SysEx bytes without the leading
0xF0 / trailing 0xF7 - wrappers strip those at the
boundary.
Returns PushError::PoolFull when the pool can’t hold
data.len() more bytes; the event is not appended and the
pool is left unchanged. SysEx messages are atomic by spec,
so the caller’s choices are drop-and-flag (via a meter) or
fail the host call. Splitting / truncating produces a corrupt
message and is never the right answer.
§Errors
PushError::PoolFull when the pool is at capacity.
Sourcepub fn push_sysex_on_port(
&mut self,
sample_offset: u32,
port: u8,
data: &[u8],
) -> Result<(), PushError>
pub fn push_sysex_on_port( &mut self, sample_offset: u32, port: u8, data: &[u8], ) -> Result<(), PushError>
Like Self::push_sysex but stamps the event with a MIDI
Event::port. Single-port callers use Self::push_sysex
(port 0); a multi-port wrapper preserves the port a SysEx
arrived on.
§Errors
PushError::PoolFull when the pool is at capacity.
Sourcepub fn sysex_bytes(&self, body: &EventBody) -> &[u8] ⓘ
pub fn sysex_bytes(&self, body: &EventBody) -> &[u8] ⓘ
Resolve a EventBody::SysEx entry to its payload bytes.
Returns an empty slice for any other variant - the slice is
indexed against the internal byte pool, so a non-SysEx
body has nothing to point at.
pub fn clear(&mut self)
pub fn iter(&self) -> impl Iterator<Item = &Event>
pub fn get(&self, index: usize) -> Option<&Event>
pub fn len(&self) -> usize
pub fn is_empty(&self) -> bool
Sourcepub fn sysex_pool_used(&self) -> usize
pub fn sysex_pool_used(&self) -> usize
Current SysEx pool usage in bytes. Mainly useful in tests
and for plug-in code that wants to surface “headroom
remaining” in an editor.
Sourcepub fn sysex_pool_capacity(&self) -> usize
pub fn sysex_pool_capacity(&self) -> usize
Total SysEx pool capacity in bytes. Stable for the life of
the EventList (no audio-thread reallocation).