use crate::{Error, Result, abi, export, loader::Library, status_result};
#[cfg(feature = "alloc")]
use alloc::{boxed::Box, rc::Rc, vec::Vec};
use core::{
cell::Cell,
ffi::{CStr, c_void},
marker::PhantomData,
ops::Deref,
ptr::NonNull,
};
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum UnloadPolicy {
Pinned,
Cooperative,
}
#[derive(Clone, Copy, Debug)]
pub struct InterfaceSpec {
pub id: &'static str,
pub version: u32,
pub signatures: &'static [&'static str],
}
pub struct Plugin {
library: Option<Library>,
descriptor: NonNull<abi::PluginDescriptor>,
policy: UnloadPolicy,
pinned: Cell<bool>,
_local: PhantomData<*mut ()>,
}
impl Plugin {
pub unsafe fn load(path: &CStr) -> Result<Self> {
unsafe { Self::load_policy(path, UnloadPolicy::Pinned) }
}
pub unsafe fn load_cooperative(path: &CStr) -> Result<Self> {
unsafe { Self::load_policy(path, UnloadPolicy::Cooperative) }
}
unsafe fn load_policy(path: &CStr, policy: UnloadPolicy) -> Result<Self> {
let library = unsafe { Library::open(path)? };
unsafe { Self::from_library(library, policy) }
}
#[cfg(windows)]
pub unsafe fn load_wide(path: &[u16], policy: UnloadPolicy) -> Result<Self> {
let library = unsafe { Library::open_wide(path)? };
unsafe { Self::from_library(library, policy) }
}
#[cfg(feature = "std")]
pub unsafe fn load_path(
path: impl AsRef<std::path::Path>,
policy: UnloadPolicy,
) -> Result<Self> {
let path = std::fs::canonicalize(path).map_err(|_| Error::LoadFailed)?;
#[cfg(unix)]
{
use std::os::unix::ffi::OsStrExt;
let path = std::ffi::CString::new(path.as_os_str().as_bytes())
.map_err(|_| Error::InvalidArgument)?;
unsafe { Self::load_policy(&path, policy) }
}
#[cfg(windows)]
{
use std::os::windows::ffi::OsStrExt;
let path: Vec<u16> = path
.as_os_str()
.encode_wide()
.chain(core::iter::once(0))
.collect();
let library = unsafe { Library::open_wide(&path)? };
unsafe { Self::from_library(library, policy) }
}
#[cfg(not(any(unix, windows)))]
{
let _ = (path, policy);
Err(Error::Unsupported)
}
}
unsafe fn from_library(mut library: Library, policy: UnloadPolicy) -> Result<Self> {
let result = (|| {
let symbol = library.symbol(abi::ENTRY)?;
let entry: abi::Entry = unsafe { core::mem::transmute(symbol) };
let descriptor = unsafe { validate_descriptor(entry())? };
let value = unsafe { descriptor.as_ref() };
if policy == UnloadPolicy::Cooperative
&& (value.flags & abi::COOPERATIVE == 0 || value.quiesce.is_none())
{
return Err(Error::Unsupported);
}
Ok(descriptor)
})();
match result {
Ok(descriptor) => Ok(Self {
library: Some(library),
descriptor,
policy,
pinned: Cell::new(false),
_local: PhantomData,
}),
Err(error) => {
if policy == UnloadPolicy::Cooperative {
let _ = unsafe { library.close() };
}
Err(error)
}
}
}
pub unsafe fn from_static(header: &'static abi::Header) -> Result<Self> {
Ok(Self {
library: None,
descriptor: unsafe { validate_descriptor(header)? },
policy: UnloadPolicy::Pinned,
pinned: Cell::new(false),
_local: PhantomData,
})
}
fn descriptor(&self) -> &abi::PluginDescriptor {
unsafe { self.descriptor.as_ref() }
}
pub fn version(&self) -> abi::Version {
self.descriptor().plugin_version
}
pub fn unload_policy(&self) -> UnloadPolicy {
self.policy
}
pub fn pin(&self) {
self.pinned.set(true);
}
#[cfg(feature = "hot-reload")]
pub(crate) fn same_image(&self, other: &Self) -> bool {
match (&self.library, &other.library) {
(Some(a), Some(b)) => a.same_image(b),
(None, None) => self.descriptor == other.descriptor,
_ => false,
}
}
#[cfg(feature = "hot-reload")]
pub(crate) fn discard_duplicate(mut self, other: &Self) {
assert!(self.same_image(other));
if let Some(mut library) = self.library.take() {
if unsafe { library.close() }.is_err() {
other.pin();
}
}
}
pub fn bind(&self, spec: InterfaceSpec) -> Result<Binding<'_>> {
Ok(Binding {
descriptor: self.find(spec)?,
spec,
lease: Lease::Borrowed(self),
})
}
#[cfg(feature = "alloc")]
pub fn create_owned(plugin: &Rc<Self>, spec: InterfaceSpec) -> Result<Instance<'static>> {
Binding {
descriptor: plugin.find(spec)?,
spec,
lease: Lease::Shared(Rc::clone(plugin)),
}
.create()
}
fn find(&self, spec: InterfaceSpec) -> Result<NonNull<abi::InterfaceDescriptor>> {
let descriptor = self.descriptor();
if descriptor.interface_count > 4096 {
return Err(Error::InvalidDescriptor);
}
if descriptor.interface_count != 0 {
export::check_pointer(descriptor.interfaces)?;
}
for i in 0..descriptor.interface_count as usize {
let ptr = unsafe { descriptor.interfaces.add(i).read() };
export::check_pointer(ptr)?;
let size = unsafe { ptr.cast::<u32>().read() };
require_size(size, core::mem::size_of::<abi::InterfaceDescriptor>())?;
let interface = unsafe { &*ptr };
let id = unsafe { interface.id.as_slice()? };
if id != spec.id.as_bytes() {
continue;
}
if interface.version != spec.version {
return Err(Error::InterfaceVersion {
expected: spec.version,
actual: interface.version,
});
}
if interface.method_count as usize != spec.signatures.len() {
return Err(Error::MissingMethod {
method: interface.method_count.min(spec.signatures.len() as u32),
});
}
if interface.create.is_none() || interface.destroy.is_none() {
return Err(Error::InvalidDescriptor);
}
if interface.method_count != 0 {
export::check_pointer(interface.methods)?;
}
for (index, signature) in spec.signatures.iter().enumerate() {
let method = unsafe { &*interface.methods.add(index) };
if method.call.is_none() {
return Err(Error::MissingMethod {
method: index as u32,
});
}
if unsafe { method.signature.as_slice()? } != signature.as_bytes() {
return Err(Error::SignatureMismatch {
method: index as u32,
});
}
}
return NonNull::new(ptr.cast_mut()).ok_or(Error::InvalidDescriptor);
}
Err(Error::InterfaceNotFound)
}
pub fn try_close(mut self) -> core::result::Result<(), (Error, Self)> {
if let Err(error) = self.close() {
return Err((error, self));
}
Ok(())
}
fn close(&mut self) -> Result<()> {
if self.library.is_none() {
return Ok(());
}
if self.policy != UnloadPolicy::Cooperative || self.pinned.get() {
return Err(Error::Busy);
}
let quiesce = self.descriptor().quiesce.ok_or(Error::Unsupported)?;
status_result(unsafe { quiesce() })?;
unsafe {
self.library.as_mut().unwrap().close()?;
}
self.library = None;
Ok(())
}
}
impl Drop for Plugin {
fn drop(&mut self) {
let _ = self.close();
}
}
fn require_size(actual: u32, expected: usize) -> Result<()> {
if (actual as usize) < expected {
Err(Error::DescriptorTooShort {
expected: expected as u32,
actual,
})
} else {
Ok(())
}
}
unsafe fn validate_descriptor(
header: *const abi::Header,
) -> Result<NonNull<abi::PluginDescriptor>> {
export::check_pointer(header)?;
let value = unsafe { header.read() };
if value.magic != abi::MAGIC {
return Err(Error::BadMagic);
}
if value.major != abi::ABI_MAJOR {
return Err(Error::AbiVersion { found: value.major });
}
require_size(value.size, core::mem::size_of::<abi::PluginDescriptor>())?;
let ptr = header.cast::<abi::PluginDescriptor>();
export::check_pointer(ptr)?;
NonNull::new(ptr.cast_mut()).ok_or(Error::InvalidDescriptor)
}
pub(crate) enum Lease<'a> {
Borrowed(&'a Plugin),
#[cfg(feature = "alloc")]
Shared(Rc<Plugin>),
}
impl Clone for Lease<'_> {
fn clone(&self) -> Self {
match self {
Self::Borrowed(plugin) => Self::Borrowed(plugin),
#[cfg(feature = "alloc")]
Self::Shared(plugin) => Self::Shared(Rc::clone(plugin)),
}
}
}
impl Lease<'_> {
pub(crate) fn plugin(&self) -> &Plugin {
match self {
Self::Borrowed(plugin) => plugin,
#[cfg(feature = "alloc")]
Self::Shared(plugin) => plugin,
}
}
}
pub struct Binding<'a> {
descriptor: NonNull<abi::InterfaceDescriptor>,
spec: InterfaceSpec,
lease: Lease<'a>,
}
impl<'a> Binding<'a> {
pub fn method(&self, index: usize) -> abi::Call {
assert!(index < self.spec.signatures.len());
unsafe { (*self.descriptor.as_ref().methods.add(index)).call.unwrap() }
}
pub fn create(&self) -> Result<Instance<'a>> {
let descriptor = unsafe { self.descriptor.as_ref() };
let mut object = core::ptr::null_mut();
let status = unsafe { descriptor.create.unwrap()(&mut object) };
if let Err(error) = status_result(status) {
if !object.is_null() || error == Error::Panicked {
self.lease.plugin().pin();
}
return Err(error);
}
let handle = NonNull::new(object).ok_or(Error::NullObject)?;
Ok(Instance {
handle,
descriptor: self.descriptor,
spec: self.spec,
lease: self.lease.clone(),
})
}
}
pub struct Instance<'a> {
handle: NonNull<c_void>,
descriptor: NonNull<abi::InterfaceDescriptor>,
spec: InterfaceSpec,
lease: Lease<'a>,
}
impl<'a> Instance<'a> {
pub fn handle(&self) -> *mut c_void {
self.handle.as_ptr()
}
pub fn check(&self, spec: InterfaceSpec) -> Result<()> {
if self.spec.id != spec.id {
return Err(Error::InterfaceNotFound);
}
if self.spec.version != spec.version {
return Err(Error::InterfaceVersion {
expected: spec.version,
actual: self.spec.version,
});
}
if self.spec.signatures != spec.signatures {
return Err(Error::SignatureMismatch { method: 0 });
}
Ok(())
}
pub fn method(&self, index: usize) -> abi::Call {
assert!(index < self.spec.signatures.len());
unsafe { (*self.descriptor.as_ref().methods.add(index)).call.unwrap() }
}
pub unsafe fn buffer(&self, raw: abi::RawBuffer) -> Result<Buffer<'a>> {
let owned = unsafe { OwnedBytes::from_raw(raw)? };
Ok(Buffer {
owned,
lease: self.lease.clone(),
})
}
pub unsafe fn task<T: crate::AbiValue>(&self, raw: abi::RawTask) -> Result<crate::Task<'a, T>> {
unsafe { crate::task::Task::new_owned(raw, self.lease.clone()) }
}
pub unsafe fn resource(&self, raw: abi::RawResource) -> Result<crate::Resource<'a>> {
unsafe { crate::resource::Resource::new_owned(raw, self.lease.clone()) }
}
}
impl Drop for Instance<'_> {
fn drop(&mut self) {
let destroy = unsafe { self.descriptor.as_ref().destroy.unwrap() };
if unsafe { destroy(self.handle.as_ptr()) } != 0 {
self.lease.plugin().pin();
}
}
}
pub struct OwnedBytes {
raw: Option<abi::RawBuffer>,
}
impl OwnedBytes {
pub unsafe fn from_raw(raw: abi::RawBuffer) -> Result<Self> {
abi::validate_range(raw.data, raw.len)?;
if raw.release.is_none() {
return Err(Error::InvalidArgument);
}
Ok(Self { raw: Some(raw) })
}
#[cfg(feature = "alloc")]
pub fn from_vec(value: Vec<u8>) -> Self {
let bytes = value.into_boxed_slice();
let len = bytes.len();
let data = Box::into_raw(bytes).cast::<u8>();
export::resource_acquired();
Self {
raw: Some(abi::RawBuffer {
data,
len,
context: core::ptr::null_mut(),
release: Some(release_boxed),
}),
}
}
pub fn into_raw(mut self) -> abi::RawBuffer {
self.raw.take().unwrap()
}
fn release(&mut self) -> i32 {
self.raw.take().map_or(0, |raw| unsafe {
raw.release.unwrap()(raw.context, raw.data, raw.len)
})
}
}
impl Deref for OwnedBytes {
type Target = [u8];
fn deref(&self) -> &[u8] {
let raw = self.raw.as_ref().unwrap();
unsafe {
abi::Bytes {
ptr: raw.data,
len: raw.len,
}
.as_slice()
.unwrap()
}
}
}
impl Drop for OwnedBytes {
fn drop(&mut self) {
let _ = self.release();
}
}
#[cfg(feature = "alloc")]
unsafe extern "C" fn release_boxed(_: *mut c_void, data: *const u8, len: usize) -> i32 {
export::guard(|| {
let slice = core::ptr::slice_from_raw_parts_mut(data.cast_mut(), len);
unsafe {
drop(Box::from_raw(slice));
}
export::resource_released();
Ok(())
})
}
pub struct Buffer<'a> {
owned: OwnedBytes,
lease: Lease<'a>,
}
impl Deref for Buffer<'_> {
type Target = [u8];
fn deref(&self) -> &[u8] {
&self.owned
}
}
impl Drop for Buffer<'_> {
fn drop(&mut self) {
if self.owned.release() != 0 {
self.lease.plugin().pin();
}
}
}