docs/rust/functions.md

# C++ bindings for Rust functions

C++ code can call functions defined in Rust, provided that the parameter and
return types are supported by Crubit:

*   If a parameter or return type is a
    [fundamental type](../cpp/fundamental_types.md), then the bindings for the
    function use the corresponding Rust type.
*   Similarly, if a parameter or return type is a
    [pointer type](../cpp/pointer_types.md), then the bindings for the function
    use the corresponding Rust pointer type.
*   If the type is a user-defined type, such as a [struct](struct.md) or
    [enum](enums.md), then the bindings for the function use the bindings for
    that type.

As a special case, functions also support reference parameters to supported
types, with some restrictions to ensure safety. See [References](#references).

## Example

Given the following Rust crate:

```live-snippet
cs/file:examples/rust/function/example.rs function:add_two_integers
```

Crubit will generate the following function declaration, which calls into
accompanying glue code:

```live-snippet
cs/file:examples/rust/function/example_generated.h function:add_two_integers
```

## `unsafe` functions

C++ does not have an `unsafe` marker at this time. **In the future**, Crubit may
introduce a way to mark `unsafe` functions to help increase the reliability of
C++ callers.

## References

In general, Rust references are not exposed to C++. However, some Rust functions
which accept reference parameters do get mapped to C++ functions accepting C++
references:

*   All references must have an unbound parameter lifetime – not `'static`, for
    example.
*   Only the parameter itself can be a reference type. References to references,
    vectors of references, etc. are still unsupported.
*   If there is a `mut` reference parameter, it is the **only** reference
    parameter.

This set of rules is intended to describe a safe subset of Rust functions, which
do not introduce substantial aliasing risk to a mixed C++/Rust codebase.

For example, the following Rust functions will receive C++ bindings, and can be
called from C++:

```rust {.good}
fn foo(&self) {}
fn foo(_: &mut i32) {}
fn foo(_: &i32, _: &i32) {}
```

However, none of the below will receive bindings:

```rust {.bad}
fn foo(_: &'static i32) {}  // 'static lifetime is bound
fn foo(_: &&i32) {}  // Reference in non-parameter type
fn foo(_: &mut i32, _: &i32) {}  // More than one reference, one of which is mut
fn foo(_: &'a i32) {}  // 'a is not a lifetime parameter of `foo`
```

Returned references are still not supported, and references which are bound to
some lifetime (e.g. `'static`) are also still not supported.

If you wish to accept more than one reference/pointer in C++, a raw pointer
(`*const T`, `*mut T`) can be used instead. However, all of the usual `unsafe`
caveats apply.