Update Rust docs page (#7296)
I think these changes reflect the current state, but I found it hard to
track the state of some of the planned work. Hence why it'd be good to
have it documented :)
I also expanded some sections that I found misleading, as somebody
familiar with Rust and FlatBuffers separately. Parts of these pages seem
to be aimed at people familiar with FlatBuffers (ie via the other
documentation pages) but not each language, which I'm trying to
preserve. However, Rust does some things differently, and as somebody
with expectations about how typical Rust APIs work the discussion of
threading made me wonder what was different.
diff --git a/docs/source/RustUsage.md b/docs/source/RustUsage.md
index 9e959a9..2a16258 100644
--- a/docs/source/RustUsage.md
+++ b/docs/source/RustUsage.md
@@ -58,7 +58,7 @@
For example, here is how you would read a FlatBuffer binary file in Rust:
First, include the library and generated code. Then read the file into
-a `u8` vector, which you pass, as a byte slice, to `get_root_as_monster()`.
+a `u8` vector, which you pass, as a byte slice, to `root_as_monster()`.
This full example program is available in the Rust test suite:
[monster_example.rs](https://github.com/google/flatbuffers/blob/master/tests/rust_usage_test/bin/monster_example.rs)
@@ -80,7 +80,7 @@
let mut buf = Vec::new();
f.read_to_end(&mut buf).expect("file reading failed");
- let monster = my_game::example::get_root_as_monster(&buf[..]);
+ let monster = my_game::example::root_as_monster(&buf[..]);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
`monster` is of type `Monster`, and points to somewhere *inside* your
@@ -108,7 +108,7 @@
For structs, layout is deterministic and guaranteed to be the same
across platforms (scalars are aligned to their
own size, and structs themselves to their largest member), and you
-are allowed to access this memory directly by using `safe_slice` and
+are allowed to access this memory directly by using `safe_slice`
on the reference to a struct, or even an array of structs.
To compute offsets to sub-elements of a struct, make sure they
@@ -118,9 +118,10 @@
in OpenGL or similar APIs.
It is important to note is that structs are still little endian on all
-machines, so only use tricks like this if you can guarantee you're not
-shipping on a big endian machine (using an `#[cfg(target_endian = "little")]`
-attribute would be wise).
+machines, so the functions to enable tricks like this are only exposed on little
+endian machines. If you also ship on big endian machines, using an
+`#[cfg(target_endian = "little")]` attribute would be wise or your code will not
+compile.
The special function `safe_slice` is implemented on Vector objects that are
represented in memory the same way as they are represented on the wire. This
@@ -134,22 +135,22 @@
## Access of untrusted buffers
+The safe Rust functions to interpret a slice as a table (`root`,
+`size_prefixed_root`, `root_with_opts`, and `size_prefixed_root_with_opts`)
+verify the data first. This has some performance cost, but is intended to be
+safe for use on flatbuffers from untrusted sources. There are corresponding
+`unsafe` versions with names ending in `_unchecked` which skip this
+verification, and may access arbitrary memory.
+
The generated accessor functions access fields over offsets, which is
-very quick. These offsets are used to index into Rust slices, so they are
-bounds-checked by the Rust runtime. However, our Rust implementation may
-change: we may convert access functions to use direct pointer dereferencing, to
-improve lookup speed. As a result, users should not rely on the aforementioned
-bounds-checking behavior.
+very quick. The current implementation uses these to access memory without any
+further bounds checking. All of the safe Rust APIs ensure the verifier is run
+over these flatbuffers before accessing them.
When you're processing large amounts of data from a source you know (e.g.
-your own generated data on disk), this is acceptable, but when reading
-data from the network that can potentially have been modified by an
-attacker, this is undesirable.
-
-The C++ port provides a buffer verifier. At this time, Rust does not. Rust may
-provide a verifier in a future version. In the meantime, Rust users can access
-the buffer verifier generated by the C++ port through a foreign function
-interface (FFI).
+your own generated data on disk), the `_unchecked` versions are acceptable, but
+when reading data from the network that can potentially have been modified by an
+attacker, it is desirable to use the safe versions which use the verifier.
## Threading
@@ -165,6 +166,17 @@
accomplish this, by design, as we feel multithreaded construction
of a single buffer will be rare, and synchronisation overhead would be costly.
+Unlike most other languages, in Rust these properties are exposed to and
+enforced by the type system. `flatbuffers::Table` and the generated table types
+are `Send + Sync`, indicating they may be freely shared across threads and data
+may be accessed from any thread which receives a const (aka shared) reference.
+There are no functions which require a mutable (aka exclusive) reference, which
+means all the available functions may be called like this.
+`flatbuffers::FlatBufferBuilder` is also `Send + Sync`, but all of the mutating
+functions require a mutable (aka exclusive) reference which can only be created
+when no other references to the `FlatBufferBuilder` exist, and may not be copied
+within the same thread, let alone to a second thread.
+
## Useful tools created by others
* [flatc-rust](https://github.com/frol/flatc-rust) - FlatBuffers compiler
