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