| 1 |
//! Definition of the "C ABI" of how imported functions interact with exported |
| 2 |
//! tasks. |
| 3 |
//! |
| 4 |
//! Ok this crate is written in Rust, why in the world does this exist? This |
| 5 |
//! comment is intended to explain this rationale but the tl;dr; is we want |
| 6 |
//! this to work: |
| 7 |
//! |
| 8 |
//! * Within a single component ... |
| 9 |
//! * One rust crate uses `wit-bindgen 0.A.0` to generate an exported function. |
| 10 |
//! * One rust crate uses `wit-bindgen 0.B.0` to bind an imported function. |
| 11 |
//! * The two crates are connected in the application with |
| 12 |
//! `std::future::Future`. |
| 13 |
//! |
| 14 |
//! Without this module this situation won't work because 0.A.0 has no |
| 15 |
//! knowledge of 0.B.0 meaning that 0.B.0 has no means of inserting a `waitable` |
| 16 |
//! into the `waitable-set` managed by 0.A.0's export. |
| 17 |
//! |
| 18 |
//! To solve this problem the long-term intention is that something will live |
| 19 |
//! in `wasi-libc` itself, but in the meantime it's living "somewhere" within |
| 20 |
//! `wit-bindgen 0.*.0`. Specifically all `wit-bindgen` versions will |
| 21 |
//! reference, via C linkage, a single function which is used to manipulate a |
| 22 |
//! single pointer in linear memory. This pointer is a `wasip3_task` structure |
| 23 |
//! which has all the various fields to use it. |
| 24 |
//! |
| 25 |
//! The `wasip3_task_set` symbol is itself defined in C inside of the |
| 26 |
//! `src/wit_bindgen_cabi.c` file at this time, specifically because it's |
| 27 |
//! annotated with `__weak__` meaning that any definition of it suffices. This |
| 28 |
//! isn't possible to define in stable Rust (specifically `__weak__`). |
| 29 |
//! |
| 30 |
//! Once `wasip3_task_set` is defined everything then operates via indirection, |
| 31 |
//! aka based off the returned pointer. The intention is that exported functions |
| 32 |
//! will set this (it's sort of like an executor) and then imported functions |
| 33 |
//! will all use this as the source of registering waitables. In the end that |
| 34 |
//! means that it's possible to share types with `std::future::Future` that |
| 35 |
//! are backed at the ABI level with this "channel". |
| 36 |
//! |
| 37 |
//! In the future it's hoped that this can move into `wasi-libc` itself, or if |
| 38 |
//! `wasi-libc` provides something else that would be prioritized over this. |
| 39 |
//! For now this is basically an affordance that we're going to be frequently |
| 40 |
//! releaseing new major versions of `wit-bindgen` and we don't want to force |
| 41 |
//! applications to all be using the exact same version of the bindings |
| 42 |
//! generator and async bindings. |
| 43 |
//! |
| 44 |
//! Additionally for now this file is serving as documentation of this |
| 45 |
//! interface. |
| 46 |
|
| 47 |
use core::ffi::c_void; |
| 48 |
|
| 49 |
#[cfg(target_family = "wasm")] |
| 50 |
extern "C" { |
| 51 |
/// Sets the global task pointer to `ptr` provided. Returns the previous |
| 52 |
/// value. |
| 53 |
/// |
| 54 |
/// This function acts as a dual getter and a setter. To get the |
| 55 |
/// current task pointer a dummy `ptr` can be provided (e.g. NULL) and then |
| 56 |
/// it's passed back when you're done working with it. When setting the |
| 57 |
/// current task pointer it's recommended to call this and then call it |
| 58 |
/// again with the previous value when the tasks's work is done. |
| 59 |
/// |
| 60 |
/// For executors they need to ensure that the `ptr` passed in lives for |
| 61 |
/// the entire lifetime of the component model task. |
| 62 |
pub fn wasip3_task_set(ptr: *mut wasip3_task) -> *mut wasip3_task; |
| 63 |
} |
| 64 |
|
| 65 |
#[cfg(not(target_family = "wasm"))] |
| 66 |
pub unsafe extern "C" fn wasip3_task_set(ptr: *mut wasip3_task) -> *mut wasip3_task { |
| 67 |
let _ = ptr; |
| 68 |
unreachable!(); |
| 69 |
} |
| 70 |
|
| 71 |
/// The first version of `wasip3_task` which implies the existence of the |
| 72 |
/// fields `ptr`, `waitable_register`, and `waitable_unregister`. |
| 73 |
pub const WASIP3_TASK_V1: u32 = 1; |
| 74 |
|
| 75 |
/// Indirect "vtable" used to connect imported functions and exported tasks. |
| 76 |
/// Executors (e.g. exported functions) define and manage this while imports |
| 77 |
/// use it. |
| 78 |
#[repr(C)] |
| 79 |
pub struct wasip3_task { |
| 80 |
/// Currently `WASIP3_TASK_V1`. Indicates what fields are present next |
| 81 |
/// depending on the version here. |
| 82 |
pub version: u32, |
| 83 |
|
| 84 |
/// Private pointer owned by the `wasip3_task` itself, passed to callbacks |
| 85 |
/// below as the first argument. |
| 86 |
pub ptr: *mut c_void, |
| 87 |
|
| 88 |
/// Register a new `waitable` for this exported task. |
| 89 |
/// |
| 90 |
/// This exported task will add `waitable` to its `waitable-set`. When it |
| 91 |
/// becomes ready then `callback` will be invoked with the ready code as |
| 92 |
/// well as the `callback_ptr` provided. |
| 93 |
/// |
| 94 |
/// If `waitable` was previously registered with this task then the |
| 95 |
/// previous `callback_ptr` is returned. Otherwise `NULL` is returned. |
| 96 |
/// |
| 97 |
/// It's the caller's responsibility to ensure that `callback_ptr` is valid |
| 98 |
/// until `callback` is invoked, `waitable_unregister` is invoked, or |
| 99 |
/// `waitable_register` is called again to overwrite the value. |
| 100 |
pub waitable_register: unsafe extern "C" fn( |
| 101 |
ptr: *mut c_void, |
| 102 |
waitable: u32, |
| 103 |
callback: unsafe extern "C" fn(callback_ptr: *mut c_void, code: u32), |
| 104 |
callback_ptr: *mut c_void, |
| 105 |
) -> *mut c_void, |
| 106 |
|
| 107 |
/// Removes the `waitable` from this task's `waitable-set`. |
| 108 |
/// |
| 109 |
/// Returns the `callback_ptr` passed to `waitable_register` if present, or |
| 110 |
/// `NULL` if it's not present. |
| 111 |
pub waitable_unregister: unsafe extern "C" fn(ptr: *mut c_void, waitable: u32) -> *mut c_void, |
| 112 |
} |