Struct OutputEvents 

pub struct OutputEvents<'a> { /* private fields */ }

An ordered list of timestamped events.

OutputEventss are always ordered: an event at index i will always have a timestamp smaller than or equal to the timestamp of the next event at index i + 1.

OutputEventss do not own the event data, they are only lightweight wrappers around a compatible event buffer (i.e. OutputEventBuffer), see OutputEvents::from_buffer.

Unlike Vecs or slices, OutputEventss only support appending a new event to the list (try_push).

This type also implements a few extra features based on these operations for convenience, such as the Extend trait.

Example

 use clack_common::events::{Event, EventHeader, Pckn};
 use clack_common::events::event_types::NoteOnEvent;
 use clack_common::events::io::{EventBuffer, OutputEvents};

 let mut buf = EventBuffer::new();
 let mut output_events = OutputEvents::from_buffer(&mut buf);

 let event = NoteOnEvent::new(0, Pckn::new(0u16, 0u16, 12u16, 60u32), 4.2);
 output_events.try_push(event.as_unknown()).unwrap();

 assert_eq!(1, buf.len());

Implementations

impl<'a> OutputEvents<'a>

pub const unsafe fn from_raw_mut( raw: &mut clap_output_events, ) -> &'a mut OutputEvents<'a>

Creates a mutable reference to an OutputEvents list from a given C FFI-compatible pointer.

Safety

The caller must ensure the given pointer is valid for the lifetime 'a.

pub const fn as_raw(&mut self) -> &clap_output_events

Returns a reference to a C FFI-compatible representation of this event list.

pub const unsafe fn as_raw_mut(&mut self) -> &mut clap_output_events

Returns a C FFI-compatible mutable pointer to this event list.

Safety

This method allows mutating the list’s inner fields. Modifying those fields may trigger Undefined Behavior.

pub const fn from_buffer<O>(buffer: &'a mut O) -> OutputEvents<'a>

where O: OutputEventBuffer,

Create a new event list by wrapping an event buffer implementation.

This buffer may have been used by a previous OutputEvents, and will keep all events that have been pushed into it. This allows to reuse event buffers between process trips.

Realtime Safety

This is a very cheap, realtime-safe operation that does not change the given buffer in any way. However, since users of the OutputEvents may call append on it, the buffer should have a reasonable amount of storage pre-allocated, as to not have to perform additional allocations on the audio thread.

Example

use clack_common::events::io::{EventBuffer, OutputEvents};

// Allocate the buffer on the main thread
let mut buf = EventBuffer::new();

// Later, on the DSP thread
let output_events = OutputEvents::from_buffer(&mut buf);

pub const fn void() -> OutputEvents<'a>

Creates a void “list” which ignores every event that is pushed to it.

This can be useful if you do not intend to support output events at all.

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

where E: AsRef<UnknownEvent>,

Appends a copy of the given event to the list.

Note that the event is not guaranteed to be added at the end of the list: in order to efficiently preserve ordering, some implementations may choose to insert it in a position following all events with smaller timestamps, and preceding all events with greater timestamps.

For best performance however, it is recommended to insert the events in order if possible.

Errors

This method will return a TryPushError if the event could not be pushed to the list.

The exact reason is left at the implementer’s discretion, but this is usually a sign that the implementer ran out of buffer space, and either cannot or refuses to allocate more.

Realtime Safety

This operation may cause the underlying event buffer to be reallocated by the host, therefore realtime safety cannot be guaranteed. However, it is expected for hosts to pre-allocate a reasonable amount of space before forwarding the list to the plugin, in order to make allocations as unlikely as possible.

Trait Implementations

impl<'a, 'b> Extend<&'b UnknownEvent> for OutputEvents<'a>

where 'a: 'b,

fn extend<T>(&mut self, iter: T)

where T: IntoIterator<Item = &'b UnknownEvent>,

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: T)

🔬This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl<'a, I> From<&'a mut I> for OutputEvents<'a>

where I: OutputEventBuffer,

fn from(implementation: &'a mut I) -> OutputEvents<'a>

Converts to this type from the input type.

impl OutputEventBuffer for OutputEvents<'_>

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

Attempts to push a given event to the queue.