-
Notifications
You must be signed in to change notification settings - Fork 3
/
wasm_runtime.h
315 lines (299 loc) · 11.8 KB
/
wasm_runtime.h
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
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
/* See doc at: https://github.com/eqrion/cbindgen/blob/master/docs.md#cbindgentoml
/* Generated with cbindgen:0.26.0 */
#include <stdarg.h>
#include <stdbool.h>
#include <stdint.h>
#include <stdlib.h>
#include "version.h"
/**
* Load a Wasm Module from disk.
*
* All successfully loaded Wasm modules are stored in a `HashMap`.
* This implies that:
* - The `path` (also used as module's id) must point to an existing file.
* - The file pointed by `path` must be a valid .wasm module.
*
* In case of error, the reason is printed to stderr and returns -1.
* Otherwise, it returns 0.
*
* Due to String management differences between C and Rust, this function uses `unsafe {}` code.
* So `path` must be a valid pointer to a null-terminated C char array. Otherwise, code might panic.
* In addition, `path` must contain valid ASCII chars that can be converted into UTF-8 encoding.
*
* # Examples (C Code)
*
* ```
* wasm_module_load("/var/www/wasm/python3_11.wasm");
* wasm_module_load("/var/www/wasm/php8.wasm");
* ```
*/
int wasm_module_load(const char *path);
/**
* Creates a new Wasm Config given an identifier.
* The identifier must be unique.
*
* In case of error, the reason is printed to stderr and returns -1.
* Otherwise, it returns 0.
*
* Due to String management differences between C and Rust, this function uses `unsafe {}` code.
* So `config_id` must be a valid pointer to a null-terminated C char array. Otherwise, code might panic.
* In addition, `config_id` must contain valid ASCII chars that can be converted into UTF-8 encoding.
*
* # Examples (C Code)
*
* ```
* wasm_config_create("Drupal");
* wasm_config_create("WordPress");
* ```
*/
int wasm_config_create(const char *config_id);
/**
* Set a loaded Wasm Module to an existing Wasm Config.
*
* In case of error, the reason is printed to stderr and returns -1.
* Otherwise, it returns 0.
*
* Due to String management differences between C and Rust, this function uses `unsafe {}` code.
* So `config_id` and `module_id` must be a valid pointer to a null-terminated C char array. Otherwise, code might panic.
* In addition, `config_id` and `module_id` must contain valid ASCII chars that can be converted into UTF-8 encoding.
*
* # Examples (C Code)
*
* ```
* wasm_config_module_set("Drupal", "/var/www/php8.wasm");
* wasm_config_module_set("WordPress", "/var/www/php8.wasm");
* ```
*/
int wasm_config_module_set(const char *config_id,
const char *module_id);
/**
* Add a WASI argument for the given Wasm config
*
* Wasm config must have been previously created.
*
* In case of error, the reason is printed to stderr and returns -1.
* Otherwise, it returns 0.
*
* Due to String management differences between C and Rust, this function uses `unsafe {}` code.
* So `config_id` and `arg` must be a valid pointer to a null-terminated C char array. Otherwise, code might panic.
* In addition, `config_id` and `arg` must contain valid ASCII chars that can be converted into UTF-8 encoding.
*
* # Examples (C Code)
*
* ```
* wasm_config_arg_add("config_id", "--help");
* ```
*/
int wasm_config_arg_add(const char *config_id,
const char *arg);
/**
* Add a WASI environment variable for the given Wasm config
*
* Wasm config must have been previously created.
*
* In case of error, the reason is printed to stderr and returns -1.
* Otherwise, it returns 0.
*
* Due to String management differences between C and Rust, this function uses `unsafe {}` code.
* So `config_id`, `env` and `value` must be a valid pointer to a null-terminated C char array. Otherwise, code might panic.
* In addition, `config_id`, `env` and `value` must contain valid ASCII chars that can be converted into UTF-8 encoding.
*
* # Examples (C Code)
*
* ```
* wasm_config_env_add("config_id", "TMP", "/tmp");
* ```
*/
int wasm_config_env_add(const char *config_id,
const char *env,
const char *value);
/**
* Add a WASI preopen dir for the Wasm module
*
* In case of error, the reason is printed to stderr and returns -1.
* Otherwise, it returns 0.
*
* Due to String management differences between C and Rust, this function uses `unsafe {}` code.
* So `config_id` and `dir` must be a valid pointer to a null-terminated C char array. Otherwise, code might panic.
* In addition, `config_id` and `dir` must contain valid ASCII chars that can be converted into UTF-8 encoding.
*
* # Examples (C Code)
*
* ```
* wasm_config_dir_add("config_id", "/tmp");
* ```
*/
int wasm_config_dir_add(const char *config_id,
const char *dir);
/**
* Add a WASI preopen dir with mapping for the Wasm module
*
* In case of error, the reason is printed to stderr and returns -1.
* Otherwise, it returns 0.
*
* Due to String management differences between C and Rust, this function uses `unsafe {}` code.
* So `config_id`, `map` and `dir` must be a valid pointer to a null-terminated C char array. Otherwise, code might panic.
* In addition, `config_id`, `map` and `dir` must contain valid ASCII chars that can be converted into UTF-8 encoding.
*
* # Examples (C Code)
*
* ```
* wasm_config_mapdir_add("config_id", "./", ".");
* wasm_config_mapdir_add("config_id", "/wasmhome", "/home/wasm_user");
* wasm_config_mapdir_add("config_id", "/wasmlogs", "/var/log");
* ```
*/
int wasm_config_mapdir_add(const char *config_id,
const char *map,
const char *dir);
/**
* Returns a mapped version of the provided path, based on the current mapdirs
*
* In case no path is found, it returns null
*
* Due to String management differences between C and Rust, this function uses `unsafe {}` code.
* So `config_id` and `path` must be a valid pointer to a null-terminated C char array. Otherwise, code might panic.
* In addition, `config_id` and `path` must contain valid ASCII chars that can be converted into UTF-8 encoding.
*
* # Examples (C Code)
*
* ```
* wasm_config_get_mapped_path("config_id", "/usr/local/apache2");
* wasm_config_get_mapped_path("config_id", "c:/app/apache2/htdocs/info.php");
* ```
*/
const char *wasm_config_get_mapped_path(const char *config_id,
const char *path);
/**
* Creates a new Wasm Execution Context for the given Wasm Config identifier.
*
* Returns a C string (const *char) with the new generated Wasm Execution Context ID.
* Otherwise, trace the error and returns a string explaining the error.
*
* Due to String management differences between C and Rust, this function uses `unsafe {}` code.
* So `config_id` must be a valid pointer to a null-terminated C char array. Otherwise, code might panic.
* In addition, `config_id` must contain valid ASCII chars that can be converted into UTF-8 encoding.
*
* Finally, the execution context itself and the returned C string's containing the execution contex are owned by Rust.
* So, in order to avoid leaking memory, C world must invoke `wasm_executionctx_deallocate()` and `wasm_return_const_char_ownership()`
* when the execution context and its ID are not needed anymore.
*
* # Examples (C Code)
*
* ```
* const char* exec_ctx_id = wasm_executionctx_create_from_config("WordPress");
* ...
* // do some work with `exec_ctx_id`
* ...
* wasm_executionctx_deallocate(exec_ctx_id);
* wasm_return_const_char_ownership(exec_ctx_id);
* ```
*/
const char *wasm_executionctx_create_from_config(const char *config_id);
/**
* Deallocates the given Wasm execution context
*
* Wasm execution context must have been previously created.
*
* In case of error, the reason is printed to stderr and returns -1.
* Otherwise, it returns 0.
*
* Due to String management differences between C and Rust, this function uses `unsafe {}` code.
* So `executionctx_id` must be a valid pointer to a null-terminated C char array. Otherwise, code might panic.
* In addition, `executionctx_id` must contain valid ASCII chars that can be converted into UTF-8 encoding.
*
* # Examples (C Code)
*
* ```
* wasm_executionctx_deallocate("12AB34DC");
* ```
*/
int wasm_executionctx_deallocate(const char *executionctx_id);
/**
* Add a WASI environment variable for the given Wasm execution context
*
* Wasm execution context must have been previously created.
*
* In case of error, the reason is printed to stderr and returns -1.
* Otherwise, it returns 0.
*
* Due to String management differences between C and Rust, this function uses `unsafe {}` code.
* So `executionctx_id`, `env` and `value` must be a valid pointer to a null-terminated C char array. Otherwise, code might panic.
* In addition, `executionctx_id`, `env` and `value` must contain valid ASCII chars that can be converted into UTF-8 encoding.
*
* # Examples (C Code)
*
* ```
* wasm_executionctx_env_add("12AB34DC", "TMP", "/tmp");
* ```
*/
int wasm_executionctx_env_add(const char *executionctx_id,
const char *env,
const char *value);
/**
* Set the WASI stdin for the given Wasm execution context
*
* Wasm execution context must have been previously created.
*
* In case of error, the reason is printed to stderr and returns -1.
* Otherwise, it returns 0.
*
* Due to String management differences between C and Rust, this function uses `unsafe {}` code.
* So `executionctx_id` must be a valid pointer to a null-terminated C char array. Otherwise, code might panic.
* In addition, `executionctx_id` must contain valid ASCII chars that can be converted into UTF-8 encoding.
* Finally, this funcion can fail if data within the `buffer` is not well aligned or not in sync with `size`.
*
* # Examples (C Code)
*
* ```
* wasm_executionctx_stdin_set("12AB34DC", buffer, buffer_size);
* ```
*/
int wasm_executionctx_stdin_set(const char *executionctx_id,
const unsigned char *buffer,
uintptr_t buffer_size);
/**
* Run the given Wasm execution context
*
* In case of error, the reason is printed to stderr and returns -1.
* Otherwise, it returns 0.
*
* Parameters:
*
* - `executionctx_id`: Wasm execution context ID. It must have been previously created.
* - `_buffer`: It's an out-only parameter that represents a C `const char**`. Empty when calling the function.
* On output, it points to the Wasm execution context output.
* - `_len`: It's an out-only parameter that represents a C `unsigned long int*`. On output, it contains the buffer length.
*
* Due to String management differences between C and Rust, this function uses `unsafe {}` code.
* So `executionctx_id` must be a valid pointer to a null-terminated C char array. Otherwise, code might panic.
* In addition, `executionctx_id` must contain valid ASCII chars that can be converted into UTF-8 encoding.
*
* The returned `_buffer` can contain more than one NULL terminator ('\0) character (ie. binary files as .png images).
*
* Finally, the memory returned in `_buffer` containing the Wasm module stdout is owned by Rust.
* So, in order to avoid leaking memory, C world must invoke `wasm_return_const_char_ownership()`
* when the Wasm module stdout is not needed anymore.
*
* # Examples (C Code)
*
* ```
* const char* module_output = wasm_executionctx_run("12AB34DC");
* ...
* // do some work with `module_output`
* ...
* wasm_return_const_char_ownership(module_output);
* ```
*/
int wasm_executionctx_run(const char *executionctx_id,
const char **_buffer,
unsigned long *_len);
/**
* Returns raw pointer's ownership
*
* After returning a const *char pointer from Rust-world to the C-world, when such a pointer is not going to be used any more,
* C-world MUST invoke this function in order to Rust-world being able to deallocate the memory.
* Otherwise, memory will leak.
*
*/
void wasm_return_const_char_ownership(const char *ptr);