1 /** 2 * \file wasmtime/instance.h 3 * 4 * Wasmtime APIs for interacting with wasm instances. 5 */ 6 7 #ifndef WASMTIME_INSTANCE_H 8 #define WASMTIME_INSTANCE_H 9 10 #include <wasm.h> 11 #include <wasmtime/extern.h> 12 #include <wasmtime/module.h> 13 #include <wasmtime/store.h> 14 15 #ifdef __cplusplus 16 extern "C" { 17 #endif 18 19 /// \brief Representation of a instance in Wasmtime. 20 /// 21 /// Instances are represented with a 64-bit identifying integer in Wasmtime. 22 /// They do not have any destructor associated with them. Instances cannot 23 /// interoperate between #wasmtime_store_t instances and if the wrong instance 24 /// is passed to the wrong store then it may trigger an assertion to abort the 25 /// process. 26 typedef struct wasmtime_instance { 27 /// Internal identifier of what store this belongs to, never zero. 28 uint64_t store_id; 29 /// Internal index within the store. 30 size_t index; 31 } wasmtime_instance_t; 32 33 /** 34 * \brief Instantiate a wasm module. 35 * 36 * This function will instantiate a WebAssembly module with the provided 37 * imports, creating a WebAssembly instance. The returned instance can then 38 * afterwards be inspected for exports. 39 * 40 * \param store the store in which to create the instance 41 * \param module the module that's being instantiated 42 * \param imports the imports provided to the module 43 * \param nimports the size of `imports` 44 * \param instance where to store the returned instance 45 * \param trap where to store the returned trap 46 * 47 * This function requires that `imports` is the same size as the imports that 48 * `module` has. Additionally the `imports` array must be 1:1 lined up with the 49 * imports of the `module` specified. This is intended to be relatively low 50 * level, and #wasmtime_linker_instantiate is provided for a more ergonomic 51 * name-based resolution API. 52 * 53 * The states of return values from this function are similar to 54 * #wasmtime_func_call where an error can be returned meaning something like a 55 * link error in this context. A trap can be returned (meaning no error or 56 * instance is returned), or an instance can be returned (meaning no error or 57 * trap is returned). 58 * 59 * Note that this function requires that all `imports` specified must be owned 60 * by the `store` provided as well. 61 * 62 * This function does not take ownership of any of its arguments, but all return 63 * values are owned by the caller. 64 */ 65 WASM_API_EXTERN wasmtime_error_t *wasmtime_instance_new( 66 wasmtime_context_t *store, 67 const wasmtime_module_t *module, 68 const wasmtime_extern_t* imports, 69 size_t nimports, 70 wasmtime_instance_t *instance, 71 wasm_trap_t **trap 72 ); 73 74 /** 75 * \brief Get an export by name from an instance. 76 * 77 * \param store the store that owns `instance` 78 * \param instance the instance to lookup within 79 * \param name the export name to lookup 80 * \param name_len the byte length of `name` 81 * \param item where to store the returned value 82 * 83 * Returns nonzero if the export was found, and `item` is filled in. Otherwise 84 * returns 0. 85 * 86 * Doesn't take ownership of any arguments but does return ownership of the 87 * #wasmtime_extern_t. 88 */ 89 WASM_API_EXTERN bool wasmtime_instance_export_get( 90 wasmtime_context_t *store, 91 const wasmtime_instance_t *instance, 92 const char *name, 93 size_t name_len, 94 wasmtime_extern_t *item 95 ); 96 97 /** 98 * \brief Get an export by index from an instance. 99 * 100 * \param store the store that owns `instance` 101 * \param instance the instance to lookup within 102 * \param index the index to lookup 103 * \param name where to store the name of the export 104 * \param name_len where to store the byte length of the name 105 * \param item where to store the export itself 106 * 107 * Returns nonzero if the export was found, and `name`, `name_len`, and `item` 108 * are filled in. Otherwise returns 0. 109 * 110 * Doesn't take ownership of any arguments but does return ownership of the 111 * #wasmtime_extern_t. The `name` pointer return value is owned by the `store` 112 * and must be immediately used before calling any other APIs on 113 * #wasmtime_context_t. 114 */ 115 WASM_API_EXTERN bool wasmtime_instance_export_nth( 116 wasmtime_context_t *store, 117 const wasmtime_instance_t *instance, 118 size_t index, 119 char **name, 120 size_t *name_len, 121 wasmtime_extern_t *item 122 ); 123 124 /** 125 * \brief A #wasmtime_instance_t, pre-instantiation, that is ready to be instantiated. 126 * 127 * Must be deleted using #wasmtime_instance_pre_delete. 128 * 129 * For more information see the Rust documentation: 130 * https://docs.wasmtime.dev/api/wasmtime/struct.InstancePre.html 131 */ 132 typedef struct wasmtime_instance_pre wasmtime_instance_pre_t; 133 134 /** 135 * \brief Delete a previously created wasmtime_instance_pre_t. 136 */ 137 WASM_API_EXTERN void 138 wasmtime_instance_pre_delete(wasmtime_instance_pre_t *instance_pre); 139 140 /** 141 * \brief Instantiates instance within the given store. 142 * 143 * This will also run the function's startup function, if there is one. 144 * 145 * For more information on instantiation see #wasmtime_instance_new. 146 * 147 * \param instance_pre the pre-initialized instance 148 * \param store the store in which to create the instance 149 * \param instance where to store the returned instance 150 * \param trap_ptr where to store the returned trap 151 * 152 * \return One of three things can happen as a result of this function. First 153 * the module could be successfully instantiated and returned through 154 * `instance`, meaning the return value and `trap` are both set to `NULL`. 155 * Second the start function may trap, meaning the return value and `instance` 156 * are set to `NULL` and `trap` describes the trap that happens. Finally 157 * instantiation may fail for another reason, in which case an error is returned 158 * and `trap` and `instance` are set to `NULL`. 159 * 160 * This function does not take ownership of any of its arguments, and all return 161 * values are owned by the caller. 162 */ 163 WASM_API_EXTERN wasmtime_error_t* wasmtime_instance_pre_instantiate( 164 const wasmtime_instance_pre_t* instance_pre, 165 wasmtime_store_t *store, 166 wasmtime_instance_t* instance, 167 wasm_trap_t **trap_ptr); 168 169 /** 170 * \brief Get the module (as a shallow clone) for a instance_pre. 171 * 172 * The returned module is owned by the caller and the caller **must** 173 * delete it via `wasmtime_module_delete`. 174 */ 175 WASM_API_EXTERN wasmtime_module_t* 176 wasmtime_instance_pre_module(wasmtime_instance_pre_t *instance_pre); 177 178 #ifdef __cplusplus 179 } // extern "C" 180 #endif 181 182 #endif // WASMTIME_INSTANCE_H 183