commit d1b45786b1f91d3a65e88cc99c8021ea9d25a106 Author: Nick Mathewson nickm@torproject.org Date: Tue Oct 18 12:25:55 2016 -0400

Document connection_or.c and connection.c at module level --- src/or/connection.c | 44 ++++++++++++++++++++++++++++++++++++++++++++ src/or/connection_or.c | 11 +++++++++++ 2 files changed, 55 insertions(+)

diff --git a/src/or/connection.c b/src/or/connection.c index 5ecd1ad..49cb78e 100644 --- a/src/or/connection.c +++ b/src/or/connection.c @@ -8,6 +8,50 @@ * \file connection.c * \brief General high-level functions to handle reading and writing * on connections. + * + * Each connection (ideally) represents a TLS connection, a TCP socket, a unix + * socket, or a UDP socket on which reads and writes can occur. (But see + * connection_edge.c for cases where connections can also represent streams + * that do not have a corresponding socket.) + * + * The module implements the abstract type, connection_t. The subtypes are: + * <ul> + * <li>listener_connection_t, implemented here in connection.c + * <li>dir_connection_t, implemented in directory.c + * <li>or_connection_t, implemented in connection_or.c + * <li>edge_connection_t, implemented in connection_edge.c, along with + * its subtype(s): + * <ul><li>entry_connection_t, also implemented in connection_edge.c + * </ul> + * <li>control_connection_t, implemented in control.c + * </ul> + * + * The base type implemented in this module is responsible for basic + * rate limiting, flow control, and marshalling bytes onto and off of the + * network (either directly or via TLS). + * + * Connections are registered with the main loop with connection_add(). As + * they become able to read or write register the fact with the event main + * loop by calling connection_watch_events(), connection_start_reading(), or + * connection_start_writing(). When they no longer want to read or write, + * they call connection_stop_reading() or connection_start_writing(). + * + * To queue data to be written on a connection, call + * connection_write_to_buf(). When data arrives, the + * connection_process_inbuf() callback is invoked, which dispatches to a + * type-specific function (such as connection_edge_process_inbuf() for + * example). Connection types that need notice of when data has been written + * receive notification via connection_flushed_some() and + * connection_finished_flushing(). These functions all delegate to + * type-specific implementations. + * + * Additionally, beyond the core of connection_t, this module also implements: + * <ul> + * <li>Listeners, which wait for incoming sockets and launch connections + * <li>Outgoing SOCKS proxy support + * <li>Outgoing HTTP proxy support + * <li>An out-of-sockets handler for dealing with socket exhaustion + * </ul> **/

#define CONNECTION_PRIVATE diff --git a/src/or/connection_or.c b/src/or/connection_or.c index 72d8e13..267c32d 100644 --- a/src/or/connection_or.c +++ b/src/or/connection_or.c @@ -8,6 +8,17 @@ * \file connection_or.c * \brief Functions to handle OR connections, TLS handshaking, and * cells on the network. + * + * An or_connection_t is a subtype of connection_t (as implemented in + * connection.c) that uses a TLS connection to send and receive cells on the + * Tor network. (By sending and receiving cells connection_or.c, it cooperates + * with channeltls.c to implement a the channel interface of channel.c.) + * + * Every OR connection has an underlying tortls_t object (as implemented in + * tortls.c) which it uses as its TLS stream. It is responsible for + * sending and receiving cells over that TLS. + * + * This module also implements the client side of the v3 Tor link handshake, **/ #include "or.h" #include "buffers.h"