commit b0d7b100886ef14a785f6ca1de968df9a884d0a7 Author: Nick Mathewson <nickm@torproject.org> Date: Thu Jul 16 09:57:52 2020 -0400 Improve documentation for our TO_*_CONN() cast functions. Preliminary work for #40046. --- src/core/mainloop/connection.c | 8 ++++++-- src/core/or/connection_edge.c | 20 ++++++++++++++++++-- src/core/or/connection_or.c | 7 +++++-- src/feature/control/control.c | 8 ++++++-- src/feature/dircommon/directory.c | 8 ++++++-- 5 files changed, 41 insertions(+), 10 deletions(-) diff --git a/src/core/mainloop/connection.c b/src/core/mainloop/connection.c index 282d90c2b0..216aeb68d1 100644 --- a/src/core/mainloop/connection.c +++ b/src/core/mainloop/connection.c @@ -220,8 +220,12 @@ static smartlist_t *outgoing_addrs = NULL; /**************************************************************/ -/** Convert a connection_t* to an listener_connection_t*; assert if the cast - * is invalid. */ +/** + * Cast a `connection_t *` to a `listener_connection_t *`. + * + * Exit with an assertion failure if the input is not a + * `listener_connection_t`. + **/ listener_connection_t * TO_LISTENER_CONN(connection_t *c) { diff --git a/src/core/or/connection_edge.c b/src/core/or/connection_edge.c index 8eb9f8ba0f..30cfb18f0f 100644 --- a/src/core/or/connection_edge.c +++ b/src/core/or/connection_edge.c @@ -166,8 +166,12 @@ static int connection_exit_connect_dir(edge_connection_t *exitconn); static int consider_plaintext_ports(entry_connection_t *conn, uint16_t port); static int connection_ap_supports_optimistic_data(const entry_connection_t *); -/** Convert a connection_t* to an edge_connection_t*; assert if the cast is - * invalid. */ +/** + * Cast a `connection_t *` to an `edge_connection_t *`. + * + * Exit with an assertion failure if the input is not an + * `edge_connection_t`. + **/ edge_connection_t * TO_EDGE_CONN(connection_t *c) { @@ -176,6 +180,12 @@ TO_EDGE_CONN(connection_t *c) return DOWNCAST(edge_connection_t, c); } +/** + * Cast a `connection_t *` to an `entry_connection_t *`. + * + * Exit with an assertion failure if the input is not an + * `entry_connection_t`. + **/ entry_connection_t * TO_ENTRY_CONN(connection_t *c) { @@ -183,6 +193,12 @@ TO_ENTRY_CONN(connection_t *c) return (entry_connection_t*) SUBTYPE_P(c, entry_connection_t, edge_.base_); } +/** + * Cast an `edge_connection_t *` to an `entry_connection_t *`. + * + * Exit with an assertion failure if the input is not an + * `entry_connection_t`. + **/ entry_connection_t * EDGE_TO_ENTRY_CONN(edge_connection_t *c) { diff --git a/src/core/or/connection_or.c b/src/core/or/connection_or.c index e62c28821a..e6dc62a475 100644 --- a/src/core/or/connection_or.c +++ b/src/core/or/connection_or.c @@ -99,8 +99,11 @@ static void connection_or_check_canonicity(or_connection_t *conn, /**************************************************************/ -/** Convert a connection_t* to an or_connection_t*; assert if the cast is - * invalid. */ +/** + * Cast a `connection_t *` to an `or_connection_t *`. + * + * Exit with an assertion failure if the input is not an `or_connnection_t`. + **/ or_connection_t * TO_OR_CONN(connection_t *c) { diff --git a/src/feature/control/control.c b/src/feature/control/control.c index ee1026359d..b5d4c31525 100644 --- a/src/feature/control/control.c +++ b/src/feature/control/control.c @@ -61,8 +61,12 @@ #include <sys/stat.h> #endif -/** Convert a connection_t* to an control_connection_t*; assert if the cast is - * invalid. */ +/** + * Cast a `connection_t *` to a `control_connection_t *`. + * + * Exit with an assertion failure if the input is not a + * `control_connection_t`. + **/ control_connection_t * TO_CONTROL_CONN(connection_t *c) { diff --git a/src/feature/dircommon/directory.c b/src/feature/dircommon/directory.c index 7f9f157a49..bb9264eaf9 100644 --- a/src/feature/dircommon/directory.c +++ b/src/feature/dircommon/directory.c @@ -79,8 +79,12 @@ * connection_finished_connecting() in connection.c */ -/** Convert a connection_t* to a dir_connection_t*; assert if the cast is - * invalid. */ +/** + * Cast a `connection_t *` to a `dir_connection_t *`. + * + * Exit with an assertion failure if the input is not a + * `dir_connection_t`. + **/ dir_connection_t * TO_DIR_CONN(connection_t *c) {