Merge pull request #482 from dtolnay/book

Book content

Author: dtolnay

book/book.toml

@@ -16,3 +16,7 @@ cname = "cxx.rs"
 git-repository-url = "https://github.com/dtolnay/cxx"
 playground = { copyable = false }
 print = { enable = false }
+
+[output.html.redirect]
+"binding/index.html" = "../bindings.html"
+"build/index.html" = "../building.html"

book/src/SUMMARY.md

@@ -1,3 +1,35 @@
 # Summary
 
-[Rust ❤️ C++](about.md)
+- [Rust ❤️ C++](index.md)
+
+- [Core concepts](concepts.md)
+
+- [Tutorial](tutorial.md)
+
+- [Other Rust–C++ interop tools](context.md)
+
+- [Multi-language build system options](building.md)
+    - [Cargo](build/cargo.md)
+    - [Bazel](build/bazel.md)
+    - [CMake](build/cmake.md)
+    - [More...](build/other.md)
+
+- [Reference: the bridge module](reference.md)
+    - [extern "Rust"](extern-rust.md)
+    - [extern "C++"](extern-c++.md)
+    - [Shared types](shared.md)
+    - [Attributes](attributes.md)
+    - [Async functions](async.md)
+    - [Error handling](binding/result.md)
+
+- [Reference: built-in bindings](bindings.md)
+    - [String — rust::String](binding/string.md)
+    - [&str — rust::Str](binding/str.md)
+    - [&&#91;T&#93; &mdash; rust::Slice\<const T\>](binding/slice.md)
+    - [CxxString &mdash; std::string](binding/cxxstring.md)
+    - [Box\<T\> &mdash; rust::Box\<T\>](binding/box.md)
+    - [UniquePtr\<T\> &mdash; std::unique\_ptr\<T\>](binding/uniqueptr.md)
+    - [Vec\<T\> &mdash; rust::Vec\<T\>](binding/vec.md)
+    - [CxxVector\<T\> &mdash; std::vector\<T\>](binding/cxxvector.md)
+    - [Function pointers](binding/fn.md)
+    - [Result\<T\>](binding/result.md)

book/src/about.md

@@ -0,0 +1,86 @@
+{{#title Async functions — Rust ♡ C++}}
+# Async functions
+
+Direct FFI of async functions is absolutely in scope for CXX (on C++20 and up)
+but is not implemented yet in the current release. We are aiming for an
+implementation that is as easy as:
+
+```rust,noplayground
+#[cxx::bridge]
+mod ffi {
+    unsafe extern "C++" {
+        async fn doThing(arg: Arg) -> Ret;
+    }
+}
+```
+
+```cpp,hidelines
+rust::Future<Ret> doThing(Arg arg) {
+  auto v1 = co_await f();
+  auto v2 = co_await g(arg);
+  co_return v1 + v2;
+}
+```
+
+## Workaround
+
+For now the recommended approach is to handle the return codepath over a oneshot
+channel (such as [`futures::channel::oneshot`]) represented in an opaque Rust
+type on the FFI.
+
+[`futures::channel::oneshot`]: https://docs.rs/futures/0.3.8/futures/channel/oneshot/index.html
+
+```rust,noplayground
+// bridge.rs
+
+use futures::channel::oneshot;
+
+#[cxx::bridge]
+mod ffi {
+    extern "Rust" {
+        type DoThingContext;
+    }
+
+    unsafe extern "C++" {
+        include!("path/to/bridge_shim.h");
+
+        fn shim_doThing(
+            arg: Arg,
+            done: fn(Box<DoThingContext>, ret: Ret),
+            ctx: Box<DoThingContext>,
+        );
+    }
+}
+
+struct DoThingContext(oneshot::Sender<Ret>);
+
+pub async fn do_thing(arg: Arg) -> Ret {
+    let (tx, rx) = oneshot::channel();
+    let context = Box::new(DoThingContext(tx));
+
+    ffi::shim_doThing(
+        arg,
+        |tx, ret| { let _ = tx.0.send(ret); },
+        context,
+    );
+
+    rx.await.unwrap()
+}
+```
+
+```cpp
+// bridge_shim.cc
+
+#include "path/to/bridge.rs.h"
+#include "rust/cxx.h"
+
+void shim_doThing(
+    Arg arg,
+    rust::Fn<void(rust::Box<DoThingContext> ctx, Ret ret)> done,
+    rust::Box<DoThingContext> ctx) noexcept {
+  doThing(arg)
+      .then([done, ctx(std::move(ctx))](auto &&res) mutable {
+        (*done)(std::move(ctx), std::move(res));
+      });
+}
+```

book/src/async.md

@@ -0,0 +1,74 @@
+{{#title Attributes — Rust ♡ C++}}
+# Attributes
+
+## namespace
+
+The top-level cxx::bridge attribute macro takes an optional `namespace` argument
+to control the C++ namespace into which to emit extern Rust items and the
+namespace in which to expect to find the extern C++ items.
+
+```rust,noplayground
+#[cxx::bridge(namespace = "path::of::my::company")]
+mod ffi {
+    extern "Rust" {
+        type MyType;  // emitted to path::of::my::company::MyType
+    }
+
+    extern "C++" {
+        type TheirType;  // refers to path::of::my::company::TheirType
+    }
+}
+```
+
+Additionally, a `#[namespace = "..."]` attribute may be used inside the bridge
+module on any extern block or individual item. An item will inherit the
+namespace specified on its surrounding extern block if any, otherwise the
+namespace specified with the top level cxx::bridge attribute if any, otherwise
+the global namespace.
+
+```rust,noplayground
+#[cxx::bridge(namespace = "third_priority")]
+mod ffi {
+    #[namespace = "second_priority"]
+    extern "Rust" {
+        fn f();
+
+        #[namespace = "first_priority"]
+        fn g();
+    }
+
+    extern "Rust" {
+        fn h();
+    }
+}
+```
+
+The above would result in functions `::second_priority::f`,
+`::first_priority::g`, `::third_priority::h`.
+
+## rust\_name, cxx\_name
+
+Sometimes you want the Rust name of a function to differ from its C++ name.
+Importantly, this enables binding multiple overloads of the same C++ function
+name using distinct Rust names.
+
+```rust,noplayground
+#[cxx::bridge]
+mod ffi {
+    unsafe extern "C++" {
+        #[rust_name = "i32_overloaded_function"]
+        fn cOverloadedFunction(x: i32) -> String;
+        #[rust_name = "str_overloaded_function"]
+        fn cOverloadedFunction(x: &str) -> String;
+    }
+}
+```
+
+The `#[rust_name = "..."]` attribute replaces the name that Rust should use for
+this function, and an analogous `#[cxx_name = "..."]` attribute replaces the
+name that C++ should use.
+
+Either of the two attributes may be used on extern "Rust" as well as extern
+"C++" functions, according to which one you find clearer in context.
+
+Support for renaming type names and enum variants is not implemented yet.

book/src/attributes.md

@@ -0,0 +1,120 @@
+{{#title rust::Box<T> — Rust ♡ C++}}
+# rust::Box\<T\>
+
+### Public API:
+
+```cpp,hidelines
+// rust/cxx.h
+#
+# #include <type_traits>
+#
+# namespace rust {
+
+template <typename T>
+class Box final {
+public:
+  using value_type = T;
+  using const_pointer =
+      typename std::add_pointer<typename std::add_const<T>::type>::type;
+  using pointer = typename std::add_pointer<T>::type;
+
+  Box(const Box &);
+  Box(Box &&) noexcept;
+  ~Box() noexcept;
+
+  explicit Box(const T &);
+  explicit Box(T &&);
+
+  Box &operator=(const Box &);
+  Box &operator=(Box &&) noexcept;
+
+  const T *operator->() const noexcept;
+  const T &operator*() const noexcept;
+  T *operator->() noexcept;
+  T &operator*() noexcept;
+
+  template <typename... Fields>
+  static Box in_place(Fields &&...);
+
+  // Important: requires that `raw` came from an into_raw call. Do not
+  // pass a pointer from `new` or any other source.
+  static Box from_raw(T *) noexcept;
+
+  T *into_raw() noexcept;
+};
+#
+# } // namespace rust
+```
+
+### Restrictions:
+
+Box\<T\> does not support T being an opaque C++ type. You should use
+[UniquePtr\<T\>](uniqueptr.md) instead for transferring ownership of opaque C++
+types on the language boundary.
+
+If T is an opaque Rust type, the Rust type is required to be [Sized] i.e. size
+known at compile time. In the future we may introduce support for dynamically
+sized opaque Rust types.
+
+[Sized]: https://doc.rust-lang.org/std/marker/trait.Sized.html
+
+## Example
+
+This program uses a Box to pass ownership of some opaque piece of Rust state
+over to C++ and then back to a Rust callback, which is a useful pattern for
+implementing [async functions over FFI](../async.md).
+
+```rust,noplayground
+// src/main.rs
+
+use std::io::Write;
+
+#[cxx::bridge]
+mod ffi {
+    extern "Rust" {
+        type File;
+    }
+
+    unsafe extern "C++" {
+        include!("example/include/example.h");
+
+        fn f(
+            callback: fn(Box<File>, fst: &str, snd: &str),
+            out: Box<File>,
+        );
+    }
+}
+
+pub struct File(std::fs::File);
+
+fn main() {
+    let out = std::fs::File::create("example.log").unwrap();
+
+    ffi::f(
+        |mut out, fst, snd| { let _ = write!(out.0, "{}{}\n", fst, snd); },
+        Box::new(File(out)),
+    );
+}
+```
+
+```cpp
+// include/example.h
+
+#pragma once
+#include "example/src/main.rs.h"
+#include "rust/cxx.h"
+
+void f(rust::Fn<void(rust::Box<File>, rust::Str, rust::Str)> callback,
+       rust::Box<File> out);
+```
+
+```cpp
+// include/example.cc
+
+#include "example/include/example.h"
+
+void f(rust::Fn<void(rust::Box<File>, rust::Str, rust::Str)> callback,
+       rust::Box<File> out) {
+  callback(std::move(out), "fearless", "concurrency");
+}
+```