Document connection_or.c and connection.c at module level

This commit is contained in:
Nick Mathewson 2016-10-18 12:25:55 -04:00
parent 84829e336c
commit d1b45786b1
2 changed files with 55 additions and 0 deletions

View File

@ -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

View File

@ -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"