Debian Codegraph @

.cargo/vendor/wit-bindgen/src/rt/async_support/cabi.rs

raw
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 }