1 /** 2 * \mainpage Wasmtime C API 3 * 4 * This documentation is an overview and API reference for the C API of 5 * Wasmtime. The C API is spread between three different header files: 6 * 7 * * \ref wasmtime.h 8 * * \ref wasi.h 9 * * \ref wasm.h 10 * 11 * The \ref wasmtime.h header file includes all the other header files and is 12 * the main header file you'll likely be using. The \ref wasm.h header file 13 * comes directly from the 14 * [WebAssembly/wasm-c-api](https://github.com/WebAssembly/wasm-c-api) 15 * repository, and at this time the upstream header file does not have 16 * documentation so Wasmtime provides documentation here. It should be noted 17 * some semantics may be Wasmtime-specific and may not be portable to other 18 * engines. 19 * 20 * ## Installing the C API 21 * 22 * To install the C API from precompiled binaries you can download the 23 * appropriate binary from the [releases page of 24 * Wasmtime](https://github.com/bytecodealliance/wasmtime/releases). Artifacts 25 * for the C API all end in "-c-api" for the filename. 26 * 27 * Each archive contains an `include` directory with necessary headers, as well 28 * as a `lib` directory with both a static archive and a dynamic library of 29 * Wasmtime. You can link to either of them as you see fit. 30 * 31 * ## Linking against the C API 32 * 33 * You'll want to arrange the `include` directory of the C API to be in your 34 * compiler's header path (e.g. the `-I` flag). If you're compiling for Windows 35 * and you're using the static library then you'll also need to pass 36 * `-DWASM_API_EXTERN=` and `-DWASI_API_EXTERN=` to disable dllimport. 37 * 38 * Your final artifact can then be linked with `-lwasmtime`. If you're linking 39 * against the static library you may need to pass other system libraries 40 * depending on your platform: 41 * 42 * * Linux - `-lpthread -ldl -lm` 43 * * macOS - no extra flags needed 44 * * Windows - `ws2_32.lib advapi32.lib userenv.lib ntdll.lib shell32.lib ole32.lib` 45 * 46 * ## Building from Source 47 * 48 * The C API is located in the 49 * [`crates/c-api`](https://github.com/bytecodealliance/wasmtime/tree/main/crates/c-api) 50 * directory of the [Wasmtime 51 * repository](https://github.com/bytecodealliance/wasmtime). To build from 52 * source you'll need a Rust compiler and a checkout of the `wasmtime` project. 53 * Afterwards you can execute: 54 * 55 * ``` 56 * $ cargo build --release -p wasmtime-c-api 57 * ``` 58 * 59 * This will place the final artifacts in `target/release`, with names depending 60 * on what platform you're compiling for. 61 * 62 * ## Other resources 63 * 64 * Some other handy resources you might find useful when exploring the C API 65 * documentation are: 66 * 67 * * [Rust `wasmtime` crate 68 * documentation](https://bytecodealliance.github.io/wasmtime/api/wasmtime/) - 69 * although this documentation is for Rust and not C, you'll find that many 70 * functions mirror one another and there may be extra documentation in Rust 71 * you find helpful. If you find yourself having to frequently do this, 72 * though, please feel free to [file an 73 * issue](https://github.com/bytecodealliance/wasmtime/issues/new). 74 * 75 * * [C embedding 76 * examples](https://bytecodealliance.github.io/wasmtime/examples-c-embed.html) 77 * are available online and are tested from the Wasmtime repository itself. 78 * 79 * * [Contribution documentation for 80 * Wasmtime](https://bytecodealliance.github.io/wasmtime/contributing.html) in 81 * case you're interested in helping out! 82 */ 83 84 /** 85 * \file wasmtime.h 86 * 87 * \brief Wasmtime's C API 88 * 89 * This file is the central inclusion point for Wasmtime's C API. There are a 90 * number of sub-header files but this file includes them all. The C API is 91 * based on \ref wasm.h but there are many Wasmtime-specific APIs which are 92 * tailored to Wasmtime's implementation. 93 * 94 * The #wasm_config_t and #wasm_engine_t types are used from \ref wasm.h. 95 * Additionally all type-level information (like #wasm_functype_t) is also 96 * used from \ref wasm.h. Otherwise, though, all wasm objects (like 97 * #wasmtime_store_t or #wasmtime_func_t) are used from this header file. 98 * 99 * ### Thread Safety 100 * 101 * The multithreading story of the C API very closely follows the 102 * multithreading story of the Rust API for Wasmtime. All objects are safe to 103 * send to other threads so long as user-specific data is also safe to send to 104 * other threads. Functions are safe to call from any thread but some functions 105 * cannot be called concurrently. For example, functions which correspond to 106 * `&T` in Rust can be called concurrently with any other methods that take 107 * `&T`. Functions that take `&mut T` in Rust, however, cannot be called 108 * concurrently with any other function (but can still be invoked on any 109 * thread). 110 * 111 * This generally equates to mutation of internal state. Functions which don't 112 * mutate anything, such as learning type information through 113 * #wasmtime_func_type, can be called concurrently. Functions which do require 114 * mutation, for example #wasmtime_func_call, cannot be called concurrently. 115 * This is conveyed in the C API with either `const wasmtime_context_t*` 116 * (concurrency is ok as it's read-only) or `wasmtime_context_t*` (concurrency 117 * is not ok, mutation may happen). 118 * 119 * When in doubt assume that functions cannot be called concurrently with 120 * aliasing objects. 121 * 122 * ### Aliasing 123 * 124 * The C API for Wasmtime is intended to be a relatively thin layer over the 125 * Rust API for Wasmtime. Rust has much more strict rules about aliasing than C 126 * does, and the Rust API for Wasmtime is designed around these rules to be 127 * used safely. These same rules must be upheld when using the C API of 128 * Wasmtime. 129 * 130 * The main consequence of this is that the #wasmtime_context_t pointer into 131 * the #wasmtime_store_t must be carefully used. Since the context is an 132 * internal pointer into the store it must be used carefully to ensure you're 133 * not doing something that Rust would otherwise forbid at compile time. A 134 * #wasmtime_context_t can only be used when you would otherwise have been 135 * provided access to it. For example in a host function created with 136 * #wasmtime_func_new you can use #wasmtime_context_t in the host function 137 * callback. This is because an argument, a #wasmtime_caller_t, provides access 138 * to #wasmtime_context_t. On the other hand a destructor passed to 139 * #wasmtime_externref_new, however, cannot use a #wasmtime_context_t because 140 * it was not provided access to one. Doing so may lead to memory unsafety. 141 * 142 * ### Stores 143 * 144 * A foundational construct in this API is the #wasmtime_store_t. A store is a 145 * collection of host-provided objects and instantiated wasm modules. Stores are 146 * often treated as a "single unit" and items within a store are all allowed to 147 * reference one another. References across stores cannot currently be created. 148 * For example you cannot pass a function from one store into another store. 149 * 150 * A store is not intended to be a global long-lived object. Stores provide no 151 * means of internal garbage collections of wasm objects (such as instances), 152 * meaning that no memory from a store will be deallocated until you call 153 * #wasmtime_store_delete. If you're working with a web server, for example, 154 * then it's recommended to think of a store as a "one per request" sort of 155 * construct. Globally you'd have one #wasm_engine_t and a cache of 156 * #wasmtime_module_t instances compiled into that engine. Each request would 157 * create a new #wasmtime_store_t and then instantiate a #wasmtime_module_t 158 * into the store. This process of creating a store and instantiating a module 159 * is expected to be quite fast. When the request is finished you'd delete the 160 * #wasmtime_store_t keeping memory usage reasonable for the lifetime of the 161 * server. 162 */ 163 164 #ifndef WASMTIME_API_H 165 #define WASMTIME_API_H 166 167 #include <wasi.h> 168 #include <wasmtime/config.h> 169 #include <wasmtime/error.h> 170 #include <wasmtime/engine.h> 171 #include <wasmtime/extern.h> 172 #include <wasmtime/func.h> 173 #include <wasmtime/global.h> 174 #include <wasmtime/instance.h> 175 #include <wasmtime/linker.h> 176 #include <wasmtime/memory.h> 177 #include <wasmtime/module.h> 178 #include <wasmtime/store.h> 179 #include <wasmtime/table.h> 180 #include <wasmtime/trap.h> 181 #include <wasmtime/val.h> 182 183 #ifdef __cplusplus 184 extern "C" { 185 #endif 186 187 /** 188 * \brief Converts from the text format of WebAssembly to to the binary format. 189 * 190 * \param wat this it the input pointer with the WebAssembly Text Format inside of 191 * it. This will be parsed and converted to the binary format. 192 * \param wat_len this it the length of `wat`, in bytes. 193 * \param ret if the conversion is successful, this byte vector is filled in with 194 * the WebAssembly binary format. 195 * 196 * \return a non-null error if parsing fails, or returns `NULL`. If parsing 197 * fails then `ret` isn't touched. 198 * 199 * This function does not take ownership of `wat`, and the caller is expected to 200 * deallocate the returned #wasmtime_error_t and #wasm_byte_vec_t. 201 */ 202 WASM_API_EXTERN wasmtime_error_t* wasmtime_wat2wasm( 203 const char *wat, 204 size_t wat_len, 205 wasm_byte_vec_t *ret 206 ); 207 208 #ifdef __cplusplus 209 } // extern "C" 210 #endif 211 212 #endif // WASMTIME_API_H 213