[tor-commits] [tor/master] Update the primitive types explanation in the Rust coding standards

[nickm at torproject.org]

commit 01a977b492327f39e7490e9ffbc5a27f15734dc9
Author: teor <teor2345 at gmail.com>
Date:   Tue Feb 27 15:55:13 2018 +1100

    Update the primitive types explanation in the Rust coding standards
    
    Part of #25368.
    Includes c_double in anticipation of #23061.
---
 doc/HACKING/CodingStandardsRust.md | 22 ++++++++++++++++++----
 1 file changed, 18 insertions(+), 4 deletions(-)

diff --git a/doc/HACKING/CodingStandardsRust.md b/doc/HACKING/CodingStandardsRust.md
index d0b17c160..731a7bb85 100644
--- a/doc/HACKING/CodingStandardsRust.md
+++ b/doc/HACKING/CodingStandardsRust.md
@@ -284,12 +284,26 @@ Here are some additional bits of advice and rules:
             }
         }
 
-3. Pass only integer types and bytes over the boundary
+3. Pass only C-compatible primitive types and bytes over the boundary
 
-   The only non-integer type which may cross the FFI boundary is
+   Rust's C-compatible primitive types are integers and floats.
+   These types are declared in the [libc crate](https://doc.rust-lang.org/libc/x86_64-unknown-linux-gnu/libc/index.html#types).
+   Most Rust objects have different [representations](https://doc.rust-lang.org/libc/x86_64-unknown-linux-gnu/libc/index.html#types)
+   in C and Rust, so they can't be passed using FFI.
+
+   Tor currently uses the following Rust primitive types from libc for FFI:
+   * defined-size integers: `uint32_t`
+   * native-sized integers: `c_int`
+   * native-sized floats: `c_double`
+   * native-sized raw pointers: `* c_void`, `* c_char`, `** c_char`
+
+   TODO: C smartlist to Stringlist conversion using FFI
+
+   The only non-primitive type which may cross the FFI boundary is
    bytes, e.g. `&[u8]`.  This SHOULD be done on the Rust side by
-   passing a pointer (`*mut libc::c_char`) and a length
-   (`libc::size_t`).
+   passing a pointer (`*mut libc::c_char`). The length can be passed
+   explicitly (`libc::size_t`), or the string can be NUL-byte terminated
+   C string.
 
    One might be tempted to do this via doing
    `CString::new("blah").unwrap().into_raw()`. This has several problems: