audio_plugin_bsd/

loader.rs

//! Dynamic plugin loader: [`PluginLoader`], [`LoadedPlugin`], and [`PluginId`].
//!
//! [`PluginLoader`] owns every loaded `cdylib` (`libloading::Library`) and
//! hands out [`PluginId`]s that reference them. Unloading a plugin removes its
//! entry, which drops the `Library` and runs `dlclose` — guaranteeing no
//! outstanding [`AudioNode`](audio_core_bsd::AudioNode) instance can outlive
//! the library it came from (the adapter is dropped first, releasing the
//! opaque handle, and only then the library is closed).
//!
//! # Real-time safety boundary
//!
//! `load` / `unload` / `instantiate` run on a **non-RT** (setup) thread. Only
//! the [`AudioNode`](audio_core_bsd::AudioNode) returned from
//! [`PluginLoader::instantiate`] ever touches the RT thread.

use std::collections::HashMap;
use std::path::Path;

use audio_core_bsd::AudioNode;
use libloading::Library;

use crate::abi::{is_abi_compatible, AUDIO_PLUGIN_ABI_MAGIC, AUDIO_PLUGIN_ABI_VERSION};
use crate::error::{PluginError, Result};
use crate::metadata::PluginMetadata;
use crate::plugin::{HostPlugin, Plugin};
use crate::symbols::{
    raw_to_metadata, AbiMagicFn, AbiVersionFn, CreateFn, DestroyFn, MetadataFn,
    AUDIO_PLUGIN_ABI_MAGIC_SYMBOL, AUDIO_PLUGIN_ABI_VERSION_SYMBOL, AUDIO_PLUGIN_CREATE_SYMBOL,
    AUDIO_PLUGIN_DESTROY_SYMBOL, AUDIO_PLUGIN_METADATA_SYMBOL,
};

/// Opaque, copyable handle identifying one loaded plugin inside a
/// [`PluginLoader`].
///
/// IDs are assigned monotonically starting at 0 and are unique within a single
/// loader instance until `u32::MAX` is reached (after which they wrap). In
/// practice the wrap is unreachable; it is handled without panicking for
/// robustness.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct PluginId(u32);

/// A successfully loaded plugin: its library, metadata, host adapter, and id.
///
/// The library is owned here so that dropping a `LoadedPlugin` runs `dlclose`
/// after the adapter (and any instantiated node) has been released, preventing
/// use-after-unload.
pub struct LoadedPlugin {
    /// The opened `cdylib`; never read directly — its sole purpose is to be
    /// dropped (running `dlclose`) when the `LoadedPlugin` is removed, so the
    /// plugin's symbols stay mapped for the adapter's lifetime.
    #[allow(dead_code)]
    library: Library,
    /// Owned metadata copied out of the plugin at load time.
    metadata: PluginMetadata,
    /// Host adapter bridging the plugin's C symbols to [`Plugin`].
    plugin: Box<dyn Plugin>,
    /// The loader-assigned id.
    id: PluginId,
}

impl LoadedPlugin {
    /// Static metadata for this plugin.
    #[must_use]
    pub fn metadata(&self) -> &PluginMetadata {
        &self.metadata
    }

    /// The id under which this plugin is registered.
    #[must_use]
    pub fn id(&self) -> PluginId {
        self.id
    }
}

/// Owner of all loaded plugin `cdylib`s.
///
/// See the [module docs](self) for the lifetime / RT-safety contract.
pub struct PluginLoader {
    plugins: HashMap<PluginId, LoadedPlugin>,
    next_id: u32,
}

impl PluginLoader {
    /// Construct an empty loader.
    #[must_use]
    pub fn new() -> Self {
        Self {
            plugins: HashMap::new(),
            next_id: 0,
        }
    }

