1 /**
2  * \file wasmtime/linker.h
3  *
4  * Wasmtime API for a name-based linker used to instantiate modules.
5  */
6 
7 #ifndef WASMTIME_LINKER_H
8 #define WASMTIME_LINKER_H
9 
10 #include <wasm.h>
11 #include <wasmtime/conf.h>
12 #include <wasmtime/error.h>
13 #include <wasmtime/extern.h>
14 #include <wasmtime/func.h>
15 #include <wasmtime/instance.h>
16 #include <wasmtime/store.h>
17 
18 #ifdef __cplusplus
19 extern "C" {
20 #endif
21 
22 /**
23  * \typedef wasmtime_linker_t
24  * \brief Alias to #wasmtime_linker
25  *
26  * \struct #wasmtime_linker
27  * \brief Object used to conveniently link together and instantiate wasm
28  * modules.
29  *
30  * This type corresponds to the `wasmtime::Linker` type in Rust. This
31  * type is intended to make it easier to manage a set of modules that link
32  * together, or to make it easier to link WebAssembly modules to WASI.
33  *
34  * A #wasmtime_linker_t is a higher level way to instantiate a module than
35  * #wasm_instance_new since it works at the "string" level of imports rather
36  * than requiring 1:1 mappings.
37  */
38 typedef struct wasmtime_linker wasmtime_linker_t;
39 
40 /**
41  * \brief Creates a new linker for the specified engine.
42  *
43  * This function does not take ownership of the engine argument, and the caller
44  * is expected to delete the returned linker.
45  */
46 WASM_API_EXTERN wasmtime_linker_t *wasmtime_linker_new(wasm_engine_t *engine);
47 
48 /**
49  * \brief Clones existing linker.
50  *
51  * This function does not take ownership of the linker argument, and the caller
52  * is expected to delete the returned linker.
53  */
54 WASM_API_EXTERN wasmtime_linker_t *
55 wasmtime_linker_clone(wasmtime_linker_t *linker);
56 
57 /**
58  * \brief Deletes a linker
59  */
60 WASM_API_EXTERN void wasmtime_linker_delete(wasmtime_linker_t *linker);
61 
62 /**
63  * \brief Configures whether this linker allows later definitions to shadow
64  * previous definitions.
65  *
66  * By default this setting is `false`.
67  */
68 WASM_API_EXTERN void wasmtime_linker_allow_shadowing(wasmtime_linker_t *linker,
69                                                      bool allow_shadowing);
70 
71 /**
72  * \brief Ensures that `module` can be instantiated with this linker by defining
73  * all functions otherwise missing from this linker to trap.
74  */
75 WASM_API_EXTERN wasmtime_error_t *
76 wasmtime_linker_define_unknown_imports_as_traps(wasmtime_linker_t *linker,
77                                                 wasmtime_module_t *module);
78 
79 /**
80  * \brief Ensures that `module` can be instantiated with this linker by defining
81  * all functions otherwise missing from this linker to return the 'default' for
82  * what that import is.
83  */
84 WASM_API_EXTERN wasmtime_error_t *
85 wasmtime_linker_define_unknown_imports_as_default_values(
86     wasmtime_linker_t *linker, wasmtime_context_t *store,
87     wasmtime_module_t *module);
88 
89 /**
90  * \brief Defines a new item in this linker.
91  *
92  * \param linker the linker the name is being defined in.
93  * \param store the store that the `item` is owned by.
94  * \param module the module name the item is defined under.
95  * \param module_len the byte length of `module`
96  * \param name the field name the item is defined under
97  * \param name_len the byte length of `name`
98  * \param item the item that is being defined in this linker.
99  *
100  * \return On success `NULL` is returned, otherwise an error is returned which
101  * describes why the definition failed.
102  *
103  * For more information about name resolution consult the [Rust
104  * documentation](https://bytecodealliance.github.io/wasmtime/api/wasmtime/struct.Linker.html#name-resolution).
105  */
106 WASM_API_EXTERN wasmtime_error_t *
107 wasmtime_linker_define(wasmtime_linker_t *linker, wasmtime_context_t *store,
108                        const char *module, size_t module_len, const char *name,
109                        size_t name_len, const wasmtime_extern_t *item);
110 
111 /**
112  * \brief Defines a new function in this linker.
113  *
114  * \param linker the linker the name is being defined in.
115  * \param module the module name the item is defined under.
116  * \param module_len the byte length of `module`
117  * \param name the field name the item is defined under
118  * \param name_len the byte length of `name`
119  * \param ty the type of the function that's being defined
120  * \param cb the host callback to invoke when the function is called
121  * \param data the host-provided data to provide as the first argument to the
122  *        callback
123  * \param finalizer an optional finalizer for the `data` argument.
124  *
125  * \return On success `NULL` is returned, otherwise an error is returned which
126  * describes why the definition failed.
127  *
128  * For more information about name resolution consult the [Rust
129  * documentation](https://bytecodealliance.github.io/wasmtime/api/wasmtime/struct.Linker.html#name-resolution).
130  *
131  * Note that this function does not create a #wasmtime_func_t. This creates a
132  * store-independent function within the linker, allowing this function
133  * definition to be used with multiple stores.
134  *
135  * For more information about host callbacks see #wasmtime_func_new.
136  */
137 WASM_API_EXTERN wasmtime_error_t *wasmtime_linker_define_func(
138     wasmtime_linker_t *linker, const char *module, size_t module_len,
139     const char *name, size_t name_len, const wasm_functype_t *ty,
140     wasmtime_func_callback_t cb, void *data, void (*finalizer)(void *));
141 
142 /**
143  * \brief Defines a new function in this linker.
144  *
145  * This is the same as #wasmtime_linker_define_func except that it's the analog
146  * of #wasmtime_func_new_unchecked instead of #wasmtime_func_new. Be sure to
147  * consult the documentation of #wasmtime_linker_define_func for argument
148  * information as well as #wasmtime_func_new_unchecked for why this is an
149  * unsafe API.
150  */
151 WASM_API_EXTERN wasmtime_error_t *wasmtime_linker_define_func_unchecked(
152     wasmtime_linker_t *linker, const char *module, size_t module_len,
153     const char *name, size_t name_len, const wasm_functype_t *ty,
154     wasmtime_func_unchecked_callback_t cb, void *data,
155     void (*finalizer)(void *));
156 
157 #ifdef WASMTIME_FEATURE_WASI
158 
159 /**
160  * \brief Defines WASI functions in this linker.
161  *
162  * \param linker the linker the name is being defined in.
163  *
164  * \return On success `NULL` is returned, otherwise an error is returned which
165  * describes why the definition failed.
166  *
167  * This function will provide WASI function names in the specified linker. Note
168  * that when an instance is created within a store then the store also needs to
169  * have its WASI settings configured with #wasmtime_context_set_wasi for WASI
170  * functions to work, otherwise an assert will be tripped that will abort the
171  * process.
172  *
173  * For more information about name resolution consult the [Rust
174  * documentation](https://bytecodealliance.github.io/wasmtime/api/wasmtime/struct.Linker.html#name-resolution).
175  */
176 WASM_API_EXTERN wasmtime_error_t *
177 wasmtime_linker_define_wasi(wasmtime_linker_t *linker);
178 
179 #endif // WASMTIME_FEATURE_WASI
180 
181 /**
182  * \brief Defines an instance under the specified name in this linker.
183  *
184  * \param linker the linker the name is being defined in.
185  * \param store the store that owns `instance`
186  * \param name the module name to define `instance` under.
187  * \param name_len the byte length of `name`
188  * \param instance a previously-created instance.
189  *
190  * \return On success `NULL` is returned, otherwise an error is returned which
191  * describes why the definition failed.
192  *
193  * This function will take all of the exports of the `instance` provided and
194  * defined them under a module called `name` with a field name as the export's
195  * own name.
196  *
197  * For more information about name resolution consult the [Rust
198  * documentation](https://bytecodealliance.github.io/wasmtime/api/wasmtime/struct.Linker.html#name-resolution).
199  */
200 WASM_API_EXTERN wasmtime_error_t *wasmtime_linker_define_instance(
201     wasmtime_linker_t *linker, wasmtime_context_t *store, const char *name,
202     size_t name_len, const wasmtime_instance_t *instance);
203 
204 /**
205  * \brief Instantiates a #wasm_module_t with the items defined in this linker.
206  *
207  * \param linker the linker used to instantiate the provided module.
208  * \param store the store that is used to instantiate within
209  * \param module the module that is being instantiated.
210  * \param instance the returned instance, if successful.
211  * \param trap a trap returned, if the start function traps.
212  *
213  * \return One of three things can happen as a result of this function. First
214  * the module could be successfully instantiated and returned through
215  * `instance`, meaning the return value and `trap` are both set to `NULL`.
216  * Second the start function may trap, meaning the return value and `instance`
217  * are set to `NULL` and `trap` describes the trap that happens. Finally
218  * instantiation may fail for another reason, in which case an error is returned
219  * and `trap` and `instance` are set to `NULL`.
220  *
221  * This function will attempt to satisfy all of the imports of the `module`
222  * provided with items previously defined in this linker. If any name isn't
223  * defined in the linker than an error is returned. (or if the previously
224  * defined item is of the wrong type).
225  */
226 WASM_API_EXTERN wasmtime_error_t *
227 wasmtime_linker_instantiate(const wasmtime_linker_t *linker,
228                             wasmtime_context_t *store,
229                             const wasmtime_module_t *module,
230                             wasmtime_instance_t *instance, wasm_trap_t **trap);
231 
232 /**
233  * \brief Defines automatic instantiations of a #wasm_module_t in this linker.
234  *
235  * \param linker the linker the module is being added to
236  * \param store the store that is used to instantiate `module`
237  * \param name the name of the module within the linker
238  * \param name_len the byte length of `name`
239  * \param module the module that's being instantiated
240  *
241  * \return An error if the module could not be instantiated or added or `NULL`
242  * on success.
243  *
244  * This function automatically handles [Commands and
245  * Reactors](https://github.com/WebAssembly/WASI/blob/main/legacy/application-abi.md#current-unstable-abi)
246  * instantiation and initialization.
247  *
248  * For more information see the [Rust
249  * documentation](https://bytecodealliance.github.io/wasmtime/api/wasmtime/struct.Linker.html#method.module).
250  */
251 WASM_API_EXTERN wasmtime_error_t *
252 wasmtime_linker_module(wasmtime_linker_t *linker, wasmtime_context_t *store,
253                        const char *name, size_t name_len,
254                        const wasmtime_module_t *module);
255 
256 /**
257  * \brief Acquires the "default export" of the named module in this linker.
258  *
259  * \param linker the linker to load from
260  * \param store the store to load a function into
261  * \param name the name of the module to get the default export for
262  * \param name_len the byte length of `name`
263  * \param func where to store the extracted default function.
264  *
265  * \return An error is returned if the default export could not be found, or
266  * `NULL` is returned and `func` is filled in otherwise.
267  *
268  * For more information see the [Rust
269  * documentation](https://bytecodealliance.github.io/wasmtime/api/wasmtime/struct.Linker.html#method.get_default).
270  */
271 WASM_API_EXTERN wasmtime_error_t *
272 wasmtime_linker_get_default(const wasmtime_linker_t *linker,
273                             wasmtime_context_t *store, const char *name,
274                             size_t name_len, wasmtime_func_t *func);
275 
276 /**
277  * \brief Loads an item by name from this linker.
278  *
279  * \param linker the linker to load from
280  * \param store the store to load the item into
281  * \param module the name of the module to get
282  * \param module_len the byte length of `module`
283  * \param name the name of the field to get
284  * \param name_len the byte length of `name`
285  * \param item where to store the extracted item
286  *
287  * \return A nonzero value if the item is defined, in which case `item` is also
288  * filled in. Otherwise zero is returned.
289  */
290 WASM_API_EXTERN bool wasmtime_linker_get(const wasmtime_linker_t *linker,
291                                          wasmtime_context_t *store,
292                                          const char *module, size_t module_len,
293                                          const char *name, size_t name_len,
294                                          wasmtime_extern_t *item);
295 
296 /**
297  * \brief Perform all the checks for instantiating `module` with the linker,
298  *        except that instantiation doesn't actually finish.
299  *
300  * \param linker the linker used to instantiate the provided module.
301  * \param module the module that is being instantiated.
302  * \param instance_pre the returned instance_pre, if successful.
303  *
304  * \return An error or `NULL` if successful.
305  *
306  * For more information see the Rust documentation at:
307  * https://docs.wasmtime.dev/api/wasmtime/struct.Linker.html#method.instantiate_pre
308  */
309 WASM_API_EXTERN wasmtime_error_t *
310 wasmtime_linker_instantiate_pre(const wasmtime_linker_t *linker,
311                                 const wasmtime_module_t *module,
312                                 wasmtime_instance_pre_t **instance_pre);
313 
314 #ifdef __cplusplus
315 } // extern "C"
316 #endif
317 
318 #endif // WASMTIME_LINKER_H
319