use std::collections::BTreeMap;
use std::ffi::c_void;
use astrs_wire::{
DataId, DurationMs, Metadata, ParamKey, ParamScope, Parameter, PortRef, RouteCloseReason,
StopCause, WireDecode, WireEncode,
};
use oxicode::{Decode, Encode};
use crate::error::OpResult;
use crate::event::OpEvent;
use crate::operator::{Operator, Status};
use crate::output::OpOutput;
pub const ASTRS_OPERATOR_ABI_VERSION: u32 = 1;
pub type WriteCallback = unsafe extern "C" fn(ctx: *mut c_void, ptr: *const u8, len: usize);
#[repr(C)]
#[derive(Debug, Clone, Copy)]
pub struct OperatorVTable {
pub new: unsafe extern "C" fn() -> *mut c_void,
pub on_event: unsafe extern "C" fn(
handle: *mut c_void,
call_ptr: *const u8,
call_len: usize,
write: WriteCallback,
write_ctx: *mut c_void,
) -> i32,
pub drop: unsafe extern "C" fn(handle: *mut c_void),
}
#[repr(C)]
#[derive(Debug, Clone, Copy)]
pub struct OperatorDescriptor {
pub abi_version: u32,
pub name_ptr: *const u8,
pub name_len: usize,
pub vtable: OperatorVTable,
}
#[derive(Debug, Clone, PartialEq, Encode, Decode)]
pub enum WireEvent {
#[oxicode(variant = 0)]
Input {
id: DataId,
source: PortRef,
metadata: Metadata,
payload: Vec<u8>,
},
#[oxicode(variant = 1)]
InputClosed {
id: DataId,
source: PortRef,
reason: RouteCloseReason,
},
#[oxicode(variant = 2)]
Stop {
cause: StopCause,
grace: Option<DurationMs>,
},
#[oxicode(variant = 3)]
Reload,
#[oxicode(variant = 4)]
ParamUpdate {
scope: ParamScope,
key: ParamKey,
value: Parameter,
},
}
impl From<&OpEvent> for WireEvent {
fn from(event: &OpEvent) -> Self {
match event {
OpEvent::Input {
id,
source,
metadata,
payload,
} => Self::Input {
id: id.clone(),
source: source.clone(),
metadata: metadata.clone(),
payload: payload.clone(),
},
OpEvent::InputClosed { id, source, reason } => Self::InputClosed {
id: id.clone(),
source: source.clone(),
reason: reason.clone(),
},
OpEvent::Stop { cause, grace } => Self::Stop {
cause: cause.clone(),
grace: *grace,
},
OpEvent::Reload => Self::Reload,
OpEvent::ParamUpdate { scope, key, value } => Self::ParamUpdate {
scope: scope.clone(),
key: key.clone(),
value: value.clone(),
},
}
}
}
impl From<WireEvent> for OpEvent {
fn from(event: WireEvent) -> Self {
match event {
WireEvent::Input {
id,
source,
metadata,
payload,
} => Self::Input {
id,
source,
metadata,
payload,
},
WireEvent::InputClosed { id, source, reason } => {
Self::InputClosed { id, source, reason }
}
WireEvent::Stop { cause, grace } => Self::Stop { cause, grace },
WireEvent::Reload => Self::Reload,
WireEvent::ParamUpdate { scope, key, value } => Self::ParamUpdate { scope, key, value },
}
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Encode, Decode)]
pub enum WireStatus {
#[oxicode(variant = 0)]
Continue,
#[oxicode(variant = 1)]
Finished,
}
impl From<Status> for WireStatus {
fn from(status: Status) -> Self {
match status {
Status::Continue => Self::Continue,
Status::Finished => Self::Finished,
}
}
}
impl From<WireStatus> for Status {
fn from(status: WireStatus) -> Self {
match status {
WireStatus::Continue => Self::Continue,
WireStatus::Finished => Self::Finished,
}
}
}
#[derive(Debug, Clone, PartialEq, Encode, Decode)]
pub enum DylibCall {
#[oxicode(variant = 0)]
Configure(BTreeMap<String, Parameter>),
#[oxicode(variant = 1)]
OnStart,
#[oxicode(variant = 2)]
OnEvent(WireEvent),
#[oxicode(variant = 3)]
OnStop,
#[oxicode(variant = 4)]
OnReload,
}
impl DylibCall {
#[must_use]
pub fn on_event(event: &OpEvent) -> Self {
Self::OnEvent(WireEvent::from(event))
}
}
#[derive(Debug, Clone, PartialEq, Encode, Decode)]
pub enum DylibReply {
#[oxicode(variant = 0)]
Ok {
status: WireStatus,
sends: Vec<(DataId, Metadata, Vec<u8>)>,
},
#[oxicode(variant = 1)]
Err {
message: String,
},
}
fn panic_message(payload: &(dyn std::any::Any + Send + 'static)) -> String {
if let Some(message) = payload.downcast_ref::<&str>() {
(*message).to_owned()
} else if let Some(message) = payload.downcast_ref::<String>() {
message.clone()
} else {
"operator panicked with a non-string payload".to_owned()
}
}
fn dispatch<T: Operator>(operator: &mut T, call: DylibCall) -> DylibReply {
let mut out = OpOutput::new();
let outcome: OpResult<WireStatus> = match call {
DylibCall::Configure(config) => operator.configure(&config).map(|()| WireStatus::Continue),
DylibCall::OnStart => operator.on_start(&mut out).map(|()| WireStatus::Continue),
DylibCall::OnEvent(wire_event) => operator
.on_event(&OpEvent::from(wire_event), &mut out)
.map(WireStatus::from),
DylibCall::OnStop => operator.on_stop(&mut out).map(|()| WireStatus::Continue),
DylibCall::OnReload => operator.on_reload(&mut out).map(|()| WireStatus::Continue),
};
match outcome {
Ok(status) => DylibReply::Ok {
status,
sends: out
.drain()
.into_iter()
.map(crate::output::OpSend::into_parts)
.collect(),
},
Err(error) => DylibReply::Err {
message: error.to_string(),
},
}
}
pub extern "C" fn new_operator<T: Operator + Default>() -> *mut c_void {
match std::panic::catch_unwind(T::default) {
Ok(operator) => Box::into_raw(Box::new(operator)).cast::<c_void>(),
Err(_) => std::ptr::null_mut(),
}
}
pub unsafe extern "C" fn on_event_operator<T: Operator>(
handle: *mut c_void,
call_ptr: *const u8,
call_len: usize,
write: WriteCallback,
write_ctx: *mut c_void,
) -> i32 {
if handle.is_null() {
return -1;
}
let outcome = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
let operator = unsafe { &mut *handle.cast::<T>() };
let bytes = unsafe { std::slice::from_raw_parts(call_ptr, call_len) };
match DylibCall::decode_exact(bytes) {
Ok(call) => dispatch(operator, call),
Err(error) => DylibReply::Err {
message: format!("malformed call from host: {error}"),
},
}
}));
let reply = outcome.unwrap_or_else(|payload| DylibReply::Err {
message: format!(
"operator panicked inside dylib: {}",
panic_message(&*payload)
),
});
let encoded = reply.encode_to_vec().unwrap_or_default();
let write_outcome = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
unsafe { write(write_ctx, encoded.as_ptr(), encoded.len()) };
}));
if write_outcome.is_err() { -1 } else { 0 }
}
pub unsafe extern "C" fn drop_operator<T>(handle: *mut c_void) {
if handle.is_null() {
return;
}
let _ = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
drop(unsafe { Box::from_raw(handle.cast::<T>()) });
}));
}
#[macro_export]
macro_rules! export_dylib_operator {
($ty:ty) => {
#[unsafe(no_mangle)]
pub extern "C" fn astrs_operator_descriptor() -> $crate::dylib::OperatorDescriptor {
const NAME: &str = ::core::stringify!($ty);
$crate::dylib::OperatorDescriptor {
abi_version: $crate::dylib::ASTRS_OPERATOR_ABI_VERSION,
name_ptr: NAME.as_ptr(),
name_len: NAME.len(),
vtable: $crate::dylib::OperatorVTable {
new: $crate::dylib::new_operator::<$ty>,
on_event: $crate::dylib::on_event_operator::<$ty>,
drop: $crate::dylib::drop_operator::<$ty>,
},
}
}
};
($name:expr => $ty:ty) => {
#[unsafe(no_mangle)]
pub extern "C" fn astrs_operator_descriptor() -> $crate::dylib::OperatorDescriptor {
const NAME: &str = $name;
$crate::dylib::OperatorDescriptor {
abi_version: $crate::dylib::ASTRS_OPERATOR_ABI_VERSION,
name_ptr: NAME.as_ptr(),
name_len: NAME.len(),
vtable: $crate::dylib::OperatorVTable {
new: $crate::dylib::new_operator::<$ty>,
on_event: $crate::dylib::on_event_operator::<$ty>,
drop: $crate::dylib::drop_operator::<$ty>,
},
}
}
};
}
#[cfg(test)]
mod tests {
#![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
use super::*;
use crate::operator::Status;
use astrs_time::HlcTimestamp;
use astrs_wire::Metadata;
#[derive(Default)]
struct Recording {
configured_with: Option<i64>,
started: bool,
stopped: bool,
reloaded: bool,
}
impl Operator for Recording {
fn configure(&mut self, config: &BTreeMap<String, Parameter>) -> OpResult<()> {
if let Some(Parameter::Integer(value)) = config.get("threshold") {
self.configured_with = Some(*value);
}
Ok(())
}
fn on_start(&mut self, out: &mut OpOutput) -> OpResult<()> {
self.started = true;
out.send_bytes("status", meta(), b"started".to_vec())?;
Ok(())
}
fn on_event(&mut self, event: &OpEvent, out: &mut OpOutput) -> OpResult<Status> {
match event {
OpEvent::Input {
metadata, payload, ..
} => {
out.send_bytes("out", metadata.clone(), payload.clone())?;
Ok(Status::Continue)
}
OpEvent::Stop { .. } => Ok(Status::Finished),
_ => Ok(Status::Continue),
}
}
fn on_stop(&mut self, out: &mut OpOutput) -> OpResult<()> {
self.stopped = true;
out.send_bytes("status", meta(), b"stopped".to_vec())?;
Ok(())
}
fn on_reload(&mut self, _out: &mut OpOutput) -> OpResult<()> {
self.reloaded = true;
Ok(())
}
}
#[derive(Default)]
struct AlwaysPanics;
impl Operator for AlwaysPanics {
fn on_event(&mut self, _event: &OpEvent, _out: &mut OpOutput) -> OpResult<Status> {
panic!("boom");
}
}
fn meta() -> Metadata {
Metadata::new(HlcTimestamp::EPOCH)
}
fn input_event(payload: Vec<u8>) -> OpEvent {
OpEvent::Input {
id: DataId::new("frames").unwrap(),
source: "camera/image".parse().unwrap(),
metadata: meta(),
payload,
}
}
unsafe extern "C" fn collecting_write(ctx: *mut c_void, ptr: *const u8, len: usize) {
let collected = unsafe { &mut *ctx.cast::<Vec<u8>>() };
let bytes = unsafe { std::slice::from_raw_parts(ptr, len) };
collected.extend_from_slice(bytes);
}
fn drive(vtable: &OperatorVTable, handle: *mut c_void, call: &DylibCall) -> DylibReply {
let bytes = call.encode_to_vec().unwrap();
let mut collected: Vec<u8> = Vec::new();
let status = unsafe {
(vtable.on_event)(
handle,
bytes.as_ptr(),
bytes.len(),
collecting_write,
std::ptr::from_mut(&mut collected).cast::<c_void>(),
)
};
assert_eq!(status, 0, "on_event must always answer through `write`");
DylibReply::decode_exact(&collected).unwrap()
}
#[test]
fn wire_event_round_trips_every_op_event_variant() {
let events = [
input_event(vec![1, 2, 3]),
OpEvent::InputClosed {
id: DataId::new("frames").unwrap(),
source: "camera/image".parse().unwrap(),
reason: RouteCloseReason::ProducerFinished,
},
OpEvent::Stop {
cause: StopCause::Requested,
grace: None,
},
OpEvent::Reload,
OpEvent::ParamUpdate {
scope: ParamScope::Global,
key: ParamKey::new("gain").unwrap(),
value: Parameter::Float(1.5),
},
];
for event in events {
let wire = WireEvent::from(&event);
let back: OpEvent = wire.clone().into();
assert_eq!(back, event, "{wire:?} did not round-trip");
let bytes = wire.encode_to_vec().unwrap();
let decoded = WireEvent::decode_exact(&bytes).unwrap();
assert_eq!(decoded, wire);
}
}
#[test]
fn dylib_call_and_reply_round_trip_through_the_wire_codec() {
let call = DylibCall::on_event(&input_event(vec![9]));
let bytes = call.encode_to_vec().unwrap();
assert_eq!(DylibCall::decode_exact(&bytes).unwrap(), call);
let reply = DylibReply::Ok {
status: WireStatus::Finished,
sends: vec![(DataId::new("out").unwrap(), meta(), vec![1, 2, 3])],
};
let bytes = reply.encode_to_vec().unwrap();
assert_eq!(DylibReply::decode_exact(&bytes).unwrap(), reply);
let err = DylibReply::Err {
message: "boom".to_owned(),
};
let bytes = err.encode_to_vec().unwrap();
assert_eq!(DylibReply::decode_exact(&bytes).unwrap(), err);
}
#[test]
fn status_mirrors_both_directions() {
assert_eq!(WireStatus::from(Status::Continue), WireStatus::Continue);
assert_eq!(WireStatus::from(Status::Finished), WireStatus::Finished);
assert_eq!(Status::from(WireStatus::Continue), Status::Continue);
assert_eq!(Status::from(WireStatus::Finished), Status::Finished);
}
export_dylib_operator!(Recording);
#[test]
fn the_generated_descriptor_names_the_type_and_declares_the_current_abi_version() {
let descriptor = astrs_operator_descriptor();
assert_eq!(descriptor.abi_version, ASTRS_OPERATOR_ABI_VERSION);
let name = unsafe { std::slice::from_raw_parts(descriptor.name_ptr, descriptor.name_len) };
assert_eq!(std::str::from_utf8(name).unwrap(), "Recording");
}
#[test]
fn the_generated_vtable_drives_every_hook_through_on_event() {
let descriptor = astrs_operator_descriptor();
let vtable = descriptor.vtable;
let handle = unsafe { (vtable.new)() };
assert!(!handle.is_null());
let mut config = BTreeMap::new();
config.insert("threshold".to_owned(), Parameter::Integer(7));
match drive(&vtable, handle, &DylibCall::Configure(config)) {
DylibReply::Ok { .. } => {}
other => panic!("configure failed: {other:?}"),
}
match drive(&vtable, handle, &DylibCall::OnStart) {
DylibReply::Ok { sends, .. } => {
assert_eq!(sends.len(), 1);
assert_eq!(sends[0].0.as_str(), "status");
assert_eq!(sends[0].2, b"started".to_vec());
}
other => panic!("on_start failed: {other:?}"),
}
match drive(&vtable, handle, &DylibCall::on_event(&input_event(vec![9]))) {
DylibReply::Ok { status, sends } => {
assert_eq!(status, WireStatus::Continue);
assert_eq!(sends.len(), 1);
assert_eq!(sends[0].2, vec![9]);
}
other => panic!("on_event failed: {other:?}"),
}
match drive(&vtable, handle, &DylibCall::OnReload) {
DylibReply::Ok { .. } => {}
other => panic!("on_reload failed: {other:?}"),
}
let stop_event = OpEvent::Stop {
cause: StopCause::Requested,
grace: None,
};
match drive(&vtable, handle, &DylibCall::on_event(&stop_event)) {
DylibReply::Ok { status, .. } => assert_eq!(status, WireStatus::Finished),
other => panic!("stop event failed: {other:?}"),
}
match drive(&vtable, handle, &DylibCall::OnStop) {
DylibReply::Ok { sends, .. } => {
assert_eq!(sends[0].2, b"stopped".to_vec());
}
other => panic!("on_stop failed: {other:?}"),
}
unsafe { (vtable.drop)(handle) };
}
#[test]
fn a_panicking_on_event_becomes_an_err_reply_not_a_process_abort() {
let handle = new_operator::<AlwaysPanics>();
assert!(!handle.is_null());
let vtable = OperatorVTable {
new: new_operator::<AlwaysPanics>,
on_event: on_event_operator::<AlwaysPanics>,
drop: drop_operator::<AlwaysPanics>,
};
match drive(&vtable, handle, &DylibCall::on_event(&input_event(vec![1]))) {
DylibReply::Err { message } => {
assert!(message.contains("boom"), "message was: {message}")
}
other => panic!("expected Err, got {other:?}"),
}
unsafe { (vtable.drop)(handle) };
}
#[test]
fn a_malformed_call_is_reported_rather_than_crashing() {
let handle = new_operator::<Recording>();
assert!(!handle.is_null());
let vtable = OperatorVTable {
new: new_operator::<Recording>,
on_event: on_event_operator::<Recording>,
drop: drop_operator::<Recording>,
};
let garbage = b"not a valid DylibCall";
let mut collected: Vec<u8> = Vec::new();
let status = unsafe {
(vtable.on_event)(
handle,
garbage.as_ptr(),
garbage.len(),
collecting_write,
std::ptr::from_mut(&mut collected).cast::<c_void>(),
)
};
assert_eq!(status, 0);
match DylibReply::decode_exact(&collected).unwrap() {
DylibReply::Err { message } => assert!(message.contains("malformed call")),
other => panic!("expected Err, got {other:?}"),
}
unsafe { (vtable.drop)(handle) };
}
#[test]
fn new_operator_returns_null_on_a_panicking_default() {
struct PanicsOnDefault;
impl Default for PanicsOnDefault {
fn default() -> Self {
panic!("no default for you");
}
}
impl Operator for PanicsOnDefault {
fn on_event(&mut self, _event: &OpEvent, _out: &mut OpOutput) -> OpResult<Status> {
Ok(Status::Continue)
}
}
assert!(new_operator::<PanicsOnDefault>().is_null());
}
#[test]
fn drop_operator_on_null_is_a_no_op() {
unsafe { drop_operator::<Recording>(std::ptr::null_mut()) };
}
}