Here we describe how Crubit maps pointer and reference types.
Rust bindings for lifetime-annotated C++ pointers and references look as follows:
| C++ API | Rust bindings |
|---|---|
const T& $a | &'a T |
T& $a | &'a mut T |
const T* $a | Option<&'a T> |
T* $a | Option<&'a mut T> |
TODO: Document how explicit lifetime annotations work. (A prerequisite might be defining $a macros via a new header under crubit/support.)
TODO: Document how #pragma clang lifetime_elision works.
C++ pointers and references that are not annotated with lifetimes look as follows:
| C++ API | Rust bindings |
|---|---|
const T& | *const T |
T& | *mut T |
const T* | *const T |
T* | *mut T |
TODO: Document what happens for void*.
Rust bindings for lifetime-annotated C++ pointers look as follows:
| Rust API | C++ bindings |
|---|---|
*const T | const T* |
*mut T | T* |
When used as function parameter types or function return types, Rust references map into the corresponding C++ types as follows:
| Rust API | C++ bindings |
|---|---|
&'a T | const std::int32_t & [[clang::annotate_type("lifetime", "a")]] |
&'a mut T | std::int32_t & [[clang::annotate_type("lifetime", "a")]] |
&str | TODO(b/262580415): Not supported yet. |
&mut str | TODO(b/262580415): Not supported yet. |
&[T] | TODO(b/271016831): Not supported yet. |
&mut[T] | TODO(b/271016831): Not supported yet. |
TODO(b/286299326): Use shorter $a syntax in the generated C++.
TODO(b/279913786): Generate ABSL_ATTRIBUTE_LIFETIME_BOUND when appropriate.
TODO(b/286256327): Support Rust references in fields and nested types.
Rust reference documents Undefined Behavior (UB) and says that “it is the programmer's responsibility when writing unsafe code to ensure that any safe code interacting with the unsafe code cannot trigger these [undefined] behaviors”. A programmer using Crubit bindings has the same responsibility: Crubit is implicitly “unsafe”, and incorrect usage can cause UB. The sections below document requirements for safely using Crubit when working with Rust and C++ references and pointers. The requirements are the same as the ones documented in the Rust reference, but are rephrased below from Crubit perspective.
The safety requirements below focus on avoiding UB related to Rust references and therefore matter in scenarios where Crubit-generated code may create Rust references out of C++ references or C++ pointers:
CppRef<T> in the generated bindings (and this should mitigate some of the memory safety concerns).&T.Incorrect lifetime annotations may lead to UB. Rust‘s borrow checker prevents incorrect lifetime annotations, but lifetime annotations of C++ APIs are not verified by the C++ compiler and Crubit’s optional lifetime analysis can't detect all incorrect annotations. Note that Crubit assumes that lifetime annotations are correct both for explicit annotations (e.g. int& $a f2(int& $a);) as well as for annotations provided by #pragma clang lifetime_elision.
Mutating a value in C++ may lead to UB if the mutation happens while Rust holds a references to that value. This applies to Rust shared references (e.g. &T) and to exclusive references (e.g. &mut T).
Examples of C++ features that may mutate a value that Rust holds a reference to:
TODO: Try to succintly mention the idea that short-lived / non-retained references are safe from the mutation risk.
All references and NonNull pointers must not be null, and if they point to a nonzero span of memory, must not be dangling. (The behavior of a program which violates these rules is undefined.)
C++ doesn't share these rules, and care must be taken when converting Rust references to and from C++ pointers. For example, spans/slices are particularly error-prone: a Rust empty slice uses a dangling pointer (which produces UB in C++ when used in pointer arithmetic), and a C++ empty span (often) uses nullptr (which is UB in Rust). To effectively use spans in FFI, one must either use non-native types, or perform a conversion operation which rewrites the pointer values. For that, we recommend using the conversion routines provided by Crubit support library (e.g. impl From<string_view> for &[u8]).
TODO(b/271016831, b/262580415): Cover rs_std::Slice<T> and/or rs_std::str above once these types are provided by Crubit.
Constructing a Rust references that aliases the same address as an already existing exclusive reference &mut T may lead to UB.
TODO: Provide FFI-related examples.
TODO: Document what runtime checks are provided by Crubit (and link to a separate md document that explains why general checks are infeasible).