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 /** 31 * \brief Compiles a WebAssembly binary into a #wasmtime_module_t 32 * 33 * This function will compile a WebAssembly binary into an owned #wasm_module_t. 34 * This performs the same as #wasm_module_new except that it returns a 35 * #wasmtime_error_t type to get richer error information. 36 * 37 * On success the returned #wasmtime_error_t is `NULL` and the `ret` pointer is 38 * filled in with a #wasm_module_t. On failure the #wasmtime_error_t is 39 * non-`NULL` and the `ret` pointer is unmodified. 40 * 41 * This function does not take ownership of any of its arguments, but the 42 * returned error and module are owned by the caller. 43 */ 44 WASM_API_EXTERN wasmtime_error_t *wasmtime_module_new( 45 wasm_engine_t *engine, 46 const uint8_t *wasm, 47 size_t wasm_len, 48 wasmtime_module_t **ret 49 ); 50 51 /** 52 * \brief Deletes a module. 53 */ 54 WASM_API_EXTERN void wasmtime_module_delete(wasmtime_module_t *m); 55 56 /** 57 * \brief Creates a shallow clone of the specified module, increasing the 58 * internal reference count. 59 */ 60 WASM_API_EXTERN wasmtime_module_t *wasmtime_module_clone(wasmtime_module_t *m); 61 62 /** 63 * \brief Same as #wasm_module_imports, but for #wasmtime_module_t. 64 */ 65 WASM_API_EXTERN void wasmtime_module_imports( 66 const wasmtime_module_t *module, 67 wasm_importtype_vec_t *out 68 ); 69 70 /** 71 * \brief Same as #wasm_module_exports, but for #wasmtime_module_t. 72 */ 73 WASM_API_EXTERN void wasmtime_module_exports( 74 const wasmtime_module_t *module, 75 wasm_exporttype_vec_t *out 76 ); 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 *wasmtime_module_validate( 91 wasm_engine_t *engine, 92 const uint8_t *wasm, 93 size_t wasm_len 94 ); 95 96 /** 97 * \brief This function serializes compiled module artifacts as blob data. 98 * 99 * \param module the module 100 * \param ret if the conversion is successful, this byte vector is filled in with 101 * the serialized compiled module. 102 * 103 * \return a non-null error if parsing fails, or returns `NULL`. If parsing 104 * fails then `ret` isn't touched. 105 * 106 * This function does not take ownership of `module`, and the caller is 107 * expected to deallocate the returned #wasmtime_error_t and #wasm_byte_vec_t. 108 */ 109 WASM_API_EXTERN wasmtime_error_t* wasmtime_module_serialize( 110 wasmtime_module_t* module, 111 wasm_byte_vec_t *ret 112 ); 113 114 /** 115 * \brief Build a module from serialized data. 116 * 117 * This function does not take ownership of any of its arguments, but the 118 * returned error and module are owned by the caller. 119 * 120 * This function is not safe to receive arbitrary user input. See the Rust 121 * documentation for more information on what inputs are safe to pass in here 122 * (e.g. only that of #wasmtime_module_serialize) 123 */ 124 WASM_API_EXTERN wasmtime_error_t *wasmtime_module_deserialize( 125 wasm_engine_t *engine, 126 const uint8_t *bytes, 127 size_t bytes_len, 128 wasmtime_module_t **ret 129 ); 130 131 /** 132 * \brief Deserialize a module from an on-disk file. 133 * 134 * This function is the same as #wasmtime_module_deserialize except that it 135 * reads the data for the serialized module from the path on disk. This can be 136 * faster than the alternative which may require copying the data around. 137 * 138 * This function does not take ownership of any of its arguments, but the 139 * returned error and module are owned by the caller. 140 * 141 * This function is not safe to receive arbitrary user input. See the Rust 142 * documentation for more information on what inputs are safe to pass in here 143 * (e.g. only that of #wasmtime_module_serialize) 144 */ 145 WASM_API_EXTERN wasmtime_error_t *wasmtime_module_deserialize_file( 146 wasm_engine_t *engine, 147 const char *path, 148 wasmtime_module_t **ret 149 ); 150 151 #ifdef __cplusplus 152 } // extern "C" 153 #endif 154 155 #endif // WASMTIME_MODULE_H 156