    /// Load and ABI-verify a plugin `cdylib`, returning its assigned id.
    ///
    /// # Steps
    ///
    /// 1. Validate the path (must be an existing, readable file).
    /// 2. `dlopen` the library.
    /// 3. Look up and call `audio_plugin_abi_magic`; require
    ///    [`AUDIO_PLUGIN_ABI_MAGIC`].
    /// 4. Look up and call `audio_plugin_abi_version`; require a
    ///    **major** match (see [`is_abi_compatible`]).
    /// 5. Look up `audio_plugin_metadata` and copy out an owned
    ///    [`PluginMetadata`].
    /// 6. Look up `audio_plugin_create` (required) and `audio_plugin_destroy`
    ///    (optional).
    /// 7. Register the plugin under a fresh [`PluginId`].
    ///
    /// Loading the same path twice is permitted: each call receives its own id
    /// and its own `dlopen` handle.
    ///
    /// # Errors
    ///
    /// - [`PluginError::InvalidPath`] — missing file or non-UTF-8 path.
    /// - [`PluginError::LibraryLoad`] — `dlopen` failed.
    /// - [`PluginError::SymbolMissing`] — a required symbol is absent.
    /// - [`PluginError::InvalidMetadata`] — magic mismatch or bad metadata.
    /// - [`PluginError::AbiVersionMismatch`] — ABI major differs.
    pub fn load(&mut self, path: &Path) -> Result<PluginId> {
        // 1. Path validation: must exist and be a file. UTF-8 is required so
        //    that error messages can embed the path (see InvalidPath doc).
        if !path.is_file() {
            return Err(PluginError::InvalidPath(format!(
                "{}: not an existing file",
                path.display()
            )));
        }
        if path.to_str().is_none() {
            return Err(PluginError::InvalidPath(format!(
                "{}: path is not valid UTF-8",
                path.display()
            )));
        }

        // 2. dlopen.
        let library = unsafe { Library::new(path) }
            .map_err(|e| PluginError::LibraryLoad(format!("{}: {e}", path.display())))?;

        // 3. ABI magic.
        let plugin_magic = unsafe {
            let sym: libloading::Symbol<AbiMagicFn> = library
                .get(AUDIO_PLUGIN_ABI_MAGIC_SYMBOL.as_bytes())
                .map_err(|e| {
                    PluginError::SymbolMissing(format!("{AUDIO_PLUGIN_ABI_MAGIC_SYMBOL}: {e}"))
                })?;
            sym()
        };
        if plugin_magic != AUDIO_PLUGIN_ABI_MAGIC {
            return Err(PluginError::InvalidMetadata(format!(
                "ABI magic mismatch: expected {AUDIO_PLUGIN_ABI_MAGIC:#010x}, got {plugin_magic:#010x}"
            )));
        }

        // 4. ABI version (major must match host).
        let plugin_version = unsafe {
            let sym: libloading::Symbol<AbiVersionFn> = library
                .get(AUDIO_PLUGIN_ABI_VERSION_SYMBOL.as_bytes())
                .map_err(|e| {
                    PluginError::SymbolMissing(format!("{AUDIO_PLUGIN_ABI_VERSION_SYMBOL}: {e}"))
                })?;
            sym()
        };
        if !is_abi_compatible(AUDIO_PLUGIN_ABI_VERSION, plugin_version) {
            return Err(PluginError::AbiVersionMismatch {
                host: AUDIO_PLUGIN_ABI_VERSION,
                plugin: plugin_version,
            });
        }

        // 5. Metadata (copy strings into owned memory).
        let metadata = unsafe {
            let sym: libloading::Symbol<MetadataFn> = library
                .get(AUDIO_PLUGIN_METADATA_SYMBOL.as_bytes())
                .map_err(|e| {
                    PluginError::SymbolMissing(format!("{AUDIO_PLUGIN_METADATA_SYMBOL}: {e}"))
                })?;
            let raw_ptr = sym();
            // SAFETY: `raw_ptr` is the plugin's `'static` metadata pointer;
            // the library (and therefore the plugin's data segment) is alive
            // because `library` is still in scope.
            raw_to_metadata(raw_ptr)?
        };

        // 6. create (required) + destroy (optional).
        let create_fn: CreateFn = unsafe {
            let sym: libloading::Symbol<CreateFn> = library
                .get(AUDIO_PLUGIN_CREATE_SYMBOL.as_bytes())
                .map_err(|e| {
                    PluginError::SymbolMissing(format!("{AUDIO_PLUGIN_CREATE_SYMBOL}: {e}"))
                })?;
            *sym
        };
        let destroy_fn: Option<DestroyFn> = unsafe {
            library
                .get::<DestroyFn>(AUDIO_PLUGIN_DESTROY_SYMBOL.as_bytes())
                .ok()
                // SAFETY: `Symbol<DestroyFn>` derefs to `&DestroyFn`; copying
                // the plain function pointer out releases the library borrow.
                .map(|sym| *sym)
        };

        // 7. Register.
        let plugin: Box<dyn Plugin> =
            Box::new(HostPlugin::new(metadata.clone(), create_fn, destroy_fn));
        let id = self.fresh_id();
        self.plugins.insert(
            id,
            LoadedPlugin {
                library,
                metadata,
                plugin,
                id,
            },
        );
        Ok(id)
    }

