Struct PluginWrapper

Source

pub struct PluginWrapper<'a, P: Plugin> { /* private fields */ }

Expand description

A wrapper around a clack plugin of a given type.

This wrapper allows access to a plugin’s Shared, MainThread, and AudioProcessor structs, while also handling common FFI issues, such as error management and unwind safety.

The only way to access an instance of PluginWrapper is through the handle function.

Implementations§

Source §

impl<'a, P: Plugin> PluginWrapper<'a, P>

Source

pub fn is_active(&self) -> bool

Returns if the current plugin has been activated or not.

Source

pub fn shared(&self) -> &P::Shared<'a>

Returns a reference to a plugin’s Shared struct.

This is always safe to call in any context, since the Shared struct is required to implement Sync.

Source

pub unsafe fn main_thread(&self) -> &P::MainThread<'a>

Returns a raw, non-null pointer to the plugin’s MainThread struct.

§Safety

The caller must ensure this method is only called on the main thread.

The pointer is safe to mutably dereference, as long as the caller ensures it is not being aliased, as per usual safety rules.

Source

pub unsafe fn audio_processor( &self, ) -> Result<NonNull<P::AudioProcessor<'a>>, PluginWrapperError>

Returns a raw, non-null pointer to the plugin’s audio processor (i.e. Plugin) struct.

§Errors

This method will return PluginWrapperError::DeactivatedPlugin if the plugin has not been activated before calling this method.

This is an extra safety check which ensures that hosts correctly activated plugins before calling any audio-thread method.

§Safety

The caller must ensure this method is only called on the audio thread.

The pointer is safe to mutably dereference, as long as the caller ensures it is not being aliased, as per usual safety rules.

Source

pub unsafe fn handle<T, F>(plugin: *const clap_plugin, handler: F) -> Option<T>
where F: FnOnce(&PluginWrapper<'a, P>) -> Result<T, PluginWrapperError>,

Provides a shared reference to a plugin wrapper of a given type, to the given handler closure.

Besides providing a reference, this function does a few extra safety checks:

The given clap_plugin pointer is null-checked, as well as some other host-provided pointers;
The handler is wrapped in std::panic::catch_unwind;
Any PluginWrapperError returned by the handler is caught.

If any of the above safety check fails, an error message is logged (using the standard CLAP logging extension). If logging is unavailable or fails for any reason, the error message is written to stderr as a fallback.

Note that some safety checks (e.g. the clap_plugin pointer null-checks) may result in the closure never being called, and an error being returned only. Users of this function must not rely on the completion of this closure for safety, and must handle this function returning None gracefully.

If all goes well, the return value of the handler closure is forwarded and returned by this function.

§Errors

If any safety check failed, or any error or panic occurred inside the handler closure, this function returns None, and the error message is logged.

§Safety

The given plugin type P must be the correct type for the received pointer. Otherwise, incorrect casts will occur, which will lead to Undefined Behavior.

The plugin pointer must also point to a valid instance of clap_plugin, as provided by the CLAP Host. While this function does a couple of simple safety checks, only a few common cases are actually covered (i.e. null checks), and those must not be relied upon: those checks only exist to help debugging faulty hosts.

§Example

This is the implementation of the on_main_thread callback’s C wrapper.

This method is guaranteed by the CLAP specification to be only called on the main thread.

use clap_sys::plugin::clap_plugin;
use clack_plugin::plugin::{Plugin, PluginMainThread};
use clack_plugin::extensions::wrapper::PluginWrapper;

unsafe extern "C" fn on_main_thread<P: Plugin>(plugin: *const clap_plugin) {
  PluginWrapper::<P>::handle(plugin, |p| {
    p.main_thread().on_main_thread();
    Ok(())
  });
}