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 /// Constructs an instance by loading a program from a file with specified
43 /// memory locking behavior.
44 ///
45 /// # Arguments
46 /// - `file_path`: The path to the ExecuTorch program file to load.
47 /// - `load_mode`: The loading mode to use.
48 #[namespace = "executorch_rs"]
49 fn Module_new(
50 file_path: &str,
51 load_mode: ModuleLoadMode,
52 event_tracer: UniquePtr<EventTracer>,
53 ) -> UniquePtr<Module>;
54
55 /// Load the program if needed.
56 ///
57 /// # Arguments
58 /// - `verification`: The type of verification to do before returning success.
59 ///
60 /// # Returns
61 /// An Error to indicate success or failure of the loading process.
62 #[namespace = "executorch_rs"]
63 fn Module_load(self_: Pin<&mut Module>, verification: ProgramVerification) -> Error;
64
65 /// Get a list of method names available in the loaded program.
66 ///
67 /// Loads the program and method if needed.
68 ///
69 /// # Arguments
70 /// - `method_names_out`: A mutable reference to a vector that will be filled with the method names.
71 ///
72 /// # Returns
73 /// A error indicating whether the method names retrieval was successful or not.
74 ///
75 /// # Safety
76 /// The `method_names_out` vector must be valid for the lifetime of the function.
77 /// The `method_names_out` vector can be used only if the function returns `Error::Ok`.
78 #[namespace = "executorch_rs"]
79 unsafe fn Module_method_names(
80 self_: Pin<&mut Module>,
81 method_names_out: &mut Vec<String>,
82 ) -> Error;
83
84 /// Load a specific method from the program and set up memory management if
85 /// needed.
86 ///
87 /// The loaded method is cached to reuse the next time it's executed.
88 ///
89 /// # Arguments
90 /// - `method_name`: The name of the method to load.
91 ///
92 /// # Returns
93 /// An Error to indicate success or failure.
94 #[namespace = "executorch_rs"]
95 unsafe fn Module_load_method(
96 self_: Pin<&mut Module>,
97 method_name: &str,
98 event_tracer: *mut EventTracer,
99 ) -> Error;
100
101 /// Checks if a specific method is loaded.
102 ///
103 /// # Arguments
104 /// - `method_name`: The name of the method to check.
105 ///
106 /// # Returns
107 /// `true` if the method specified by `method_name` is loaded, `false` otherwise.
108 #[namespace = "executorch_rs"]
109 fn Module_is_method_loaded(self_: &Module, method_name: &str) -> bool;
110
111 /// Get a method metadata struct by method name.
112 ///
113 /// Loads the program and method if needed.
114 ///
115 /// # Arguments
116 /// - `method_name`: The name of the method to get the metadata for.
117 /// - `method_meta_out`: A mutable reference to a `MethodMeta` struct that will be filled with the metadata.
118 ///
119 /// # Returns
120 /// A error indicating whether the metadata retrieval was successful or not.
121 ///
122 /// # Safety
123 /// The `method_meta_out` struct must be valid for the lifetime of the function.
124 /// The `method_meta_out` struct can be used only if the function returns `Error::Ok`.
125 #[namespace = "executorch_rs"]
126 unsafe fn Module_method_meta(
127 self_: Pin<&mut Module>,
128 method_name: &str,
129 method_meta_out: *mut MethodMeta,
130 ) -> Error;
131
132 /// Execute a specific method with the given input values and retrieve the
133 /// output values. Loads the program and method before executing if needed.
134 ///
135 /// # Arguments
136 /// - `method_name`: The name of the method to execute.
137 /// - `inputs`: A vector of input values to be passed to the method.
138 /// - `outputs`: A mutable reference to a vector that will be filled with the output values from the method.
139 ///
140 /// # Returns
141 /// A error indicating whether the execution was successful or not.
142 ///
143 /// # Safety
144 /// The `outputs` vector must be valid for the lifetime of the function.
145 /// The `outputs` vector can be used only if the function returns `Error::Ok`.
146 #[namespace = "executorch_rs"]
147 unsafe fn Module_execute(
148 self_: Pin<&mut Module>,
149 method_name: &str,
150 inputs: ArrayRefEValue,
151 outputs: *mut VecEValue,
152 ) -> Error;
153 }
154}
155
156unsafe impl ExternType for crate::ModuleLoadMode {
157 type Id = type_id!("ModuleLoadMode");
158 type Kind = cxx::kind::Trivial;
159}