dyn_loader/lib.rs
1//! # dyn-loader
2//!
3//! Dynamic library loader with two plugin-loading modes:
4//!
5//! ## [`dyn`] — Rust fat-pointer bridge (trait objects)
6//!
7//! Load Rust trait objects from `.so`/`.dylib` plugins via their native
8//! fat-pointer representation (data + vtable), with Arc-like retain/release
9//! for cross-boundary memory safety.
10//!
11//! ```ignore
12//! // In the plugin .so:
13//! #[no_mangle]
14//! pub extern "C" fn core_ast_transform_entry() -> AbiStableDynRef {
15//! SafeArcDyn::from_arc(Arc::new(MyTransform) as Arc<dyn Transform>).into_abi()
16//! }
17//!
18//! // In the host:
19//! use dyn_loader::dyn::{DynPlugin, AbiStableDynRef};
20//! let plugin = DynPlugin::<dyn Transform>::load("libmy_transform.so", b"core_ast_transform_entry\0")?;
21//! let transform: &dyn Transform = plugin.trait_ref();
22//! ```
23//!
24//! ## [`cdyn`] — COM-style C function tables (ABI-stable)
25//!
26//! Load plain C function-table structs (`#[repr(C)]` Copy types) via
27//! positional dispatch — no trait objects, stable across languages and
28//! (to a large extent) compiler versions. This is the former `cdyn-loader`
29//! crate, merged here as `VTablePlugin<T>`.
30//!
31//! ```ignore
32//! let plugin = unsafe { VTablePlugin::<MyVtable>::load("libmy.so", b"my_get_vtable\0")? };
33//! ```
34//!
35//! ## ⚠️ ABI compatibility / compiler version alignment
36//!
37//! Even though [`cdyn`] mode is layout-stable, the Rust compiler version must
38//! still be strictly aligned across all libraries and executables that
39//! exchange pointers across the boundary. Pin one toolchain (e.g. via
40//! `rust-toolchain.toml`) and rebuild everything together. See the README for
41//! the full cross-version compatibility matrix.
42
43#[path = "dyn.rs"]
44pub mod dyn_mod;
45pub mod cdyn;
46mod helpers;
47
48pub use dyn_mod::{
49 AbiDynFatPtr, AbiStableDynRef, DynPlugin, PluginEntryPoint, ReleaseFn, RetainFn, SafeArcDyn,
50 pack_fat_ptr, unpack_fat_ptr,
51};
52pub use cdyn::{
53 CdynHandle, GeneratedFunction, MathModuleVtable, MathSession, PluginDynEntryPoint,
54 VTablePlugin,
55};
56pub use helpers::{DynLib, looks_like_plugin};