executorch_sys/cxx_bridge/module.rs
1// Clippy doesnt detect the 'Safety' comments in the cxx bridge.
2#![allow(clippy::missing_safety_doc)]
3
4use cxx::{type_id, ExternType};
5
6#[cxx::bridge]
7pub(crate) mod ffi {
8
9 unsafe extern "C++" {
10 include!("executorch-sys/cpp/executorch_rs/cxx_bridge.hpp");
11
12 /// Cpp executorch error type.
13 type Error = crate::Error;
14
15 /// Types of validation that a `Program` can do before parsing the data.
16 type ProgramVerification = crate::ProgramVerification;
17
18 /// Describes a method in an ExecuTorch program.
19 ///
20 /// The program used to create a MethodMeta object must outlive the MethodMeta.
21 /// It is separate from Method so that this information can be accessed without
22 /// paying the initialization cost of loading the full Method.
23 type MethodMeta = crate::MethodMeta;
24
25 /// A facade class for loading programs and executing methods within them.
26 #[namespace = "executorch::extension"]
27 type Module;
28
29 /// Enum to define loading behavior.
30 type ModuleLoadMode = crate::ModuleLoadMode;
31
32 /// A specification of `ArrayRef<EValue>`.
33 type ArrayRefEValue = crate::ArrayRefEValue;
34
35 /// A vector of `EValue`.
36 type VecEValue = crate::VecEValue;
37
38 /// EventTracer is a class that users can inherit and implement to log/serialize/stream etc.
39 #[namespace = "executorch::runtime"]
40 type EventTracer;
41
42 /// An allocator used to allocate objects for the runtime.
43 type MemoryAllocator = crate::MemoryAllocator;
44
45 /// Redefinition of the [`HierarchicalAllocator`](crate::HierarchicalAllocator).
46 type HierarchicalAllocator = crate::HierarchicalAllocator;
47
48 /// Constructs an instance by loading a program from a file with specified
49 /// memory locking behavior.
50 ///
51 /// # Arguments
52 ///
53 /// - `file_path`: The path to the ExecuTorch program file to load.
54 /// - `data_files`: The path to one or more .ptd file/s.
55 /// - `load_mode`: The loading mode to use.
56 /// - `event_tracer`: An EventTracer used for tracking and logging events, or null if not needed.
57 #[namespace = "executorch_rs"]
58 fn Module_new(
59 file_path: &CxxString,
60 data_files: &[&str],
61 load_mode: ModuleLoadMode,
62 event_tracer: UniquePtr<EventTracer>,
63 memory_allocator: UniquePtr<MemoryAllocator>,
64 temp_allocator: UniquePtr<MemoryAllocator>,
65 ) -> UniquePtr<Module>;
66
67 /// Load the program if needed.
68 ///
69 /// # Arguments
70 ///
71 /// - `verification`: The type of verification to do before returning success.
72 ///
73 /// # Returns
74 ///
75 /// An Error to indicate success or failure of the loading process.
76 #[namespace = "executorch_rs"]
77 fn Module_load(self_: Pin<&mut Module>, verification: ProgramVerification) -> Error;
78
79 /// Checks if the program is loaded.
80 #[namespace = "executorch_rs"]
81 fn Module_is_loaded(self_: &Module) -> bool;
82
83 /// Get the number of methods available in the loaded program.
84 ///
85 /// # Safety
86 ///
87 /// The `method_num_out` is valid only if the function returns `Error::Ok`.
88 #[namespace = "executorch_rs"]
89 unsafe fn Module_num_methods(self_: Pin<&mut Module>, method_num_out: *mut usize) -> Error;
90
91 /// Get a list of method names available in the loaded program.
92 ///
93 /// Loads the program and method if needed.
94 ///
95 /// # Arguments
96 ///
97 /// - `method_names_out`: A pointer to a (non initialized) vector that will be created and filled with
98 /// the method names.
99 ///
100 /// # Returns
101 ///
102 /// A error indicating whether the method names retrieval was successful or not.
103 ///
104 /// # Safety
105 ///
106 /// The `method_names_out` vector can be used only if the function returns `Error::Ok`.
107 #[namespace = "executorch_rs"]
108 unsafe fn Module_method_names(
109 self_: Pin<&mut Module>,
110 method_names_out: *mut Vec<String>,
111 ) -> Error;
112
113 /// Load a specific method from the program and set up memory management if
114 /// needed.
115 ///
116 /// The loaded method is cached to reuse the next time it's executed.
117 ///
118 /// # Arguments
119 ///
120 /// - `method_name`: The name of the method to load.
121 ///
122 /// # Returns
123 ///
124 /// An Error to indicate success or failure.
125 #[namespace = "executorch_rs"]
126 unsafe fn Module_load_method(
127 self_: Pin<&mut Module>,
128 method_name: &CxxString,
129 planned_memory: *mut HierarchicalAllocator,
130 event_tracer: *mut EventTracer,
131 ) -> Error;
132
133 /// Unload a specific method from the program.
134 ///
135 /// # Arguments
136 /// - `method_name`: The name of the method to unload.
137 ///
138 /// # Returns
139 ///
140 /// True if the method is unloaded, false if no-op.
141 #[namespace = "executorch_rs"]
142 unsafe fn Module_unload_method(self_: Pin<&mut Module>, method_name: &CxxString) -> bool;
143
144 /// Checks if a specific method is loaded.
145 ///
146 /// # Arguments
147 ///
148 /// - `method_name`: The name of the method to check.
149 ///
150 /// # Returns
151 ///
152 /// `true` if the method specified by `method_name` is loaded, `false` otherwise.
153 #[namespace = "executorch_rs"]
154 fn Module_is_method_loaded(self_: &Module, method_name: &CxxString) -> bool;
155
156 /// Get a method metadata struct by method name.
157 ///
158 /// Loads the program if needed.
159 ///
160 /// # Arguments
161 ///
162 /// - `method_name`: The name of the method to get the metadata for.
163 /// - `method_meta_out`: A mutable reference to a `MethodMeta` struct that will be filled with the metadata.
164 ///
165 /// # Returns
166 ///
167 /// A error indicating whether the metadata retrieval was successful or not.
168 ///
169 /// # Safety
170 ///
171 /// The `method_meta_out` struct must be valid for the lifetime of the function.
172 /// The `method_meta_out` struct can be used only if the function returns `Error::Ok`.
173 #[namespace = "executorch_rs"]
174 unsafe fn Module_method_meta(
175 self_: Pin<&mut Module>,
176 method_name: &CxxString,
177 method_meta_out: *mut MethodMeta,
178 ) -> Error;
179
180 /// Execute a specific method with the given input values and retrieve the
181 /// output values. Loads the program and method before executing if needed.
182 ///
183 /// # Arguments
184 ///
185 /// - `method_name`: The name of the method to execute.
186 /// - `inputs`: A vector of input values to be passed to the method.
187 /// - `outputs`: A mutable reference to a vector that will be filled with the output values from the method.
188 ///
189 /// # Returns
190 ///
191 /// A error indicating whether the execution was successful or not.
192 ///
193 /// # Safety
194 ///
195 /// The `outputs` vector must be valid for the lifetime of the function.
196 /// The `outputs` vector can be used only if the function returns `Error::Ok`.
197 #[namespace = "executorch_rs"]
198 unsafe fn Module_execute(
199 self_: Pin<&mut Module>,
200 method_name: &CxxString,
201 inputs: ArrayRefEValue,
202 outputs: *mut VecEValue,
203 ) -> Error;
204 }
205}
206
207unsafe impl ExternType for crate::HierarchicalAllocator {
208 type Id = type_id!("HierarchicalAllocator");
209 type Kind = cxx::kind::Trivial;
210}
211
212unsafe impl ExternType for crate::ModuleLoadMode {
213 type Id = type_id!("ModuleLoadMode");
214 type Kind = cxx::kind::Trivial;
215}