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/conf.h> 10 #include <wasmtime/error.h> 11 #include <wasmtime/store.h> 12 13 #ifdef WASMTIME_FEATURE_COMPONENT_MODEL 14 15 #ifdef __cplusplus 16 extern "C" { 17 #endif 18 19 /// A type used to instantiate a #wasmtime_component_t. 20 typedef struct wasmtime_component_linker_t wasmtime_component_linker_t; 21 22 /// Structure representing an "instance" being defined within a linker. 23 typedef struct wasmtime_component_linker_instance_t 24 wasmtime_component_linker_instance_t; 25 26 /** 27 * \brief Creates a new #wasmtime_component_linker_t for the specified engine. 28 * 29 * \param engine the compilation environment and configuration 30 * 31 * \return a pointer to the newly created #wasmtime_component_linker_t 32 */ 33 WASM_API_EXTERN wasmtime_component_linker_t * 34 wasmtime_component_linker_new(const wasm_engine_t *engine); 35 36 /** 37 * \brief Returns the "root instance" of this linker, used to define names into 38 * the root namespace. 39 * 40 * \warning This acquires exclusive access to the \p linker. The \p linker 41 * *MUST* not be accessed by anything until the returned 42 * #wasmtime_component_linker_instance_t in \p linker_instance_out is destroyed 43 * by #wasmtime_component_linker_instance_delete. 44 */ 45 WASM_API_EXTERN wasmtime_component_linker_instance_t * 46 wasmtime_component_linker_root(wasmtime_component_linker_t *linker); 47 48 /** 49 * \brief Instantiates a component instance in a given #wasmtime_context_t 50 * 51 * \param linker a #wasmtime_component_linker_t that will help provide host 52 * functions 53 * \param context the #wasmtime_context_t in which the instance should be 54 * created 55 * \param component the #wasmtime_component_t to instantiate 56 * \param instance_out on success, the instantiated 57 * #wasmtime_component_instance_t 58 * 59 * \return wasmtime_error_t* on success `NULL` is returned, otherwise an error 60 * is returned which describes why the build failed. 61 */ 62 WASM_API_EXTERN wasmtime_error_t *wasmtime_component_linker_instantiate( 63 const wasmtime_component_linker_t *linker, wasmtime_context_t *context, 64 const wasmtime_component_t *component, 65 wasmtime_component_instance_t *instance_out); 66 67 /** 68 * \brief Deletes a #wasmtime_component_linker_t created by 69 * #wasmtime_component_linker_new 70 * 71 * \param linker the #wasmtime_component_linker_t to delete 72 */ 73 WASM_API_EXTERN void 74 wasmtime_component_linker_delete(wasmtime_component_linker_t *linker); 75 76 /** 77 * \brief Defines a nested instance within this instance. 78 * 79 * This can be used to describe arbitrarily nested levels of instances within a 80 * linker to satisfy nested instance exports of components. 81 * 82 * \warning This acquires exclusive access to the \p linker_instance. The \p 83 * linker_instance *MUST* not be accessed by anything until the returned 84 * #wasmtime_component_linker_instance_t in \p linker_instance_out is destroyed 85 * by #wasmtime_component_linker_instance_delete. 86 * 87 * \param linker_instance the linker instance from which the new one is created 88 * \param name new instance name 89 * \param name_len length of \p name in bytes 90 * \param linker_instance_out on success, the new 91 * #wasmtime_component_linker_instance_t 92 * \return on success `NULL`, otherwise an error 93 */ 94 WASM_API_EXTERN wasmtime_error_t * 95 wasmtime_component_linker_instance_add_instance( 96 wasmtime_component_linker_instance_t *linker_instance, const char *name, 97 size_t name_len, 98 wasmtime_component_linker_instance_t **linker_instance_out); 99 100 /** 101 * \brief Defines a #wasmtime_module_t within this instance. 102 * 103 * This can be used to provide a core wasm #wasmtime_module_t as an import 104 * to a component. The #wasmtime_module_t provided is saved within the 105 * linker for the specified \p name in this instance. 106 * 107 * \param linker_instance the instance to define the module in 108 * \param name the module name 109 * \param name_len length of \p name in bytes 110 * \param module the module 111 * \return on success `NULL`, otherwise an error 112 */ 113 WASM_API_EXTERN wasmtime_error_t *wasmtime_component_linker_instance_add_module( 114 wasmtime_component_linker_instance_t *linker_instance, const char *name, 115 size_t name_len, const wasmtime_module_t *module); 116 117 /// Type of the callback used in #wasmtime_component_linker_instance_add_func 118 typedef wasmtime_error_t *(*wasmtime_component_func_callback_t)( 119 void *, wasmtime_context_t *, const wasmtime_component_val_t *, size_t, 120 wasmtime_component_val_t *, size_t); 121 122 /** 123 * \brief Define a function within this instance. 124 * 125 * \param linker_instance the instance to define the function in 126 * \param name the module name 127 * \param name_len length of \p name in bytes 128 * \param callback the callback when this function gets called 129 * \param data host-specific data passed to the callback invocation, can be 130 * `NULL` 131 * \param finalizer optional finalizer for \p data, can be `NULL` 132 * \return on success `NULL`, otherwise an error 133 */ 134 WASM_API_EXTERN wasmtime_error_t *wasmtime_component_linker_instance_add_func( 135 wasmtime_component_linker_instance_t *linker_instance, const char *name, 136 size_t name_len, wasmtime_component_func_callback_t callback, void *data, 137 void (*finalizer)()); 138 139 #ifdef WASMTIME_FEATURE_WASI 140 141 /** 142 * \brief Add all WASI interfaces into the \p linker provided. 143 */ 144 WASM_API_EXTERN wasmtime_error_t * 145 wasmtime_component_linker_add_wasip2(wasmtime_component_linker_t *linker); 146 147 #endif // WASMTIME_FEATURE_WASI 148 149 /** 150 * \brief Deletes a #wasmtime_component_linker_instance_t 151 * 152 * \param linker_instance the #wasmtime_component_linker_instance_t to delete 153 */ 154 WASM_API_EXTERN void wasmtime_component_linker_instance_delete( 155 wasmtime_component_linker_instance_t *linker_instance); 156 157 #ifdef __cplusplus 158 } // extern "C" 159 #endif 160 161 #endif // WASMTIME_FEATURE_COMPONENT_MODEL 162 163 #endif // WASMTIME_COMPONENT_LINKER_H 164