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