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 /** 20 * \brief An opaque object representing the type of an instance. 21 */ 22 typedef struct wasmtime_instancetype wasmtime_instancetype_t; 23 24 /// \brief Deletes an instance type 25 WASM_API_EXTERN void wasmtime_instancetype_delete(wasmtime_instancetype_t *ty); 26 27 /** 28 * \brief Returns the list of exports that this instance type provides. 29 * 30 * This function does not take ownership of the provided instance type but 31 * ownership of `out` is passed to the caller. Note that `out` is treated as 32 * uninitialized when passed to this function. 33 */ 34 WASM_API_EXTERN void wasmtime_instancetype_exports(const wasmtime_instancetype_t*, wasm_exporttype_vec_t* out); 35 36 /** 37 * \brief Converts a #wasmtime_instancetype_t to a #wasm_externtype_t 38 * 39 * The returned value is owned by the #wasmtime_instancetype_t argument and should not 40 * be deleted. 41 */ 42 WASM_API_EXTERN wasm_externtype_t* wasmtime_instancetype_as_externtype(wasmtime_instancetype_t*); 43 44 /** 45 * \brief Attempts to convert a #wasm_externtype_t to a #wasmtime_instancetype_t 46 * 47 * The returned value is owned by the #wasmtime_instancetype_t argument and should not 48 * be deleted. Returns `NULL` if the provided argument is not a 49 * #wasmtime_instancetype_t. 50 */ 51 WASM_API_EXTERN wasmtime_instancetype_t* wasmtime_externtype_as_instancetype(wasm_externtype_t*); 52 53 /** 54 * \brief Instantiate a wasm module. 55 * 56 * This function will instantiate a WebAssembly module with the provided 57 * imports, creating a WebAssembly instance. The returned instance can then 58 * afterwards be inspected for exports. 59 * 60 * \param store the store in which to create the instance 61 * \param module the module that's being instantiated 62 * \param imports the imports provided to the module 63 * \param nimports the size of `imports` 64 * \param instance where to store the returned instance 65 * \param trap where to store the returned trap 66 * 67 * This function requires that `imports` is the same size as the imports that 68 * `module` has. Additionally the `imports` array must be 1:1 lined up with the 69 * imports of the `module` specified. This is intended to be relatively low 70 * level, and #wasmtime_linker_instantiate is provided for a more ergonomic 71 * name-based resolution API. 72 * 73 * The states of return values from this function are similar to 74 * #wasmtime_func_call where an error can be returned meaning something like a 75 * link error in this context. A trap can be returned (meaning no error or 76 * instance is returned), or an instance can be returned (meaning no error or 77 * trap is returned). 78 * 79 * Note that this function requires that all `imports` specified must be owned 80 * by the `store` provided as well. 81 * 82 * This function does not take ownership of any of its arguments, but all return 83 * values are owned by the caller. 84 */ 85 WASM_API_EXTERN wasmtime_error_t *wasmtime_instance_new( 86 wasmtime_context_t *store, 87 const wasmtime_module_t *module, 88 const wasmtime_extern_t* imports, 89 size_t nimports, 90 wasmtime_instance_t *instance, 91 wasm_trap_t **trap 92 ); 93 94 /** 95 * \brief Returns the type of the specified instance. 96 * 97 * The returned type is owned by the caller. 98 */ 99 WASM_API_EXTERN wasmtime_instancetype_t *wasmtime_instance_type( 100 const wasmtime_context_t *store, 101 const wasmtime_instance_t *instance 102 ); 103 104 /** 105 * \brief Get an export by name from an instance. 106 * 107 * \param store the store that owns `instance` 108 * \param instance the instance to lookup within 109 * \param name the export name to lookup 110 * \param name_len the byte length of `name` 111 * \param item where to store the returned value 112 * 113 * Returns nonzero if the export was found, and `item` is filled in. Otherwise 114 * returns 0. 115 * 116 * Doesn't take ownership of any arguments but does return ownership of the 117 * #wasmtime_extern_t. 118 */ 119 WASM_API_EXTERN bool wasmtime_instance_export_get( 120 wasmtime_context_t *store, 121 const wasmtime_instance_t *instance, 122 const char *name, 123 size_t name_len, 124 wasmtime_extern_t *item 125 ); 126 127 /** 128 * \brief Get an export by index from an instance. 129 * 130 * \param store the store that owns `instance` 131 * \param instance the instance to lookup within 132 * \param index the index to lookup 133 * \param name where to store the name of the export 134 * \param name_len where to store the byte length of the name 135 * \param item where to store the export itself 136 * 137 * Returns nonzero if the export was found, and `name`, `name_len`, and `item` 138 * are filled in. Otherwise returns 0. 139 * 140 * Doesn't take ownership of any arguments but does return ownership of the 141 * #wasmtime_extern_t. The `name` pointer return value is owned by the `store` 142 * and must be immediately used before calling any other APIs on 143 * #wasmtime_context_t. 144 */ 145 WASM_API_EXTERN bool wasmtime_instance_export_nth( 146 wasmtime_context_t *store, 147 const wasmtime_instance_t *instance, 148 size_t index, 149 char **name, 150 size_t *name_len, 151 wasmtime_extern_t *item 152 ); 153 154 #ifdef __cplusplus 155 } // extern "C" 156 #endif 157 158 #endif // WASMTIME_INSTANCE_H 159