[docs] Add C++ chapter and missing examples (#11569)

* [docs] Add C++ chapter and missing examples

This adds a chapter for C++ embedding. The chapter intro is rudimentary, but there are a bunch more examples now: I added C++ ports for everything that already had both a Rust and a C version available, matching the Rust version's behavior where applicable.

* [example] Fix paths in `examples/wasip1/main.c`

* [docs] Add entries for additional Rust and C embedding examples

These examples already existed, but didn't have entries in the docs.

It'll probably make sense to restructure all of this at some point and move the examples into language-specific folders.

* [docs] Remove references to Conan packages from README.md

These packages haven't been updated since Wasmtime 18, so we shouldn't link to them for now.

* Format cpp files

* Format even more cpp files

* Fix some warnings in C++ headers

* Simplify threads.cc example

* Update docs/examples-c-serialize.md

Co-authored-by: Nick Fitzgerald <fitzgen@gmail.com>

* [example] Don't try, do.

* [docs] Restore CMake link in README

* [docs] Improve examples/README.md

* [docs] Address review feedback

---------

Co-authored-by: Alex Crichton <alex@alexcrichton.com>
Co-authored-by: Nick Fitzgerald <fitzgen@gmail.com>

Author: 3 people

README.md

@@ -139,8 +139,8 @@ the implementation.
 Languages supported by the Bytecode Alliance:
 
 * **[Rust]** - the [`wasmtime` crate]
-* **[C]** - the [`wasm.h`, `wasi.h`, and `wasmtime.h` headers][c-headers], [CMake](crates/c-api/CMakeLists.txt) or [`wasmtime` Conan package]
-* **C++** - the [`wasmtime.hh` header][c-headers] or the [`wasmtime-cpp` Conan package]
+* **[C]** - the [`wasm.h`, `wasi.h`, and `wasmtime.h` headers][c-headers], [CMake](crates/c-api/CMakeLists.txt)
+* **C++** - the [`wasmtime.hh` header][c-headers]
 * **[Python]** - the [`wasmtime` PyPI package]
 * **[.NET]** - the [`Wasmtime` NuGet package]
 * **[Go]** - the [`wasmtime-go` repository]
@@ -161,8 +161,6 @@ Languages supported by the community:
 [`Wasmtime` NuGet package]: https://www.nuget.org/packages/Wasmtime
 [Go]: https://bytecodealliance.github.io/wasmtime/lang-go.html
 [`wasmtime-go` repository]: https://pkg.go.dev/github.com/bytecodealliance/wasmtime-go
-[`wasmtime` Conan package]: https://conan.io/center/wasmtime
-[`wasmtime-cpp` Conan package]: https://conan.io/center/wasmtime-cpp
 [Ruby]: https://bytecodealliance.github.io/wasmtime/lang-ruby.html
 [`wasmtime` gem]: https://rubygems.org/gems/wasmtime
 [Elixir]: https://docs.wasmtime.dev/lang-elixir.html

crates/c-api/include/wasmtime.hh

@@ -19,8 +19,13 @@
  * \example gcd.cc
  * \example linking.cc
  * \example memory.cc
+ * \example multimemory.cc
  * \example interrupt.cc
+ * \example multi.cc
+ * \example anyref.cc
  * \example externref.cc
+ * \example serialize.cc
+ * \example threads.cc
  */
 
 /**

crates/c-api/include/wasmtime/func.hh

@@ -63,9 +63,11 @@ template <typename T> struct WasmType {
     static const ValKind kind = ValKind::valkind;                              \
     static void store(Store::Context cx, wasmtime_val_raw_t *p,                \
                       const native &t) {                                       \
+      (void)cx;                                                                \
       p->field = t;                                                            \
     }                                                                          \
     static native load(Store::Context cx, wasmtime_val_raw_t *p) {             \
+      (void)cx;                                                                \
       return p->field;                                                         \
     }                                                                          \
   };
@@ -108,9 +110,13 @@ template <> struct WasmType<V128> {
   static const bool valid = true;
   static const ValKind kind = ValKind::V128;
   static void store(Store::Context cx, wasmtime_val_raw_t *p, const V128 &t) {
+    (void)cx;
     memcpy(&p->v128[0], &t.v128[0], sizeof(wasmtime_v128));
   }
-  static V128 load(Store::Context cx, wasmtime_val_raw_t *p) { return p->v128; }
+  static V128 load(Store::Context cx, wasmtime_val_raw_t *p) {
+    (void)cx;
+    return p->v128;
+  }
 };
 
 /// A "trait" for a list of types and operations on them, used for `Func::wrap`
@@ -139,8 +145,14 @@ template <> struct WasmTypeList<std::monostate> {
   static const size_t size = 0;
   static bool matches(ValType::ListRef types) { return types.size() == 0; }
   static void store(Store::Context cx, wasmtime_val_raw_t *storage,
-                    const std::monostate &t) {}
+                    const std::monostate &t) {
+    (void)cx;
+    (void)storage;
+    (void)t;
+  }
   static std::monostate load(Store::Context cx, wasmtime_val_raw_t *storage) {
+    (void)cx;
+    (void)storage;
     return std::monostate();
   }
   static std::vector<ValType> types() { return {}; }
@@ -167,8 +179,8 @@ template <typename... T> struct WasmTypeList<std::tuple<T...>> {
         t);
   }
   static std::tuple<T...> load(Store::Context cx, wasmtime_val_raw_t *storage) {
-    size_t n = 0;
-    return std::tuple<T...>{WasmType<T>::load(cx, &storage[n++])...}; // NOLINT
+    (void)cx;
+    return std::tuple<T...>{WasmType<T>::load(cx, storage++)...}; // NOLINT
   }
   static std::vector<ValType> types() { return {WasmType<T>::kind...}; }
 };
@@ -195,6 +207,8 @@ template <> struct WasmHostRet<void> {
   template <typename F, typename... A>
   static std::optional<Trap> invoke(F f, Caller cx, wasmtime_val_raw_t *raw,
                                     A... args) {
+    (void)cx;
+    (void)raw;
     f(args...);
     return std::nullopt;
   }
@@ -331,6 +345,7 @@ class Func {
   raw_callback_unchecked(void *env, wasmtime_caller_t *caller,
                          wasmtime_val_raw_t *args_and_results,
                          size_t nargs_and_results) {
+    (void)nargs_and_results;
     using HostFunc = WasmHostFunc<F>;
     Caller cx(caller);
     F *func = reinterpret_cast<F *>(env); // NOLINT

crates/c-api/include/wasmtime/global.hh

@@ -61,7 +61,7 @@ public:
   Val get(Store::Context cx) const {
     Val val;
     wasmtime_global_get(cx.ptr, &global, &val.val);
-    return std::move(val);
+    return val;
   }
 
   /// Sets this global to a new value.

docs/SUMMARY.md

@@ -11,19 +11,43 @@
     - [Hello, world!](./examples-rust-hello-world.md)
     - [Calculating the GCD](./examples-rust-gcd.md)
     - [Using Linear Memory](./examples-rust-memory.md)
-    - [WASI](./examples-rust-wasi.md)
+    - [WASIp2](./examples-rust-wasip2.md)
     - [Linking Modules](./examples-rust-linking.md)
     - [Debugging](./examples-rust-debugging.md)
     - [Core Dumps](./examples-rust-core-dumps.md)
     - [Using Multi-Value](./examples-rust-multi-value.md)
+    - [`anyref` Reference Type](./examples-rust-anyref.md)
+    - [`externref` Reference Type](./examples-rust-externref.md)
+    - [Multiple Memories](./examples-rust-multimemory.md)
+    - [Serializing Modules](./examples-rust-serialize.md)
+    - [Multithreaded Embedding](./examples-rust-multithreaded-embedding.md)
+    - [Memory Protection Keys](./examples-rust-mpk.md)
   - [C](./lang-c.md)
     - [Hello, World!](./examples-c-hello-world.md)
     - [Calculating the GCD](./examples-c-gcd.md)
     - [Using Linear Memory](./examples-c-memory.md)
-    - [WASI](./examples-c-wasi.md)
+    - [WASIp1](./examples-c-wasi.md)
     - [Linking Modules](./examples-c-linking.md)
     - [Debugging](./examples-c-debugging.md)
     - [Using Multi-Value](./examples-c-multi-value.md)
+    - [`anyref` Reference Type](./examples-c-anyref.md)
+    - [`externref` Reference Type](./examples-c-externref.md)
+    - [Multiple Memories](./examples-c-multimemory.md)
+    - [Serializing Modules](./examples-c-serialize.md)
+    - [Multithreaded Embedding](./examples-c-multithreaded-embedding.md)
+  - [C++](./lang-cpp.md)
+    - [Hello, World!](./examples-cpp-hello-world.md)
+    - [Calculating the GCD](./examples-cpp-gcd.md)
+    - [Using Linear Memory](./examples-cpp-memory.md)
+    - [WASIp1](./examples-cpp-wasi.md)
+    - [Linking Modules](./examples-cpp-linking.md)
+    - [Using Multi-Value](./examples-cpp-multi-value.md)
+    - [`anyref` Reference Type](./examples-cpp-anyref.md)
+    - [`externref` Reference Type](./examples-cpp-externref.md)
+    - [Multiple Memories](./examples-cpp-multimemory.md)
+    - [Serializing Modules](./examples-cpp-serialize.md)
+    - [Multithreaded Embedding](./examples-cpp-multithreaded-embedding.md)
+    - [Async Host Functions](./examples-cpp-async.md)
   - [Python](./lang-python.md)
   - [.NET](./lang-dotnet.md)
   - [Go](./lang-go.md)

docs/examples-c-anyref.md

@@ -0,0 +1,20 @@
+# Working with `anyref`
+
+You can also [browse this source code online][code] and clone the wasmtime
+repository to run the example locally.
+
+[code]: https://github.com/bytecodealliance/wasmtime/blob/main/examples/anyref.c
+
+This example demonstrates using `anyref` values.
+
+## `anyref.wat`
+
+```wat
+{{#include ../examples/anyref.wat}}
+```
+
+## `anyref.c`
+
+```c
+{{#include ../examples/anyref.c}}
+```

docs/examples-c-embed.md

@@ -0,0 +1,20 @@
+# Working with `externref`
+
+You can also [browse this source code online][code] and clone the wasmtime
+repository to run the example locally.
+
+[code]: https://github.com/bytecodealliance/wasmtime/blob/main/examples/externref.c
+
+This example shows how to pass opaque host references into and out of WebAssembly using `externref`.
+
+## `externref.wat`
+
+```wat
+{{#include ../examples/externref.wat}}
+```
+
+## `externref.c`
+
+```c
+{{#include ../examples/externref.c}}
+```

docs/examples-c-externref.md

@@ -0,0 +1,20 @@
+# Working with Multiple Memories
+
+You can also [browse this source code online][code] and clone the wasmtime
+repository to run the example locally.
+
+[code]: https://github.com/bytecodealliance/wasmtime/blob/main/examples/multimemory.c
+
+This example demonstrates instantiating and interacting with a module that has multiple linear memories.
+
+## `multimemory.wat`
+
+```wat
+{{#include ../examples/multimemory.wat}}
+```
+
+## `multimemory.c`
+
+```c
+{{#include ../examples/multimemory.c}}
+```

docs/examples-c-multimemory.md

@@ -0,0 +1,20 @@
+# Multithreaded Embedding
+
+You can also [browse this source code online][code] and clone the wasmtime
+repository to run the example locally.
+
+[code]: https://github.com/bytecodealliance/wasmtime/blob/main/examples/threads.c
+
+This example demonstrates using Wasmtime in multithreaded runtimes.
+
+## `threads.wat`
+
+```wat
+{{#include ../examples/threads.wat}}
+```
+
+## `threads.c`
+
+```c
+{{#include ../examples/threads.c}}
+```