Struct HostWrapper 

pub struct HostWrapper<H: HostHandlers> { /* private fields */ }

A wrapper around a clack host implementation of a given type.

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

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

Implementations

impl<H: HostHandlers> HostWrapper<H>

pub unsafe fn handle<T, F>(host: *const clap_host, handler: F) -> Option<T>

where F: FnOnce(&HostWrapper<H>) -> Result<T, HostWrapperError>,

Provides a shared reference to a host 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_host pointer is null-checked, as well as some other host-provided pointers;
• The handler is wrapped in std::panic::catch_unwind;
• Any HostWrapperError 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_host 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 host wrapper type H must be the correct type for the received pointer. Otherwise, incorrect casts will occur, which will lead to Undefined Behavior.

The host pointer must also point to a valid instance of clap_host, as created 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 for safety: those checks only exist to help debugging.

pub unsafe fn handle_main_thread<T, F>( host: *const clap_host, handler: F, ) -> Option<T>

where F: for<'a> FnOnce(&<H as HostHandlers>::MainThread<'a>) -> Result<T, HostWrapperError>,

Safety

TODO

pub unsafe fn audio_processor( &self, ) -> Result<NonNull<<H as HostHandlers>::AudioProcessor<'_>>, HostWrapperError>

Returns a raw, non-null pointer to the host’s AudioProcessor struct.

Errors

This will return HostWrapperError::DeactivatedPlugin if the plugin was not actually activated.

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.

pub fn shared(&self) -> &<H as HostHandlers>::Shared<'_>

Returns a shared reference to the host’s Shared struct.

Trait Implementations

impl<H: HostHandlers> Send for HostWrapper<H>

impl<H: HostHandlers> Sync for HostWrapper<H>