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