Struct EventBuffer 

pub struct EventBuffer { /* private fields */ }

A buffer for ordered storing of heterogeneous UnknownEvents.

This type is useful for dynamic storage of arbitrary events, as UnknownEvents are dynamically-sized types (DSTs) and can not be simply stored in e.g. a Vec.

This type is also useful as the backing storage for plugin events, as it implements both the InputEventBuffer and the OutputEventBuffer traits.

Example

use clack_common::events::event_types::ParamGestureBeginEvent;
use clack_common::events::EventHeader;
use clack_common::events::io::EventBuffer;
use clack_common::utils::ClapId;

const MY_PARAM_ID: ClapId = ClapId::new(2);

let mut buffer = EventBuffer::new();
assert!(buffer.is_empty());

let some_event = ParamGestureBeginEvent::new(6, MY_PARAM_ID);
buffer.push(&some_event);
assert_eq!(1, buffer.len());
assert_eq!(&buffer[0], &some_event);

Realtime Safety

This type is backed by Vec internally, and therefore holds similar realtime properties. Reading from it is always realtime-safe, but pushing new events to it may not be.

To avoid allocations, hosts should use the with_capacity to pre-allocate a reasonable amount of space for plugins to send their events.

However, this is always a best-effort, and not a guarantee.

Implementations

impl EventBuffer

pub const fn new() -> EventBuffer

Creates a new, empty EventBuffer.

pub fn with_capacity(events: usize) -> EventBuffer

Creates a new empty EventBuffer, but with enough pre-allocated capacity for the given number of standard events.

Because CLAP events can have any arbitrary size, this method can only pre-allocate on a best-effort basis, only reserving enough space for the largest standard CLAP events.

Realtime Safety

This method always allocates and is not realtime-safe, unless events is zero.

pub fn clear(&mut self)

Clears the buffer, removing all events.

Note that this has no effect on the allocated capacity of the buffer.

pub fn len(&self) -> u32

Returns the number of events in this buffer.

pub fn is_empty(&self) -> bool

Returns true if this buffer has no events in it (i.e. if len == 0), false otherwise.

pub fn get(&self, index: u32) -> Option<&UnknownEvent>

Returns the event located at the given index.

If index is out of bounds, this returns None.

pub fn iter(&self) -> EventBufferIter<'_>

Returns an iterator of all the events contained in this buffer.

pub fn sort(&mut self)

Sorts the events contained in this buffer, based on their time.

It is necessary to sort the events before passing them to a plugin.

pub fn insert<E>(&mut self, event: &E, position: usize)

where E: AsRef<UnknownEvent> + ?Sized,

Inserts a given event at the given position, shifting all events after it to the right.

Panics

Panics if position > len.

pub fn push_all<'a, E>(&mut self, events: impl IntoIterator<Item = &'a E>)

where E: AsRef<UnknownEvent> + 'a + ?Sized,

Pushes all events produced by the given events iterator at the end of the buffer.

pub fn push<E>(&mut self, event: &E)

where E: AsRef<UnknownEvent> + ?Sized,

Pushes the given event into the buffer.

The event is always added at the end of the buffer.

pub fn as_input(&self) -> InputEvents<'_>

Produces an InputEvents that wraps this buffer as an InputEventBuffer implementation.

This helper method is strictly equivalent to using InputEvents::from_buffer.

pub fn as_output(&mut self) -> OutputEvents<'_>

Produces an OutputEvents that wraps this buffer as an OutputEventBuffer implementation.

This helper method is strictly equivalent to using OutputEvents::from_buffer.

Trait Implementations

impl Debug for EventBuffer

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Default for EventBuffer

fn default() -> EventBuffer

Returns the “default value” for a type.

impl Index<usize> for EventBuffer

type Output = UnknownEvent

The returned type after indexing.

fn index(&self, index: usize) -> &<EventBuffer as Index<usize>>::Output

Performs the indexing (container[index]) operation.

impl InputEventBuffer for EventBuffer

fn len(&self) -> u32

Returns the number of events in this list.

fn get(&self, index: u32) -> Option<&UnknownEvent>

Returns the event at the given index.

impl<'a> IntoIterator for &'a EventBuffer

type Item = &'a UnknownEvent

The type of the elements being iterated over.

type IntoIter = EventBufferIter<'a>

Which kind of iterator are we turning this into?

fn into_iter(self) -> <&'a EventBuffer as IntoIterator>::IntoIter

Creates an iterator from a value.

impl OutputEventBuffer for EventBuffer

fn try_push(&mut self, event: &UnknownEvent) -> Result<(), TryPushError>

Attempts to push a given event to the queue.