1 /** 2 * \file wasmtime/module.h 3 * 4 * APIs for interacting with modules in Wasmtime 5 */ 6 7 #ifndef WASMTIME_MODULE_H 8 #define WASMTIME_MODULE_H 9 10 #include <wasm.h> 11 #include <wasmtime/error.h> 12 13 #ifdef __cplusplus 14 extern "C" { 15 #endif 16 17 /** 18 * \brief An opaque object representing the type of a module. 19 */ 20 typedef struct wasmtime_moduletype wasmtime_moduletype_t; 21 22 /** 23 * \brief Deletes a module type. 24 */ 25 WASM_API_EXTERN void wasmtime_moduletype_delete(wasmtime_moduletype_t *ty); 26 27 /** 28 * \brief Returns the list of imports that this module type requires. 29 * 30 * This function does not take ownership of the provided module 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_moduletype_imports(const wasmtime_moduletype_t*, wasm_importtype_vec_t* out); 35 36 /** 37 * \brief Returns the list of exports that this module type provides. 38 * 39 * This function does not take ownership of the provided module type but 40 * ownership of `out` is passed to the caller. Note that `out` is treated as 41 * uninitialized when passed to this function. 42 */ 43 WASM_API_EXTERN void wasmtime_moduletype_exports(const wasmtime_moduletype_t*, wasm_exporttype_vec_t* out); 44 45 /** 46 * \brief Converts a #wasmtime_moduletype_t to a #wasm_externtype_t 47 * 48 * The returned value is owned by the #wasmtime_moduletype_t argument and should not 49 * be deleted. 50 */ 51 WASM_API_EXTERN wasm_externtype_t* wasmtime_moduletype_as_externtype(wasmtime_moduletype_t*); 52 53 /** 54 * \brief Attempts to convert a #wasm_externtype_t to a #wasmtime_moduletype_t 55 * 56 * The returned value is owned by the #wasmtime_moduletype_t argument and 57 * should not be deleted. Returns `NULL` if the provided argument is not a 58 * #wasmtime_moduletype_t. 59 */ 60 WASM_API_EXTERN wasmtime_moduletype_t* wasmtime_externtype_as_moduletype(wasm_externtype_t*); 61 62 /** 63 * \typedef wasmtime_module_t 64 * \brief Convenience alias for #wasmtime_module 65 * 66 * \struct wasmtime_module 67 * \brief A compiled Wasmtime module. 68 * 69 * This type represents a compiled WebAssembly module. The compiled module is 70 * ready to be instantiated and can be inspected for imports/exports. It is safe 71 * to use a module across multiple threads simultaneously. 72 */ 73 typedef struct wasmtime_module wasmtime_module_t; 74 75 /** 76 * \brief Compiles a WebAssembly binary into a #wasmtime_module_t 77 * 78 * This function will compile a WebAssembly binary into an owned #wasm_module_t. 79 * This performs the same as #wasm_module_new except that it returns a 80 * #wasmtime_error_t type to get richer error information. 81 * 82 * On success the returned #wasmtime_error_t is `NULL` and the `ret` pointer is 83 * filled in with a #wasm_module_t. On failure the #wasmtime_error_t is 84 * non-`NULL` and the `ret` pointer is unmodified. 85 * 86 * This function does not take ownership of any of its arguments, but the 87 * returned error and module are owned by the caller. 88 */ 89 WASM_API_EXTERN wasmtime_error_t *wasmtime_module_new( 90 wasm_engine_t *engine, 91 const uint8_t *wasm, 92 size_t wasm_len, 93 wasmtime_module_t **ret 94 ); 95 96 /** 97 * \brief Deletes a module. 98 */ 99 WASM_API_EXTERN void wasmtime_module_delete(wasmtime_module_t *m); 100 101 /** 102 * \brief Creates a shallow clone of the specified module, increasing the 103 * internal reference count. 104 */ 105 WASM_API_EXTERN wasmtime_module_t *wasmtime_module_clone(wasmtime_module_t *m); 106 107 /** 108 * \brief Validate a WebAssembly binary. 109 * 110 * This function will validate the provided byte sequence to determine if it is 111 * a valid WebAssembly binary within the context of the engine provided. 112 * 113 * This function does not take ownership of its arguments but the caller is 114 * expected to deallocate the returned error if it is non-`NULL`. 115 * 116 * If the binary validates then `NULL` is returned, otherwise the error returned 117 * describes why the binary did not validate. 118 */ 119 WASM_API_EXTERN wasmtime_error_t *wasmtime_module_validate( 120 wasm_engine_t *engine, 121 const uint8_t *wasm, 122 size_t wasm_len 123 ); 124 125 /** 126 * \brief Returns the type of this module. 127 * 128 * The returned #wasmtime_moduletype_t is expected to be deallocated by the 129 * caller. 130 */ 131 WASM_API_EXTERN wasmtime_moduletype_t* wasmtime_module_type(const wasmtime_module_t*); 132 133 /** 134 * \brief This function serializes compiled module artifacts as blob data. 135 * 136 * \param module the module 137 * \param ret if the conversion is successful, this byte vector is filled in with 138 * the serialized compiled module. 139 * 140 * \return a non-null error if parsing fails, or returns `NULL`. If parsing 141 * fails then `ret` isn't touched. 142 * 143 * This function does not take ownership of `module`, and the caller is 144 * expected to deallocate the returned #wasmtime_error_t and #wasm_byte_vec_t. 145 */ 146 WASM_API_EXTERN wasmtime_error_t* wasmtime_module_serialize( 147 wasmtime_module_t* module, 148 wasm_byte_vec_t *ret 149 ); 150 151 /** 152 * \brief Build a module from serialized data. 153 * 154 * This function does not take ownership of any of its arguments, but the 155 * returned error and module are owned by the caller. 156 * 157 * This function is not safe to receive arbitrary user input. See the Rust 158 * documentation for more information on what inputs are safe to pass in here 159 * (e.g. only that of #wasmtime_module_serialize) 160 */ 161 WASM_API_EXTERN wasmtime_error_t *wasmtime_module_deserialize( 162 wasm_engine_t *engine, 163 const uint8_t *bytes, 164 size_t bytes_len, 165 wasmtime_module_t **ret 166 ); 167 168 #ifdef __cplusplus 169 } // extern "C" 170 #endif 171 172 #endif // WASMTIME_MODULE_H 173