1use std::any::Any;
2
3use super::types::Type;
4
5/// Provides a builder-style API for constructing CIFs and closures.
6///
7/// To use a builder, first construct it using [`Builder::new`]. The
8/// default calling convention is
9/// [`ffi_abi_FFI_DEFAULT_ABI`](crate::low::ffi_abi_FFI_DEFAULT_ABI),
10/// and the default function type is `extern "C" fn()` (or in C,
11/// `void(*)()`). Add argument types to the function type with the
12/// [`Builder::arg`] and [`args`](Builder::args) methods. Set the result type
13/// with [`Builder::res`]. Change the calling convention, if necessary,
14/// with [`Builder::abi`].
15///
16/// Once the builder is configured, construct a `Cif` with
17/// [`Builder::into_cif`] or a closure with [`Builder::into_closure`],
18/// [`into_closure_mut`](Builder::into_closure_mut), or
19/// [`into_closure_once`](Builder::into_closure_once).
20///
21/// # Examples
22///
23/// ```
24/// use std::mem;
25/// use std::os::raw::c_void;
26///
27/// use libffi::middle::*;
28/// use libffi::low;
29///
30/// unsafe extern "C" fn lambda_callback<F: Fn(u64, u64) -> u64>(
31/// _cif: &low::ffi_cif,
32/// result: &mut u64,
33/// args: *const *const c_void,
34/// userdata: &F)
35/// {
36/// let args: *const &u64 = mem::transmute(args);
37/// let arg1 = **args.offset(0);
38/// let arg2 = **args.offset(1);
39///
40/// *result = userdata(arg1, arg2);
41/// }
42///
43/// let lambda = |x: u64, y: u64| x + y;
44///
45/// let closure = Builder::new()
46/// .arg(Type::u64())
47/// .arg(Type::u64())
48/// .res(Type::u64())
49/// .into_closure(lambda_callback, &lambda);
50///
51/// unsafe {
52/// let fun: &unsafe extern "C" fn(u64, u64) -> u64
53/// = mem::transmute(closure.code_ptr());
54///
55/// assert_eq!(11, fun(5, 6));
56/// assert_eq!(12, fun(5, 7));
57/// }
58/// ```
59#[derive(Clone, Debug)]
60pub struct Builder {
61 args: Vec<Type>,
62 res: Type,
63 abi: super::FfiAbi,
64}
65
66impl Default for Builder {
67 fn default() -> Self {
68 Builder::new()
69 }
70}
71
72impl Builder {
73 /// Constructs a `Builder`.
74 pub fn new() -> Self {
75 Builder {
76 args: vec![],
77 res: Type::void(),
78 abi: super::ffi_abi_FFI_DEFAULT_ABI,
79 }
80 }
81
82 /// Adds a type to the argument type list.
83 pub fn arg(mut self, type_: Type) -> Self {
84 self.args.push(type_);
85 self
86 }
87
88 /// Adds several types to the argument type list.
89 pub fn args<I>(mut self, types: I) -> Self
90 where
91 I: IntoIterator<Item = Type>,
92 {
93 self.args.extend(types.into_iter());
94 self
95 }
96
97 /// Sets the result type.
98 pub fn res(mut self, type_: Type) -> Self {
99 self.res = type_;
100 self
101 }
102
103 /// Sets the calling convention.
104 pub fn abi(mut self, abi: super::FfiAbi) -> Self {
105 self.abi = abi;
106 self
107 }
108
109 /// Builds a CIF.
110 pub fn into_cif(self) -> super::Cif {
111 let mut result = super::Cif::new(self.args, self.res);
112 result.set_abi(self.abi);
113 result
114 }
115
116 /// Builds an immutable closure.
117 ///
118 /// # Arguments
119 ///
120 /// - `callback` — the function to call when the closure is invoked
121 /// - `userdata` — the pointer to pass to `callback` along with the
122 /// arguments when the closure is called
123 ///
124 /// # Result
125 ///
126 /// The new closure.
127 pub fn into_closure<U, R>(
128 self,
129 callback: super::Callback<U, R>,
130 userdata: &U,
131 ) -> super::Closure {
132 super::Closure::new(self.into_cif(), callback, userdata)
133 }
134
135 /// Builds a mutable closure.
136 ///
137 /// # Arguments
138 ///
139 /// - `callback` — the function to call when the closure is invoked
140 /// - `userdata` — the pointer to pass to `callback` along with the
141 /// arguments when the closure is called
142 ///
143 /// # Result
144 ///
145 /// The new closure.
146 pub fn into_closure_mut<U, R>(
147 self,
148 callback: super::CallbackMut<U, R>,
149 userdata: &mut U,
150 ) -> super::Closure {
151 super::Closure::new_mut(self.into_cif(), callback, userdata)
152 }
153
154 /// Builds a one-shot closure.
155 ///
156 /// # Arguments
157 ///
158 /// - `callback` — the function to call when the closure is invoked
159 /// - `userdata` — the object to pass to `callback` along with the
160 /// arguments when the closure is called
161 ///
162 /// # Result
163 ///
164 /// The new closure.
165 pub fn into_closure_once<U: Any, R>(
166 self,
167 callback: super::CallbackOnce<U, R>,
168 userdata: U,
169 ) -> super::ClosureOnce {
170 super::ClosureOnce::new(self.into_cif(), callback, userdata)
171 }
172}
173