    /// Unload a plugin, dropping its library (`dlclose`).
    ///
    /// The caller must ensure no [`AudioNode`](audio_core_bsd::AudioNode)
    /// instantiated from this plugin is still alive — the adapter owns an
    /// opaque handle into the plugin's memory and calling it after `dlclose`
    /// is undefined behaviour.
    ///
    /// # Errors
    ///
    /// Returns [`PluginError::NotLoaded`] when `id` is not registered.
    pub fn unload(&mut self, id: PluginId) -> Result<()> {
        if self.plugins.remove(&id).is_some() {
            Ok(())
        } else {
            Err(PluginError::NotLoaded)
        }
    }

    /// Borrow a loaded plugin by id.
    ///
    /// # Errors
    ///
    /// Returns [`PluginError::NotLoaded`] when `id` is not registered.
    pub fn get(&self, id: PluginId) -> Result<&LoadedPlugin> {
        self.plugins.get(&id).ok_or(PluginError::NotLoaded)
    }

    /// Mutably borrow a loaded plugin by id.
    ///
    /// # Errors
    ///
    /// Returns [`PluginError::NotLoaded`] when `id` is not registered.
    pub fn get_mut(&mut self, id: PluginId) -> Result<&mut LoadedPlugin> {
        self.plugins.get_mut(&id).ok_or(PluginError::NotLoaded)
    }

    /// Metadata for a loaded plugin.
    ///
    /// # Errors
    ///
    /// Returns [`PluginError::NotLoaded`] when `id` is not registered.
    pub fn metadata(&self, id: PluginId) -> Result<&PluginMetadata> {
        Ok(self.get(id)?.metadata())
    }

    /// Instantiate a fresh [`AudioNode`] from a loaded plugin.
    ///
    /// Runs on the setup thread; the returned node is then moved onto the RT
    /// thread by the caller.
    ///
    /// # Errors
    ///
    /// Returns [`PluginError::NotLoaded`] when `id` is not registered.
    pub fn instantiate(&mut self, id: PluginId) -> Result<Box<dyn AudioNode>> {
        let loaded = self.get_mut(id)?;
        Ok(loaded.plugin.instantiate())
    }

    /// `true` when `id` is currently loaded.
    #[must_use]
    pub fn is_loaded(&self, id: PluginId) -> bool {
        self.plugins.contains_key(&id)
    }

    /// Number of plugins currently loaded.
    #[must_use]
    pub fn len(&self) -> usize {
        self.plugins.len()
    }

    /// `true` when no plugins are loaded.
    #[must_use]
    pub fn is_empty(&self) -> bool {
        self.plugins.is_empty()
    }

    /// All currently-registered plugin ids.
    ///
    /// The order is unspecified (iteration order of the internal map).
    #[must_use]
    pub fn ids(&self) -> Vec<PluginId> {
        self.plugins.keys().copied().collect()
    }

    /// Allocate a fresh, never-zero id. Wraps at `u32::MAX` without panicking.
    fn fresh_id(&mut self) -> PluginId {
        let id = PluginId(self.next_id);
        self.next_id = self.next_id.wrapping_add(1);
        id
    }
}

