| 1 | // SPDX-License-Identifier: MIT |
| 2 | |
| 3 | //! Utility functions to deal with callbacks from C to Rust. |
| 4 | |
| 5 | use std::{mem, ptr::NonNull}; |
| 6 | |
| 7 | /// Trait for functions (types implementing [`Fn`]) that can be used as |
| 8 | /// callbacks. These include both zero-capture closures and function pointers. |
| 9 | /// |
| 10 | /// In Rust, calling a function through the `Fn` trait normally requires a |
| 11 | /// `self` parameter, even though for zero-sized functions (including function |
| 12 | /// pointers) the type itself contains all necessary information to call the |
| 13 | /// function. This trait provides a `call` function that doesn't require `self`, |
| 14 | /// allowing zero-sized functions to be called using only their type. |
| 15 | /// |
| 16 | /// This enables zero-sized functions to be passed entirely through generic |
| 17 | /// parameters and resolved at compile-time. A typical use is a function |
| 18 | /// receiving an unused parameter of generic type `F` and calling it via |
| 19 | /// `F::call` or passing it to another function via `func::<F>`. |
| 20 | /// |
| 21 | /// QEMU uses this trick to create wrappers to C callbacks. The wrappers |
| 22 | /// are needed to convert an opaque `*mut c_void` into a Rust reference, |
| 23 | /// but they only have a single opaque that they can use. The `FnCall` |
| 24 | /// trait makes it possible to use that opaque for `self` or any other |
| 25 | /// reference: |
| 26 | /// |
| 27 | /// ```ignore |
| 28 | /// // The compiler creates a new `rust_bh_cb` wrapper for each function |
| 29 | /// // passed to `qemu_bh_schedule_oneshot` below. |
| 30 | /// unsafe extern "C" fn rust_bh_cb<T, F: for<'a> FnCall<(&'a T,)>>( |
| 31 | /// opaque: *mut c_void, |
| 32 | /// ) { |
| 33 | /// // SAFETY: the opaque was passed as a reference to `T`. |
| 34 | /// F::call((unsafe { &*(opaque.cast::<T>()) }, )) |
| 35 | /// } |
| 36 | /// |
| 37 | /// // The `_f` parameter is unused but it helps the compiler build the appropriate `F`. |
| 38 | /// // Using a reference allows usage in const context. |
| 39 | /// fn qemu_bh_schedule_oneshot<T, F: for<'a> FnCall<(&'a T,)>>(_f: &F, opaque: &T) { |
| 40 | /// let cb: unsafe extern "C" fn(*mut c_void) = rust_bh_cb::<T, F>; |
| 41 | /// unsafe { |
| 42 | /// bindings::qemu_bh_schedule_oneshot(cb, opaque as *const T as *const c_void as *mut c_void) |
| 43 | /// } |
| 44 | /// } |
| 45 | /// ``` |
| 46 | /// |
| 47 | /// Each wrapper is a separate instance of `rust_bh_cb` and is therefore |
| 48 | /// compiled to a separate function ("monomorphization"). If you wanted |
| 49 | /// to pass `self` as the opaque value, the generic parameters would be |
| 50 | /// `rust_bh_cb::<Self, F>`. |
| 51 | /// |
| 52 | /// `Args` is a tuple type whose types are the arguments of the function, |
| 53 | /// while `R` is the returned type. |
| 54 | /// |
| 55 | /// # Examples |
| 56 | /// |
| 57 | /// ``` |
| 58 | /// # use common::callbacks::FnCall; |
| 59 | /// fn call_it<F: for<'a> FnCall<(&'a str,), String>>(_f: &F, s: &str) -> String { |
| 60 | /// F::call((s,)) |
| 61 | /// } |
| 62 | /// |
| 63 | /// let s: String = call_it(&str::to_owned, "hello world"); |
| 64 | /// assert_eq!(s, "hello world"); |
| 65 | /// ``` |
| 66 | /// |
| 67 | /// Note that the compiler will produce a different version of `call_it` for |
| 68 | /// each function that is passed to it. Therefore the argument is not really |
| 69 | /// used, except to decide what is `F` and what `F::call` does. |
| 70 | /// |
| 71 | /// Attempting to pass a non-zero-sized closure causes a compile-time failure: |
| 72 | /// |
| 73 | /// ```compile_fail |
| 74 | /// # use common::callbacks::FnCall; |
| 75 | /// # fn call_it<'a, F: FnCall<(&'a str,), String>>(_f: &F, s: &'a str) -> String { |
| 76 | /// # F::call((s,)) |
| 77 | /// # } |
| 78 | /// let x: &'static str = "goodbye world"; |
| 79 | /// call_it(&move |_| String::from(x), "hello workd"); |
| 80 | /// ``` |
| 81 | /// |
| 82 | /// `()` can be used to indicate "no function": |
| 83 | /// |
| 84 | /// ``` |
| 85 | /// # use common::callbacks::FnCall; |
| 86 | /// fn optional<F: for<'a> FnCall<(&'a str,), String>>(_f: &F, s: &str) -> Option<String> { |
| 87 | /// if F::IS_SOME { |
| 88 | /// Some(F::call((s,))) |
| 89 | /// } else { |
| 90 | /// None |
| 91 | /// } |
| 92 | /// } |
| 93 | /// |
| 94 | /// assert!(optional(&(), "hello world").is_none()); |
| 95 | /// ``` |
| 96 | /// |
| 97 | /// Invoking `F::call` will then be a run-time error. |
| 98 | /// |
| 99 | /// ```should_panic |
| 100 | /// # use common::callbacks::FnCall; |
| 101 | /// # fn call_it<F: for<'a> FnCall<(&'a str,), String>>(_f: &F, s: &str) -> String { |
| 102 | /// # F::call((s,)) |
| 103 | /// # } |
| 104 | /// let s: String = call_it(&(), "hello world"); // panics |
| 105 | /// ``` |
| 106 | /// |
| 107 | /// # Safety |
| 108 | /// |
| 109 | /// Because `Self` is a zero-sized type, all instances of the type are |
| 110 | /// equivalent. However, in addition to this, `Self` must have no invariants |
| 111 | /// that could be violated by creating a reference to it. |
| 112 | /// |
| 113 | /// This is always true for zero-capture closures and function pointers, as long |
| 114 | /// as the code is able to name the function in the first place. |
| 115 | pub unsafe trait FnCall<Args, R = ()>: 'static + Sync + Sized { |
| 116 | /// `true` if `Self` is an actual function type and not `()`. |
| 117 | /// |
| 118 | /// # Examples |
| 119 | /// |
| 120 | /// You can use `IS_SOME` to catch this at compile time: |
| 121 | /// |
| 122 | /// ```compile_fail |
| 123 | /// # use common::callbacks::FnCall; |
| 124 | /// fn call_it<F: for<'a> FnCall<(&'a str,), String>>(_f: &F, s: &str) -> String { |
| 125 | /// const { assert!(F::IS_SOME) } |
| 126 | /// F::call((s,)) |
| 127 | /// } |
| 128 | /// |
| 129 | /// let s: String = call_it((), "hello world"); // does not compile |
| 130 | /// ``` |
| 131 | const IS_SOME: bool; |
| 132 | |
| 133 | /// `false` if `Self` is an actual function type, `true` if it is `()`. |
| 134 | fn is_none() -> bool { |
| 135 | !Self::IS_SOME |
| 136 | } |
| 137 | |
| 138 | /// `true` if `Self` is an actual function type, `false` if it is `()`. |
| 139 | fn is_some() -> bool { |
| 140 | Self::IS_SOME |
| 141 | } |
| 142 | |
| 143 | /// Call the function with the arguments in args. |
| 144 | fn call(a: Args) -> R; |
| 145 | } |
| 146 | |
| 147 | /// `()` acts as a "null" callback. Using `()` and `function` is nicer |
| 148 | /// than `None` and `Some(function)`, because the compiler is unable to |
| 149 | /// infer the type of just `None`. Therefore, the trait itself acts as the |
| 150 | /// option type, with functions [`FnCall::is_some`] and [`FnCall::is_none`]. |
| 151 | unsafe impl<Args, R> FnCall<Args, R> for () { |
| 152 | const IS_SOME: bool = false; |
| 153 | |
| 154 | /// Call the function with the arguments in args. |
| 155 | fn call(_a: Args) -> R { |
| 156 | panic!("callback not specified") |
| 157 | } |
| 158 | } |
| 159 | |
| 160 | macro_rules! impl_call { |
| 161 | ($($args:ident,)* ) => ( |
| 162 | // SAFETY: because each function is treated as a separate type, |
| 163 | // accessing `FnCall` is only possible in code that would be |
| 164 | // allowed to call the function. |
| 165 | unsafe impl<F, $($args,)* R> FnCall<($($args,)*), R> for F |
| 166 | where |
| 167 | F: 'static + Sync + Sized + Fn($($args, )*) -> R, |
| 168 | { |
| 169 | const IS_SOME: bool = true; |
| 170 | |
| 171 | #[inline(always)] |
| 172 | fn call(a: ($($args,)*)) -> R { |
| 173 | const { assert!(mem::size_of::<Self>() == 0) }; |
| 174 | |
| 175 | // SAFETY: the safety of this method is the condition for implementing |
| 176 | // `FnCall`. As to the `NonNull` idiom to create a zero-sized type, |
| 177 | // see https://github.com/rust-lang/libs-team/issues/292. |
| 178 | let f: &'static F = unsafe { &*NonNull::<Self>::dangling().as_ptr() }; |
| 179 | let ($($args,)*) = a; |
| 180 | f($($args,)*) |
| 181 | } |
| 182 | } |
| 183 | ) |
| 184 | } |
| 185 | |
| 186 | impl_call!(_1, _2, _3, _4, _5,); |
| 187 | impl_call!(_1, _2, _3, _4,); |
| 188 | impl_call!(_1, _2, _3,); |
| 189 | impl_call!(_1, _2,); |
| 190 | impl_call!(_1,); |
| 191 | impl_call!(); |
| 192 | |
| 193 | #[cfg(test)] |
| 194 | mod tests { |
| 195 | use super::*; |
| 196 | |
| 197 | // The `_f` parameter is unused but it helps the compiler infer `F`. |
| 198 | fn do_test_call<'a, F: FnCall<(&'a str,), String>>(_f: &F) -> String { |
| 199 | F::call(("hello world",)) |
| 200 | } |
| 201 | |
| 202 | #[test] |
| 203 | fn test_call() { |
| 204 | assert_eq!(do_test_call(&str::to_owned), "hello world") |
| 205 | } |
| 206 | |
| 207 | // The `_f` parameter is unused but it helps the compiler infer `F`. |
| 208 | fn do_test_is_some<'a, F: FnCall<(&'a str,), String>>(_f: &F) { |
| 209 | assert!(F::is_some()); |
| 210 | } |
| 211 | |
| 212 | #[test] |
| 213 | fn test_is_some() { |
| 214 | do_test_is_some(&str::to_owned); |
| 215 | } |
| 216 | } |