wasmtime-c-api-impl 44.0.0

C API to expose the Wasmtime runtime
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163

/// \file wasmtime/component/component.h

#ifndef WASMTIME_COMPONENT_COMPONENT_H
#define WASMTIME_COMPONENT_COMPONENT_H

#include <wasm.h>
#include <wasmtime/component/types/component.h>
#include <wasmtime/conf.h>
#include <wasmtime/error.h>

#ifdef WASMTIME_FEATURE_COMPONENT_MODEL

#ifdef __cplusplus
extern "C" {
#endif

/// Representation of a component in the component model.
typedef struct wasmtime_component_t wasmtime_component_t;

#ifdef WASMTIME_FEATURE_COMPILER

/**
 * \brief Compiles a WebAssembly binary into a #wasmtime_component_t
 *
 * This function will compile a WebAssembly binary into an owned
 #wasmtime_component_t.
 *
 * It requires a component binary, such as what is produced by Rust `cargo
 component` tooling.
 *
 * This function does not take ownership of any of its arguments, but the
 * returned error and component are owned by the caller.

 * \param engine the #wasm_engine_t that will create the component
 * \param buf the address of the buffer containing the WebAssembly binary
 * \param len the length of the buffer containing the WebAssembly binary
 * \param component_out on success, contains the address of the created
 *        component
 *
 * \return NULL on success, else a #wasmtime_error_t describing the error
 */
WASM_API_EXTERN wasmtime_error_t *
wasmtime_component_new(const wasm_engine_t *engine, const uint8_t *buf,
                       size_t len, wasmtime_component_t **component_out);

/**
 * \brief This function serializes compiled component artifacts as blob data.
 *
 * \param component the component
 * \param ret if the conversion is successful, this byte vector is filled in
 * with the serialized compiled component.
 *
 * \return a non-null error if parsing fails, or returns `NULL`. If parsing
 * fails then `ret` isn't touched.
 *
 * This function does not take ownership of `component`, and the caller is
 * expected to deallocate the returned #wasmtime_error_t and #wasm_byte_vec_t.
 */
WASM_API_EXTERN wasmtime_error_t *
wasmtime_component_serialize(const wasmtime_component_t *component,
                             wasm_byte_vec_t *ret);

#endif // WASMTIME_FEATURE_COMPILER

/**
 * \brief Build a component from serialized data.
 *
 * This function does not take ownership of any of its arguments, but the
 * returned error and component are owned by the caller.
 *
 * This function is not safe to receive arbitrary user input. See the Rust
 * documentation for more information on what inputs are safe to pass in here
 * (e.g. only that of `wasmtime_component_serialize`)
 */
WASM_API_EXTERN wasmtime_error_t *
wasmtime_component_deserialize(const wasm_engine_t *engine, const uint8_t *buf,
                               size_t len,
                               wasmtime_component_t **component_out);

/**
 * \brief Deserialize a component from an on-disk file.
 *
 * This function is the same as #wasmtime_component_deserialize except that it
 * reads the data for the serialized component from the path on disk. This can
 * be faster than the alternative which may require copying the data around.
 *
 * This function does not take ownership of any of its arguments, but the
 * returned error and component are owned by the caller.
 *
 * This function is not safe to receive arbitrary user input. See the Rust
 * documentation for more information on what inputs are safe to pass in here
 * (e.g. only that of `wasmtime_component_serialize`)
 */
WASM_API_EXTERN wasmtime_error_t *
wasmtime_component_deserialize_file(const wasm_engine_t *engine,
                                    const char *path,
                                    wasmtime_component_t **component_out);

/**
 * \brief Creates a shallow clone of the specified component, increasing the
 * internal reference count.
 */
WASM_API_EXTERN wasmtime_component_t *
wasmtime_component_clone(const wasmtime_component_t *component);

/**
 * \brief Returns the type of this component.
 *
 * The returned pointer must be deallocatd with
 * `wasmtime_component_type_delete`.
 */
WASM_API_EXTERN wasmtime_component_type_t *
wasmtime_component_type(const wasmtime_component_t *component);

/**
 * \brief Deletes a #wasmtime_component_t created by #wasmtime_component_new
 *
 * \param component the component to delete
 */
WASM_API_EXTERN void wasmtime_component_delete(wasmtime_component_t *component);

/// A value which represents a known export of a component.
typedef struct wasmtime_component_export_index_t
    wasmtime_component_export_index_t;

/**
 * \brief Looks up a specific export of this component by \p name optionally
 * nested within the \p instance provided.
 *
 * \param component the component to look up \p name in
 * \param instance_export_index optional (i.e. nullable) instance to look up in
 * \param name the name of the export
 * \param name_len length of \p name in bytes
 * \return export index if found, else NULL
 */
WASM_API_EXTERN wasmtime_component_export_index_t *
wasmtime_component_get_export_index(
    const wasmtime_component_t *component,
    const wasmtime_component_export_index_t *instance_export_index,
    const char *name, size_t name_len);

/**
 * \brief Creates a new separately-owned copy of the specified index.
 */
WASM_API_EXTERN wasmtime_component_export_index_t *
wasmtime_component_export_index_clone(
    const wasmtime_component_export_index_t *index);

/**
 * \brief Deletes a #wasmtime_component_export_index_t
 *
 * \param export_index the export index to delete
 */
WASM_API_EXTERN void wasmtime_component_export_index_delete(
    wasmtime_component_export_index_t *export_index);

#ifdef __cplusplus
} // extern "C"
#endif

#endif // WASMTIME_FEATURE_COMPONENT_MODEL

#endif // WASMTIME_COMPONENT_COMPONENT_H