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 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 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)
Sourcepub fn sort(&mut self)
pub fn sort(&mut self)
Stable sort by sample_offset. Stability matters: events
with identical sample offsets stay in the order they were
pushed, which is what plugins assume when they iterate (e.g.
“MIDI on this sample then a CC on the same sample” stays in
that order). Don’t replace with sort_unstable_by_key - the
stability guarantee is load-bearing.
Sorting reorders Event entries only; SysEx pool
offsets stay valid because the pool’s bytes aren’t moved.
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).