| 1 | #![doc (html_root_url = "https://docs.rs/libffi/3.2.0" )] |
| 2 | //! Rust bindings for [libffi](https://sourceware.org/libffi/). |
|---|
| 3 | //! |
|---|
| 4 | //! The C libffi library provides two main facilities: assembling calls |
|---|
| 5 | //! to functions dynamically, and creating closures that can be called |
|---|
| 6 | //! as ordinary C functions. In Rust, the latter means that we can turn |
|---|
| 7 | //! a Rust lambda (or any object implementing [`Fn`]/[`FnMut`]) into an |
|---|
| 8 | //! ordinary C function pointer that we can pass as a callback to C. |
|---|
| 9 | //! |
|---|
| 10 | //! The easiest way to use this library is via the |
|---|
| 11 | //! [`mod@high`] layer module, but more flexibility (and |
|---|
| 12 | //! less checking) is provided by the [`mod@middle`] and |
|---|
| 13 | //! [`mod@low`] layers. |
|---|
| 14 | //! |
|---|
| 15 | //! # Usage |
|---|
| 16 | //! |
|---|
| 17 | //! Building libffi will build lifbffi-sys, which will in turn build the |
|---|
| 18 | //! libffi C library [from github](https://github.com/libffi/libffi), which |
|---|
| 19 | //! requires that you have a working make, C compiler, automake, and |
|---|
| 20 | //! autoconf first. It’s [on crates.io](https://crates.io/crates/libffi), so |
|---|
| 21 | //! you can add |
|---|
| 22 | //! |
|---|
| 23 | //! ```toml |
|---|
| 24 | //! [dependencies] |
|---|
| 25 | //! libffi = "3.2.0" |
|---|
| 26 | //! ``` |
|---|
| 27 | //! |
|---|
| 28 | //! This crate depends on [the `libffi-sys` crate], which by default |
|---|
| 29 | //! attempts to build its own version of the C libffi library. In order to |
|---|
| 30 | //! use your system’s C libffi instead, enable this crate’s `system` |
|---|
| 31 | //! feature in your `Cargo.toml`: |
|---|
| 32 | //! |
|---|
| 33 | //! ```toml |
|---|
| 34 | //! [features] |
|---|
| 35 | //! libffi = { version = "3.2.0", features = ["system"] } |
|---|
| 36 | //! ``` |
|---|
| 37 | //! |
|---|
| 38 | //! See [the `libffi-sys` documentation] for more information about how it |
|---|
| 39 | //! finds C libffi. |
|---|
| 40 | //! |
|---|
| 41 | //! This crate supports Rust version 1.48 and later. |
|---|
| 42 | //! |
|---|
| 43 | //! # Organization |
|---|
| 44 | //! |
|---|
| 45 | //! This library is organized in four layers, each of which attempts to |
|---|
| 46 | //! provide more safety and a simpler interface than the next layer |
|---|
| 47 | //! down. From top to bottom: |
|---|
| 48 | //! |
|---|
| 49 | //! - The [`mod@high`] layer provides safe(?) and |
|---|
| 50 | //! automatic marshalling of Rust closures into C function pointers. |
|---|
| 51 | //! - The [`mod@middle`] layer provides memory-managed |
|---|
| 52 | //! abstractions for assembling calls and closures, but is unsafe |
|---|
| 53 | //! because it doesn’t check argument types. |
|---|
| 54 | //! - The [`mod@low`] layer makes no attempts at safety, |
|---|
| 55 | //! but provides a more idiomatically “Rusty” API than the underlying |
|---|
| 56 | //! C library. |
|---|
| 57 | //! - The [`mod@raw`] layer is a re-export of the |
|---|
| 58 | //! [`libffi-sys`](https://crates.io/crates/libffi-sys) crate, |
|---|
| 59 | //! a direct mapping of the C libffi library into Rust, generated by |
|---|
| 60 | //! [bindgen](https://crates.io/crates/bindgen). |
|---|
| 61 | //! |
|---|
| 62 | //! It should be possible to use any layer without dipping into lower |
|---|
| 63 | //! layers (and it will be considered a bug to the extent that it |
|---|
| 64 | //! isn’t). |
|---|
| 65 | //! |
|---|
| 66 | //! # Examples |
|---|
| 67 | //! |
|---|
| 68 | //! In this example, we convert a Rust lambda containing a free variable |
|---|
| 69 | //! into an ordinary C code pointer. The type of `fun` below is |
|---|
| 70 | //! `extern "C" fn(u64, u64) -> u64`. |
|---|
| 71 | //! |
|---|
| 72 | //! ``` |
|---|
| 73 | //! use libffi::high::Closure2; |
|---|
| 74 | //! |
|---|
| 75 | //! let x = 5u64; |
|---|
| 76 | //! let f = |y: u64, z: u64| x + y + z; |
|---|
| 77 | //! |
|---|
| 78 | //! let closure = Closure2::new(&f); |
|---|
| 79 | //! let fun = closure.code_ptr(); |
|---|
| 80 | //! |
|---|
| 81 | //! assert_eq!(18, fun.call(6, 7)); |
|---|
| 82 | //! ``` |
|---|
| 83 | //! |
|---|
| 84 | //! [the `libffi-sys` crate]: https://crates.io/crates/libffi-sys/ |
|---|
| 85 | //! |
|---|
| 86 | //! [the `libffi-sys` documentation]: https://docs.rs/libffi-sys/#usage |
|---|
| 87 | //! |
|---|
| 88 | |
|---|
| 89 | #![deny (missing_docs)] |
|---|
| 90 | |
|---|
| 91 | /// Raw definitions imported from the C library (via bindgen). |
|---|
| 92 | /// |
|---|
| 93 | /// This module is generated by bindgen and undocumented. It’s intended |
|---|
| 94 | /// as the basis for higher-level bindings. |
|---|
| 95 | pub mod raw { |
|---|
| 96 | pub use libffi_sys::*; |
|---|
| 97 | } |
|---|
| 98 | |
|---|
| 99 | pub mod high; |
|---|
| 100 | pub mod low; |
|---|
| 101 | pub mod middle; |
|---|
| 102 | |
|---|
