1 /// \file wasmtime/component/component.h 2 3 #ifndef WASMTIME_COMPONENT_COMPONENT_H 4 #define WASMTIME_COMPONENT_COMPONENT_H 5 6 #include <wasm.h> 7 #include <wasmtime/conf.h> 8 #include <wasmtime/error.h> 9 10 #ifdef WASMTIME_FEATURE_COMPONENT_MODEL 11 12 #ifdef __cplusplus 13 extern "C" { 14 #endif 15 16 /// Representation of a component in the component model. 17 typedef struct wasmtime_component_t wasmtime_component_t; 18 19 #ifdef WASMTIME_FEATURE_COMPILER 20 21 /** 22 * \brief Compiles a WebAssembly binary into a #wasmtime_component_t 23 * 24 * This function will compile a WebAssembly binary into an owned 25 #wasmtime_component_t. 26 * 27 * It requires a component binary, such as what is produced by Rust `cargo 28 component` tooling. 29 * 30 * This function does not take ownership of any of its arguments, but the 31 * returned error and component are owned by the caller. 32 33 * \param engine the #wasm_engine_t that will create the component 34 * \param buf the address of the buffer containing the WebAssembly binary 35 * \param len the length of the buffer containing the WebAssembly binary 36 * \param component_out on success, contains the address of the created 37 * component 38 * 39 * \return NULL on success, else a #wasmtime_error_t describing the error 40 */ 41 WASM_API_EXTERN wasmtime_error_t * 42 wasmtime_component_new(const wasm_engine_t *engine, const uint8_t *buf, 43 size_t len, wasmtime_component_t **component_out); 44 45 /** 46 * \brief This function serializes compiled component artifacts as blob data. 47 * 48 * \param component the component 49 * \param ret if the conversion is successful, this byte vector is filled in 50 * with the serialized compiled component. 51 * 52 * \return a non-null error if parsing fails, or returns `NULL`. If parsing 53 * fails then `ret` isn't touched. 54 * 55 * This function does not take ownership of `component`, and the caller is 56 * expected to deallocate the returned #wasmtime_error_t and #wasm_byte_vec_t. 57 */ 58 WASM_API_EXTERN wasmtime_error_t * 59 wasmtime_component_serialize(const wasmtime_component_t *component, 60 wasm_byte_vec_t *ret); 61 62 #endif // WASMTIME_FEATURE_COMPILER 63 64 /** 65 * \brief Build a component from serialized data. 66 * 67 * This function does not take ownership of any of its arguments, but the 68 * returned error and component are owned by the caller. 69 * 70 * This function is not safe to receive arbitrary user input. See the Rust 71 * documentation for more information on what inputs are safe to pass in here 72 * (e.g. only that of `wasmtime_component_serialize`) 73 */ 74 WASM_API_EXTERN wasmtime_error_t * 75 wasmtime_component_deserialize(const wasm_engine_t *engine, const uint8_t *buf, 76 size_t len, 77 wasmtime_component_t **component_out); 78 79 /** 80 * \brief Deserialize a component from an on-disk file. 81 * 82 * This function is the same as #wasmtime_component_deserialize except that it 83 * reads the data for the serialized component from the path on disk. This can 84 * be faster than the alternative which may require copying the data around. 85 * 86 * This function does not take ownership of any of its arguments, but the 87 * returned error and component are owned by the caller. 88 * 89 * This function is not safe to receive arbitrary user input. See the Rust 90 * documentation for more information on what inputs are safe to pass in here 91 * (e.g. only that of `wasmtime_component_serialize`) 92 */ 93 WASM_API_EXTERN wasmtime_error_t * 94 wasmtime_component_deserialize_file(const wasm_engine_t *engine, 95 const char *path, 96 wasmtime_component_t **component_out); 97 98 /** 99 * \brief Creates a shallow clone of the specified component, increasing the 100 * internal reference count. 101 */ 102 WASM_API_EXTERN wasmtime_component_t * 103 wasmtime_component_clone(const wasmtime_component_t *component); 104 105 /** 106 * \brief Deletes a #wasmtime_component_t created by #wasmtime_component_new 107 * 108 * \param component the component to delete 109 */ 110 WASM_API_EXTERN void wasmtime_component_delete(wasmtime_component_t *component); 111 112 /// A value which represents a known export of a component. 113 typedef struct wasmtime_component_export_index_t 114 wasmtime_component_export_index_t; 115 116 /** 117 * \brief Looks up a specific export of this component by \p name optionally 118 * nested within the \p instance provided. 119 * 120 * \param component the component to look up \p name in 121 * \param instance_export_index optional (i.e. nullable) instance to look up in 122 * \param name the name of the export 123 * \param name_len length of \p name in bytes 124 * \return export index if found, else NULL 125 */ 126 WASM_API_EXTERN wasmtime_component_export_index_t * 127 wasmtime_component_get_export_index( 128 const wasmtime_component_t *component, 129 const wasmtime_component_export_index_t *instance_export_index, 130 const char *name, size_t name_len); 131 132 /** 133 * \brief Creates a new separately-owned copy of the specified index. 134 */ 135 WASM_API_EXTERN wasmtime_component_export_index_t * 136 wasmtime_component_export_index_clone( 137 const wasmtime_component_export_index_t *index); 138 139 /** 140 * \brief Deletes a #wasmtime_component_export_index_t 141 * 142 * \param export_index the export index to delete 143 */ 144 WASM_API_EXTERN void wasmtime_component_export_index_delete( 145 wasmtime_component_export_index_t *export_index); 146 147 #ifdef __cplusplus 148 } // extern "C" 149 #endif 150 151 #endif // WASMTIME_FEATURE_COMPONENT_MODEL 152 153 #endif // WASMTIME_COMPONENT_COMPONENT_H 154