[tor-commits] [tor/master] annotate where C and Rust need to stay in sync

[nickm at torproject.org]

commit 1c50331b9af28a691cb48e632ab71d9af83916ba
Author: Chelsea Holland Komlo <me at 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,