1 /// \file wasmtime/component/linker.h 2 3 #ifndef WASMTIME_COMPONENT_LINKER_H 4 #define WASMTIME_COMPONENT_LINKER_H 5 6 #include <wasm.h> 7 #include <wasmtime/component/component.h> 8 #include <wasmtime/component/instance.h> 9 #include <wasmtime/component/types/func.h> 10 #include <wasmtime/conf.h> 11 #include <wasmtime/error.h> 12 #include <wasmtime/module.h> 13 #include <wasmtime/store.h> 14 15 #ifdef WASMTIME_FEATURE_COMPONENT_MODEL 16 17 #ifdef __cplusplus 18 extern "C" { 19 #endif 20 21 /// A type used to instantiate a #wasmtime_component_t. 22 typedef struct wasmtime_component_linker_t wasmtime_component_linker_t; 23 24 /// Structure representing an "instance" being defined within a linker. 25 typedef struct wasmtime_component_linker_instance_t 26 wasmtime_component_linker_instance_t; 27 28 /** 29 * \brief Creates a new #wasmtime_component_linker_t for the specified engine. 30 * 31 * \param engine the compilation environment and configuration 32 * 33 * \return a pointer to the newly created #wasmtime_component_linker_t 34 */ 35 WASM_API_EXTERN wasmtime_component_linker_t * 36 wasmtime_component_linker_new(const wasm_engine_t *engine); 37 38 /** 39 * \brief Configures whether this linker allows later definitions to shadow 40 * previous definitions. 41 * 42 * By default this setting is `false`. 43 */ 44 WASM_API_EXTERN void 45 wasmtime_component_linker_allow_shadowing(wasmtime_component_linker_t *linker, 46 bool allow); 47 48 /** 49 * \brief Returns the "root instance" of this linker, used to define names into 50 * the root namespace. 51 * 52 * \warning This acquires exclusive access to the \p linker. The \p linker 53 * *MUST* not be accessed by anything until the returned 54 * #wasmtime_component_linker_instance_t in \p linker_instance_out is destroyed 55 * by #wasmtime_component_linker_instance_delete. 56 */ 57 WASM_API_EXTERN wasmtime_component_linker_instance_t * 58 wasmtime_component_linker_root(wasmtime_component_linker_t *linker); 59 60 /** 61 * \brief Instantiates a component instance in a given #wasmtime_context_t 62 * 63 * \param linker a #wasmtime_component_linker_t that will help provide host 64 * functions 65 * \param context the #wasmtime_context_t in which the instance should be 66 * created 67 * \param component the #wasmtime_component_t to instantiate 68 * \param instance_out on success, the instantiated 69 * #wasmtime_component_instance_t 70 * 71 * \return wasmtime_error_t* on success `NULL` is returned, otherwise an error 72 * is returned which describes why the build failed. 73 */ 74 WASM_API_EXTERN wasmtime_error_t *wasmtime_component_linker_instantiate( 75 const wasmtime_component_linker_t *linker, wasmtime_context_t *context, 76 const wasmtime_component_t *component, 77 wasmtime_component_instance_t *instance_out); 78 79 /** 80 * \brief Defines all unknown imports of `component` as trapping functions. 81 */ 82 WASM_API_EXTERN wasmtime_error_t * 83 wasmtime_component_linker_define_unknown_imports_as_traps( 84 wasmtime_component_linker_t *linker, const wasmtime_component_t *component); 85 86 /** 87 * \brief Deletes a #wasmtime_component_linker_t created by 88 * #wasmtime_component_linker_new 89 * 90 * \param linker the #wasmtime_component_linker_t to delete 91 */ 92 WASM_API_EXTERN void 93 wasmtime_component_linker_delete(wasmtime_component_linker_t *linker); 94 95 /** 96 * \brief Defines a nested instance within this instance. 97 * 98 * This can be used to describe arbitrarily nested levels of instances within a 99 * linker to satisfy nested instance exports of components. 100 * 101 * \warning This acquires exclusive access to the \p linker_instance. The \p 102 * linker_instance *MUST* not be accessed by anything until the returned 103 * #wasmtime_component_linker_instance_t in \p linker_instance_out is destroyed 104 * by #wasmtime_component_linker_instance_delete. 105 * 106 * \param linker_instance the linker instance from which the new one is created 107 * \param name new instance name 108 * \param name_len length of \p name in bytes 109 * \param linker_instance_out on success, the new 110 * #wasmtime_component_linker_instance_t 111 * \return on success `NULL`, otherwise an error 112 */ 113 WASM_API_EXTERN wasmtime_error_t * 114 wasmtime_component_linker_instance_add_instance( 115 wasmtime_component_linker_instance_t *linker_instance, const char *name, 116 size_t name_len, 117 wasmtime_component_linker_instance_t **linker_instance_out); 118 119 /** 120 * \brief Defines a #wasmtime_module_t within this instance. 121 * 122 * This can be used to provide a core wasm #wasmtime_module_t as an import 123 * to a component. The #wasmtime_module_t provided is saved within the 124 * linker for the specified \p name in this instance. 125 * 126 * \param linker_instance the instance to define the module in 127 * \param name the module name 128 * \param name_len length of \p name in bytes 129 * \param module the module 130 * \return on success `NULL`, otherwise an error 131 */ 132 WASM_API_EXTERN wasmtime_error_t *wasmtime_component_linker_instance_add_module( 133 wasmtime_component_linker_instance_t *linker_instance, const char *name, 134 size_t name_len, const wasmtime_module_t *module); 135 136 /// Type of the callback used in #wasmtime_component_linker_instance_add_func 137 typedef wasmtime_error_t *(*wasmtime_component_func_callback_t)( 138 void *, wasmtime_context_t *, const wasmtime_component_func_type_t *, 139 wasmtime_component_val_t *, size_t, wasmtime_component_val_t *, size_t); 140 141 /** 142 * \brief Define a function within this instance. 143 * 144 * \param linker_instance the instance to define the function in 145 * \param name the module name 146 * \param name_len length of \p name in bytes 147 * \param callback the callback when this function gets called 148 * \param data host-specific data passed to the callback invocation, can be 149 * `NULL` 150 * \param finalizer optional finalizer for \p data, can be `NULL` 151 * \return on success `NULL`, otherwise an error 152 */ 153 WASM_API_EXTERN wasmtime_error_t *wasmtime_component_linker_instance_add_func( 154 wasmtime_component_linker_instance_t *linker_instance, const char *name, 155 size_t name_len, wasmtime_component_func_callback_t callback, void *data, 156 void (*finalizer)(void *)); 157 158 #ifdef WASMTIME_FEATURE_WASI 159 160 /** 161 * \brief Add all WASI interfaces into the \p linker provided. 162 */ 163 WASM_API_EXTERN wasmtime_error_t * 164 wasmtime_component_linker_add_wasip2(wasmtime_component_linker_t *linker); 165 166 #endif // WASMTIME_FEATURE_WASI 167 168 #ifdef WASMTIME_FEATURE_WASI_HTTP 169 170 /** 171 * \brief Add WASI HTTP interfaces into the \p linker provided. 172 * 173 * This adds `wasi:http/types` and `wasi:http/outgoing-handler` to the linker. 174 * Requires WASI to be added first via #wasmtime_component_linker_add_wasip2. 175 */ 176 WASM_API_EXTERN wasmtime_error_t * 177 wasmtime_component_linker_add_wasi_http(wasmtime_component_linker_t *linker); 178 179 #endif // WASMTIME_FEATURE_WASI_HTTP 180 181 /// Type of the callback used in 182 /// #wasmtime_component_linker_instance_add_resource 183 typedef wasmtime_error_t *(*wasmtime_component_resource_destructor_t)( 184 void *, wasmtime_context_t *, uint32_t); 185 186 /** 187 * \brief Defines a new resource type within this instance. 188 * 189 * This can be used to define a new resource type that the guest will be able 190 * to import. Here the `resource` is a type, often a host-defined type, which 191 * can be used to distinguish and definite different types of resources. A 192 * destruction callback is also specified via `destructor` which has private 193 * data `data` along with an optional `finalizer` for the `data` too. 194 * 195 * \return on success `NULL`, otherwise an error 196 */ 197 WASM_API_EXTERN wasmtime_error_t * 198 wasmtime_component_linker_instance_add_resource( 199 wasmtime_component_linker_instance_t *linker_instance, const char *name, 200 size_t name_len, const wasmtime_component_resource_type_t *resource, 201 wasmtime_component_resource_destructor_t destructor, void *data, 202 void (*finalizer)(void *)); 203 204 /** 205 * \brief Deletes a #wasmtime_component_linker_instance_t 206 * 207 * \param linker_instance the #wasmtime_component_linker_instance_t to delete 208 */ 209 WASM_API_EXTERN void wasmtime_component_linker_instance_delete( 210 wasmtime_component_linker_instance_t *linker_instance); 211 212 #ifdef __cplusplus 213 } // extern "C" 214 #endif 215 216 #endif // WASMTIME_FEATURE_COMPONENT_MODEL 217 218 #endif // WASMTIME_COMPONENT_LINKER_H 219