weaveffi/
lib.rs

1//! WeaveFFI: write safe Rust, get a stable C ABI and bindings for 11 languages.
2//!
3//! This is the single crate a Rust producer depends on. Annotate an ordinary
4//! module with [`macro@module`], tag the items you want to export, and call
5//! [`export_runtime!`] once. The [`macro@module`] expansion emits the
6//! `#[no_mangle] extern "C"` thunks that the generated language bindings call,
7//! marshalling every argument and result through the audited [`abi`] runtime so
8//! you never write `unsafe` glue by hand.
9//!
10//! ```ignore
11//! #[weaveffi::module]
12//! pub mod calculator {
13//!     /// Add two integers.
14//!     #[weaveffi::export]
15//!     pub fn add(a: i32, b: i32) -> i32 {
16//!         a + b
17//!     }
18//!
19//!     /// Divide, reporting division by zero through the ABI's error channel.
20//!     #[weaveffi::export]
21//!     pub fn div(a: i32, b: i32) -> Result<i32, String> {
22//!         if b == 0 {
23//!             return Err("division by zero".to_string());
24//!         }
25//!         Ok(a / b)
26//!     }
27//! }
28//!
29//! // Expose the fixed runtime surface (memory/error/cancel helpers) once.
30//! weaveffi::export_runtime!();
31//! ```
32//!
33//! The same annotated source is what `weaveffi generate path/to/lib.rs` reads to
34//! emit the IDL, header, and bindings, so the producer and the bindings cannot
35//! drift: they are two views of one parse.
36//!
37//! # What you get
38//!
39//! * [`macro@module`] - the driver attribute on an exported `mod`.
40//! * [`macro@export`] - export a function (`async fn` is asynchronous; a
41//!   `Result`-returning fn is fallible).
42//! * [`macro@record`] - a by-value struct with generated create/getters.
43//! * [`macro@enumeration`] - a `#[repr(i32)]` C-style enum.
44//! * [`macro@callback`] / [`macro@listener`] - a callback and an event listener.
45//! * [`macro@cancellable`] - mark an `async fn` as accepting a cancel token;
46//!   [`macro@builder`] - opt a record into a fluent builder.
47//! * [`abi`] - the C ABI runtime: the error struct, memory helpers, the
48//!   marshalling converters the expansion calls, and [`export_runtime!`].
49
50#![deny(missing_docs)]
51
52/// The stable C ABI runtime: error type, cancel tokens, memory management, and
53/// the `lift_*`/`lower_*` marshalling converters the macro expansion calls.
54///
55/// Re-exported from [`weaveffi_abi`] so producers depend on a single `weaveffi`
56/// crate; the generated thunks reference these items as `::weaveffi::abi::*`.
57pub use weaveffi_abi as abi;
58
59pub use weaveffi_abi::export_runtime;
60
61/// An owned, lazily-pulled iterator returned by a producer function whose IDL
62/// return type is `iter<T>`. Construct one from any iterator with
63/// [`Iter::new`](weaveffi_abi::Iter::new); the [`macro@module`] expansion turns
64/// it into the opaque iterator handle the generated bindings consume.
65pub use weaveffi_abi::Iter;
66
67/// A `Send` view of a foreign cancellation token, accepted as the final
68/// parameter of a `#[weaveffi::cancellable]` `async fn`. Poll
69/// [`is_cancelled`](weaveffi_abi::CancelToken::is_cancelled) at safe points and
70/// return early when it reports cancellation; the [`macro@module`] expansion
71/// supplies the token from the async launcher's `cancel_token` slot.
72pub use weaveffi_abi::CancelToken;
73
74/// Maps a producer error onto the ABI's `(code, message)` pair. A fallible
75/// `#[weaveffi::export]` function reports `Err(e)` through its trailing
76/// `out_err` slot using this trait, so every [`std::fmt::Display`] error gets
77/// the generic code `-1`, while a type that implements
78/// [`ErrorReport`] directly surfaces the named codes
79/// of an IDL error domain.
80pub use weaveffi_abi::ErrorReport;
81
82pub use weaveffi_macros::{
83    builder, callback, cancellable, enumeration, error, export, interface, listener, module, record,
84};
weaveffi/lib.rs

weaveffi/
lib.rs
