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 * \typedef wasmtime_module_t 19 * \brief Convenience alias for #wasmtime_module 20 * 21 * \struct wasmtime_module 22 * \brief A compiled Wasmtime module. 23 * 24 * This type represents a compiled WebAssembly module. The compiled module is 25 * ready to be instantiated and can be inspected for imports/exports. It is safe 26 * to use a module across multiple threads simultaneously. 27 */ 28 typedef struct wasmtime_module wasmtime_module_t; 29 30 #ifdef WASMTIME_FEATURE_COMPILER 31 32 /** 33 * \brief Compiles a WebAssembly binary into a #wasmtime_module_t 34 * 35 * This function will compile a WebAssembly binary into an owned #wasm_module_t. 36 * This performs the same as #wasm_module_new except that it returns a 37 * #wasmtime_error_t type to get richer error information. 38 * 39 * On success the returned #wasmtime_error_t is `NULL` and the `ret` pointer is 40 * filled in with a #wasm_module_t. On failure the #wasmtime_error_t is 41 * non-`NULL` and the `ret` pointer is unmodified. 42 * 43 * This function does not take ownership of any of its arguments, but the 44 * returned error and module are owned by the caller. 45 */ 46 WASM_API_EXTERN wasmtime_error_t *wasmtime_module_new(wasm_engine_t *engine, 47 const uint8_t *wasm, 48 size_t wasm_len, 49 wasmtime_module_t **ret); 50 51 #endif // WASMTIME_FEATURE_COMPILER 52 53 /** 54 * \brief Deletes a module. 55 */ 56 WASM_API_EXTERN void wasmtime_module_delete(wasmtime_module_t *m); 57 58 /** 59 * \brief Creates a shallow clone of the specified module, increasing the 60 * internal reference count. 61 */ 62 WASM_API_EXTERN wasmtime_module_t *wasmtime_module_clone(wasmtime_module_t *m); 63 64 /** 65 * \brief Same as #wasm_module_imports, but for #wasmtime_module_t. 66 */ 67 WASM_API_EXTERN void wasmtime_module_imports(const wasmtime_module_t *module, 68 wasm_importtype_vec_t *out); 69 70 /** 71 * \brief Same as #wasm_module_exports, but for #wasmtime_module_t. 72 */ 73 WASM_API_EXTERN void wasmtime_module_exports(const wasmtime_module_t *module, 74 wasm_exporttype_vec_t *out); 75 76 #ifdef WASMTIME_FEATURE_COMPILER 77 78 /** 79 * \brief Validate a WebAssembly binary. 80 * 81 * This function will validate the provided byte sequence to determine if it is 82 * a valid WebAssembly binary within the context of the engine provided. 83 * 84 * This function does not take ownership of its arguments but the caller is 85 * expected to deallocate the returned error if it is non-`NULL`. 86 * 87 * If the binary validates then `NULL` is returned, otherwise the error returned 88 * describes why the binary did not validate. 89 */ 90 WASM_API_EXTERN wasmtime_error_t * 91 wasmtime_module_validate(wasm_engine_t *engine, const uint8_t *wasm, 92 size_t wasm_len); 93 94 /** 95 * \brief This function serializes compiled module artifacts as blob data. 96 * 97 * \param module the module 98 * \param ret if the conversion is successful, this byte vector is filled in 99 * with the serialized compiled module. 100 * 101 * \return a non-null error if parsing fails, or returns `NULL`. If parsing 102 * fails then `ret` isn't touched. 103 * 104 * This function does not take ownership of `module`, and the caller is 105 * expected to deallocate the returned #wasmtime_error_t and #wasm_byte_vec_t. 106 */ 107 WASM_API_EXTERN wasmtime_error_t * 108 wasmtime_module_serialize(wasmtime_module_t *module, wasm_byte_vec_t *ret); 109 110 #endif // WASMTIME_FEATURE_COMPILER 111 112 /** 113 * \brief Build a module from serialized data. 114 * 115 * This function does not take ownership of any of its arguments, but the 116 * returned error and module are owned by the caller. 117 * 118 * This function is not safe to receive arbitrary user input. See the Rust 119 * documentation for more information on what inputs are safe to pass in here 120 * (e.g. only that of `wasmtime_module_serialize`) 121 */ 122 WASM_API_EXTERN wasmtime_error_t * 123 wasmtime_module_deserialize(wasm_engine_t *engine, const uint8_t *bytes, 124 size_t bytes_len, wasmtime_module_t **ret); 125 126 /** 127 * \brief Deserialize a module from an on-disk file. 128 * 129 * This function is the same as #wasmtime_module_deserialize except that it 130 * reads the data for the serialized module from the path on disk. This can be 131 * faster than the alternative which may require copying the data around. 132 * 133 * This function does not take ownership of any of its arguments, but the 134 * returned error and module are owned by the caller. 135 * 136 * This function is not safe to receive arbitrary user input. See the Rust 137 * documentation for more information on what inputs are safe to pass in here 138 * (e.g. only that of `wasmtime_module_serialize`) 139 */ 140 WASM_API_EXTERN wasmtime_error_t * 141 wasmtime_module_deserialize_file(wasm_engine_t *engine, const char *path, 142 wasmtime_module_t **ret); 143 144 /** 145 * \brief Returns the range of bytes in memory where this module’s compilation 146 * image resides. 147 * 148 * The compilation image for a module contains executable code, data, debug 149 * information, etc. This is roughly the same as the wasmtime_module_serialize 150 * but not the exact same. 151 * 152 * For more details see: 153 * https://docs.wasmtime.dev/api/wasmtime/struct.Module.html#method.image_range 154 */ 155 WASM_API_EXTERN void 156 wasmtime_module_image_range(const wasmtime_module_t *module, void **start, 157 void **end); 158 159 #ifdef __cplusplus 160 } // extern "C" 161 #endif 162 163 #endif // WASMTIME_MODULE_H 164