1 /** 2 * \file wasmtime/func.h 3 * 4 * Wasmtime definitions of how to interact with host and wasm functions. 5 */ 6 7 #ifndef WASMTIME_FUNC_H 8 #define WASMTIME_FUNC_H 9 10 #include <wasm.h> 11 #include <wasmtime/val.h> 12 #include <wasmtime/store.h> 13 #include <wasmtime/extern.h> 14 15 #ifdef __cplusplus 16 extern "C" { 17 #endif 18 19 /** 20 * \typedef wasmtime_caller_t 21 * \brief Alias to #wasmtime_caller 22 * 23 * \brief Structure used to learn about the caller of a host-defined function. 24 * \struct wasmtime_caller 25 * 26 * This structure is an argument to #wasmtime_func_callback_t. The purpose 27 * of this structure is acquire a #wasmtime_context_t pointer to interact with 28 * objects, but it can also be used for inspect the state of the caller (such as 29 * getting memories and functions) with #wasmtime_caller_export_get. 30 * 31 * This object is never owned and does not need to be deleted. 32 */ 33 typedef struct wasmtime_caller wasmtime_caller_t; 34 35 /** 36 * \brief Callback signature for #wasmtime_func_new. 37 * 38 * This is the function signature for host functions that can be made accessible 39 * to WebAssembly. The arguments to this function are: 40 * 41 * \param env user-provided argument passed to #wasmtime_func_new 42 * \param caller a temporary object that can only be used during this function 43 * call. Used to acquire #wasmtime_context_t or caller's state 44 * \param args the arguments provided to this function invocation 45 * \param nargs how many arguments are provided 46 * \param results where to write the results of this function 47 * \param nresults how many results must be produced 48 * 49 * Callbacks are guaranteed to get called with the right types of arguments, but 50 * they must produce the correct number and types of results. Failure to do so 51 * will cause traps to get raised on the wasm side. 52 * 53 * This callback can optionally return a #wasm_trap_t indicating that a trap 54 * should be raised in WebAssembly. It's expected that in this case the caller 55 * relinquishes ownership of the trap and it is passed back to the engine. 56 */ 57 typedef wasm_trap_t* (*wasmtime_func_callback_t)( 58 void *env, 59 wasmtime_caller_t* caller, 60 const wasmtime_val_t *args, 61 size_t nargs, 62 wasmtime_val_t *results, 63 size_t nresults); 64 65 /** 66 * \brief Creates a new host-defined function. 67 * 68 * Inserts a host-defined function into the `store` provided which can be used 69 * to then instantiate a module with or define within a #wasmtime_linker_t. 70 * 71 * \param store the store in which to create the function 72 * \param type the wasm type of the function that's being created 73 * \param callback the host-defined callback to invoke 74 * \param env host-specific data passed to the callback invocation, can be 75 * `NULL` 76 * \param finalizer optional finalizer for `env`, can be `NULL` 77 * \param ret the #wasmtime_func_t return value to be filled in. 78 * 79 * The returned function can only be used with the specified `store`. 80 */ 81 WASM_API_EXTERN void wasmtime_func_new( 82 wasmtime_context_t *store, 83 const wasm_functype_t* type, 84 wasmtime_func_callback_t callback, 85 void *env, 86 void (*finalizer)(void*), 87 wasmtime_func_t *ret 88 ); 89 90 /** 91 * \brief Callback signature for #wasmtime_func_new_unchecked. 92 * 93 * This is the function signature for host functions that can be made accessible 94 * to WebAssembly. The arguments to this function are: 95 * 96 * \param env user-provided argument passed to #wasmtime_func_new_unchecked 97 * \param caller a temporary object that can only be used during this function 98 * call. Used to acquire #wasmtime_context_t or caller's state 99 * \param args_and_results storage space for both the parameters to the 100 * function as well as the results of the function. The size of this 101 * array depends on the function type that the host function is created 102 * with, but it will be the maximum of the number of parameters and 103 * number of results. 104 * 105 * This callback can optionally return a #wasm_trap_t indicating that a trap 106 * should be raised in WebAssembly. It's expected that in this case the caller 107 * relinquishes ownership of the trap and it is passed back to the engine. 108 * 109 * This differs from #wasmtime_func_callback_t in that the payload of 110 * `args_and_results` does not have type information, nor does it have sizing 111 * information. This is especially unsafe because it's only valid within the 112 * particular #wasm_functype_t that the function was created with. The onus is 113 * on the embedder to ensure that `args_and_results` are all read correctly 114 * for parameters and all written for results within the execution of a 115 * function. 116 * 117 * Parameters will be listed starting at index 0 in the `args_and_results` 118 * array. Results are also written starting at index 0, which will overwrite 119 * the arguments. 120 */ 121 typedef wasm_trap_t* (*wasmtime_func_unchecked_callback_t)( 122 void *env, 123 wasmtime_caller_t* caller, 124 wasmtime_val_raw_t *args_and_results); 125 126 /** 127 * \brief Creates a new host function in the same manner of #wasmtime_func_new, 128 * but the function-to-call has no type information available at runtime. 129 * 130 * This function is very similar to #wasmtime_func_new. The difference is that 131 * this version is "more unsafe" in that when the host callback is invoked there 132 * is no type information and no checks that the right types of values are 133 * produced. The onus is on the consumer of this API to ensure that all 134 * invariants are upheld such as: 135 * 136 * * The host callback reads parameters correctly and interprets their types 137 * correctly. 138 * * If a trap doesn't happen then all results are written to the results 139 * pointer. All results must have the correct type. 140 * * Types such as `funcref` cannot cross stores. 141 * * Types such as `externref` have valid reference counts. 142 * 143 * It's generally only recommended to use this if your application can wrap 144 * this in a safe embedding. This should not be frequently used due to the 145 * number of invariants that must be upheld on the wasm<->host boundary. On the 146 * upside, though, this flavor of host function will be faster to call than 147 * those created by #wasmtime_func_new (hence the reason for this function's 148 * existence). 149 */ 150 WASM_API_EXTERN void wasmtime_func_new_unchecked( 151 wasmtime_context_t *store, 152 const wasm_functype_t* type, 153 wasmtime_func_unchecked_callback_t callback, 154 void *env, 155 void (*finalizer)(void*), 156 wasmtime_func_t *ret 157 ); 158 159 /** 160 * \brief Returns the type of the function specified 161 * 162 * The returned #wasm_functype_t is owned by the caller. 163 */ 164 WASM_API_EXTERN wasm_functype_t* wasmtime_func_type( 165 const wasmtime_context_t *store, 166 const wasmtime_func_t *func 167 ); 168 169 /** 170 * \brief Call a WebAssembly function. 171 * 172 * This function is used to invoke a function defined within a store. For 173 * example this might be used after extracting a function from a 174 * #wasmtime_instance_t. 175 * 176 * \param store the store which owns `func` 177 * \param func the function to call 178 * \param args the arguments to the function call 179 * \param nargs the number of arguments provided 180 * \param results where to write the results of the function call 181 * \param nresults the number of results expected 182 * \param trap where to store a trap, if one happens. 183 * 184 * There are three possible return states from this function: 185 * 186 * 1. The returned error is non-null. This means `results` 187 * wasn't written to and `trap` will have `NULL` written to it. This state 188 * means that programmer error happened when calling the function, for 189 * example when the size of the arguments/results was wrong, the types of the 190 * arguments were wrong, or arguments may come from the wrong store. 191 * 2. The trap pointer is filled in. This means the returned error is `NULL` and 192 * `results` was not written to. This state means that the function was 193 * executing but hit a wasm trap while executing. 194 * 3. The error and trap returned are both `NULL` and `results` are written to. 195 * This means that the function call succeeded and the specified results were 196 * produced. 197 * 198 * The `trap` pointer cannot be `NULL`. The `args` and `results` pointers may be 199 * `NULL` if the corresponding length is zero. 200 * 201 * Does not take ownership of #wasmtime_val_t arguments. Gives ownership of 202 * #wasmtime_val_t results. 203 */ 204 WASM_API_EXTERN wasmtime_error_t *wasmtime_func_call( 205 wasmtime_context_t *store, 206 const wasmtime_func_t *func, 207 const wasmtime_val_t *args, 208 size_t nargs, 209 wasmtime_val_t *results, 210 size_t nresults, 211 wasm_trap_t **trap 212 ); 213 214 /** 215 * \brief Call a WebAssembly function in an "unchecked" fashion. 216 * 217 * This function is similar to #wasmtime_func_call except that there is no type 218 * information provided with the arguments (or sizing information). Consequently 219 * this is less safe to call since it's up to the caller to ensure that `args` 220 * has an appropriate size and all the parameters are configured with their 221 * appropriate values/types. Additionally all the results must be interpreted 222 * correctly if this function returns successfully. 223 * 224 * Parameters must be specified starting at index 0 in the `args_and_results` 225 * array. Results are written starting at index 0, which will overwrite 226 * the arguments. 227 * 228 * Callers must ensure that various correctness variants are upheld when this 229 * API is called such as: 230 * 231 * * The `args_and_results` pointer has enough space to hold all the parameters 232 * and all the results (but not at the same time). 233 * * Parameters must all be configured as if they were the correct type. 234 * * Values such as `externref` and `funcref` are valid within the store being 235 * called. 236 * 237 * When in doubt it's much safer to call #wasmtime_func_call. This function is 238 * faster than that function, but the tradeoff is that embeddings must uphold 239 * more invariants rather than relying on Wasmtime to check them for you. 240 */ 241 WASM_API_EXTERN wasm_trap_t *wasmtime_func_call_unchecked( 242 wasmtime_context_t *store, 243 const wasmtime_func_t *func, 244 wasmtime_val_raw_t *args_and_results 245 ); 246 247 /** 248 * \brief Loads a #wasmtime_extern_t from the caller's context 249 * 250 * This function will attempt to look up the export named `name` on the caller 251 * instance provided. If it is found then the #wasmtime_extern_t for that is 252 * returned, otherwise `NULL` is returned. 253 * 254 * Note that this only works for exported memories right now for WASI 255 * compatibility. 256 * 257 * \param caller the caller object to look up the export from 258 * \param name the name that's being looked up 259 * \param name_len the byte length of `name` 260 * \param item where to store the return value 261 * 262 * Returns a nonzero value if the export was found, or 0 if the export wasn't 263 * found. If the export wasn't found then `item` isn't written to. 264 */ 265 WASM_API_EXTERN bool wasmtime_caller_export_get( 266 wasmtime_caller_t *caller, 267 const char *name, 268 size_t name_len, 269 wasmtime_extern_t *item 270 ); 271 272 /** 273 * \brief Returns the store context of the caller object. 274 */ 275 WASM_API_EXTERN wasmtime_context_t* wasmtime_caller_context(wasmtime_caller_t* caller); 276 277 /** 278 * \brief Converts a `raw` nonzero `funcref` value from #wasmtime_val_raw_t 279 * into a #wasmtime_func_t. 280 * 281 * This function can be used to interpret nonzero values of the `funcref` field 282 * of the #wasmtime_val_raw_t structure. It is assumed that `raw` does not have 283 * a value of 0, or otherwise the program will abort. 284 * 285 * Note that this function is unchecked and unsafe. It's only safe to pass 286 * values learned from #wasmtime_val_raw_t with the same corresponding 287 * #wasmtime_context_t that they were produced from. Providing arbitrary values 288 * to `raw` here or cross-context values with `context` is UB. 289 */ 290 WASM_API_EXTERN void wasmtime_func_from_raw( 291 wasmtime_context_t* context, 292 size_t raw, 293 wasmtime_func_t *ret); 294 295 /** 296 * \brief Converts a `func` which belongs to `context` into a `usize` 297 * parameter that is suitable for insertion into a #wasmtime_val_raw_t. 298 */ 299 WASM_API_EXTERN size_t wasmtime_func_to_raw( 300 wasmtime_context_t* context, 301 const wasmtime_func_t *func); 302 303 #ifdef __cplusplus 304 } // extern "C" 305 #endif 306 307 #endif // WASMTIME_FUNC_H 308