impl Default for PluginLoader {
    fn default() -> Self {
        Self::new()
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn plugin_id_is_copy_eq_hash_debug() {
        let a = PluginId(7);
        let b = a; // Copy
        assert_eq!(a, b);
        assert_eq!(format!("{a:?}"), "PluginId(7)");

        // Hash + Eq usable in a HashSet.
        let mut set = std::collections::HashSet::new();
        set.insert(a);
        assert!(set.contains(&b));
        assert!(!set.contains(&PluginId(8)));
    }

    #[test]
    fn new_loader_is_empty() {
        let loader = PluginLoader::new();
        assert!(loader.is_empty());
        assert_eq!(loader.len(), 0);
        assert!(loader.ids().is_empty());
    }

    #[test]
    fn default_equals_new() {
        let d = PluginLoader::default();
        assert!(d.is_empty());
        assert_eq!(d.len(), 0);
    }

    #[test]
    fn unload_unknown_id_is_not_loaded_err() {
        let mut loader = PluginLoader::new();
        let err = loader.unload(PluginId(0)).unwrap_err();
        assert_eq!(err, PluginError::NotLoaded);
    }

    #[test]
    fn get_unknown_id_is_not_loaded_err() {
        let loader = PluginLoader::new();
        // Map the `Ok(&LoadedPlugin)` to `Ok(())` so `unwrap_err` only needs
        // `(): Debug` (LoadedPlugin intentionally does not impl Debug).
        let err = loader.get(PluginId(42)).map(|_| ()).unwrap_err();
        assert_eq!(err, PluginError::NotLoaded);
    }

    #[test]
    fn get_mut_unknown_id_is_not_loaded_err() {
        let mut loader = PluginLoader::new();
        let err = loader.get_mut(PluginId(99)).map(|_| ()).unwrap_err();
        assert_eq!(err, PluginError::NotLoaded);
    }

    #[test]
    fn metadata_unknown_id_is_not_loaded_err() {
        let loader = PluginLoader::new();
        let err = loader.metadata(PluginId(5)).unwrap_err();
        assert_eq!(err, PluginError::NotLoaded);
    }

    #[test]
    fn instantiate_unknown_id_is_not_loaded_err() {
        let mut loader = PluginLoader::new();
        // Map the `Ok(Box<dyn AudioNode>)` to `Ok(())` so `unwrap_err` only
        // needs `(): Debug` (dyn AudioNode does not impl Debug).
        let err = loader.instantiate(PluginId(3)).map(|_| ()).unwrap_err();
        assert_eq!(err, PluginError::NotLoaded);
    }

    #[test]
    fn is_loaded_unknown_id_is_false() {
        let loader = PluginLoader::new();
        assert!(!loader.is_loaded(PluginId(0)));
        assert!(!loader.is_loaded(PluginId(u32::MAX)));
    }

    #[test]
    fn load_missing_file_is_invalid_path_err() {
        let mut loader = PluginLoader::new();
        let err = loader
            .load(Path::new("/nonexistent/path/does-not-exist.so"))
            .unwrap_err();
        assert!(matches!(err, PluginError::InvalidPath(_)));
        assert!(err.to_string().contains("not an existing file"));
    }

    #[test]
    fn load_directory_is_invalid_path_err() {
        let mut loader = PluginLoader::new();
        // The crate's own parent directory definitely exists as a non-file.
        let dir = Path::new(env!("CARGO_MANIFEST_DIR"));
        let err = loader.load(dir).unwrap_err();
        assert!(matches!(err, PluginError::InvalidPath(_)));
        assert!(err.to_string().contains("not an existing file"));
    }

    #[test]
    fn fresh_id_is_monotonic_and_does_not_panic_at_max() {
        // Simulate the wrap directly: jump next_id to MAX and observe that the
        // next allocation returns MAX and wraps to 0 without panicking.
        let mut loader = PluginLoader::new();
        loader.next_id = u32::MAX;
        let first = loader.fresh_id();
        assert_eq!(first, PluginId(u32::MAX));
        // Wrapping add — no panic.
        let second = loader.fresh_id();
        assert_eq!(second, PluginId(0));
    }
}