commit 1c50331b9af28a691cb48e632ab71d9af83916ba Author: Chelsea Holland Komlo <me@chelseakomlo.com> Date: Sat Nov 11 22:26:22 2017 -0500 annotate where C and Rust need to stay in sync --- doc/HACKING/GettingStartedRust.md | 8 ++++++++ src/rust/protover/ffi.rs | 3 ++- src/rust/protover/protover.rs | 12 ++++++++++++ 3 files changed, 22 insertions(+), 1 deletion(-) diff --git a/doc/HACKING/GettingStartedRust.md b/doc/HACKING/GettingStartedRust.md index a5253b46a..3cd7fdc42 100644 --- a/doc/HACKING/GettingStartedRust.md +++ b/doc/HACKING/GettingStartedRust.md @@ -125,6 +125,14 @@ is on our TODO list to try to cultivate good standing with various distro maintainers of `rustc` and `cargo`, in order to ensure that whatever version we solidify on is readily available. +If parts of your Rust code needs to stay in sync with C code (such as handling +enums across the FFI boundary), annonotate these places in a comment structured +as follows: + + /// C_RUST_COUPLED: <path_to_file> `<name_of_c_object>` + +Where <name_of_c_object> can be an enum, struct, constant, etc. + Adding your Rust module to Tor's build system ----------------------------------------------- diff --git a/src/rust/protover/ffi.rs b/src/rust/protover/ffi.rs index cebf9e12f..3eb22c933 100644 --- a/src/rust/protover/ffi.rs +++ b/src/rust/protover/ffi.rs @@ -15,7 +15,8 @@ use tor_allocate::allocate_and_copy_string; /// Translate C enums to Rust Proto enums, using the integer value of the C /// enum to map to its associated Rust enum -/// This is dependant on the associated C enum preserving ordering. +/// +/// C_RUST_COUPLED: src/or/protover.h `protocol_type_t` fn translate_to_rust(c_proto: uint32_t) -> Result<Proto, &'static str> { match c_proto { 0 => Ok(Proto::Link), diff --git a/src/rust/protover/protover.rs b/src/rust/protover/protover.rs index b8bf280d4..7d5947ca2 100644 --- a/src/rust/protover/protover.rs +++ b/src/rust/protover/protover.rs @@ -10,13 +10,20 @@ use std::string::String; /// The first version of Tor that included "proto" entries in its descriptors. /// Authorities should use this to decide whether to guess proto lines. +/// +/// C_RUST_COUPLED: +/// src/or/protover.h `FIRST_TOR_VERSION_TO_ADVERTISE_PROTOCOLS` const FIRST_TOR_VERSION_TO_ADVERTISE_PROTOCOLS: &'static str = "0.2.9.3-alpha"; /// The maximum number of subprotocol version numbers we will attempt to expand /// before concluding that someone is trying to DoS us +/// +/// C_RUST_COUPLED: src/or/protover.c `MAX_PROTOCOLS_TO_EXPAND` const MAX_PROTOCOLS_TO_EXPAND: u32 = 500; /// Currently supported protocols and their versions +/// +/// C_RUST_COUPLED: src/or/protover.c `protover_get_supported_protocols` const SUPPORTED_PROTOCOLS: &'static [&'static str] = &[ "Cons=1-2", "Desc=1-2", @@ -31,6 +38,8 @@ const SUPPORTED_PROTOCOLS: &'static [&'static str] = &[ ]; /// Known subprotocols in Tor. Indicates which subprotocol a relay supports. +/// +/// C_RUST_COUPLED: src/or/protover.h `protocol_type_t` #[derive(Hash, Eq, PartialEq, Debug)] pub enum Proto { Cons, @@ -53,6 +62,8 @@ impl fmt::Display for Proto { /// Translates a string representation of a protocol into a Proto type. /// Error if the string is an unrecognized protocol name. +/// +/// C_RUST_COUPLED: src/or/protover.c `PROTOCOL_NAMES` impl FromStr for Proto { type Err = &'static str; @@ -712,6 +723,7 @@ pub fn is_supported_here(proto: Proto, vers: u32) -> bool { /// This function returns the protocols that are supported by the version input, /// only for tor versions older than FIRST_TOR_VERSION_TO_ADVERTISE_PROTOCOLS. /// +/// C_RUST_COUPLED: src/rust/protover.c `compute_for_old_tor` pub fn compute_for_old_tor(version: &str) -> String { if c_tor_version_as_new_as( version,