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