commit 8a38d053a09615c8d9009571ba639bfcbd1d4fe2 Author: Nick Mathewson nickm@torproject.org Date: Wed Oct 26 13:30:23 2016 -0400

Continue the module documentation effort with circuitbuild and circuituse --- src/or/circuitbuild.c | 14 ++++++++++++++ src/or/circuituse.c | 20 +++++++++++++++++++- 2 files changed, 33 insertions(+), 1 deletion(-)

diff --git a/src/or/circuitbuild.c b/src/or/circuitbuild.c index 873d2ec..961c166 100644 --- a/src/or/circuitbuild.c +++ b/src/or/circuitbuild.c @@ -9,6 +9,20 @@ * * \brief Implements the details of building circuits (by chosing paths, * constructing/sending create/extend cells, and so on). + * + * On the client side, this module handles launching circuits. Circuit + * launches are srtarted from circuit_establish_circuit(), called from + * circuit_launch_by_extend_info()). To choose the path the circuit will + * take, onion_extend_cpath() calls into a maze of node selection functions. + * + * Once the circuit is ready to be launched, the first hop is treated as a + * special case with circuit_handle_first_hop(), since it might need to open a + * channel. As the channel opens, and later as CREATED and RELAY_EXTENDED + * cells arrive, the client will invoke circuit_send_next_onion_skin() to send + * CREATE or RELAY_EXTEND cells. + * + * On the server side, this module also handles the logic of responding to + * RELAY_EXTEND requests, using circuit_extend(). **/

#define CIRCUITBUILD_PRIVATE diff --git a/src/or/circuituse.c b/src/or/circuituse.c index f344703..166971c 100644 --- a/src/or/circuituse.c +++ b/src/or/circuituse.c @@ -6,7 +6,25 @@

/** * \file circuituse.c - * \brief Launch the right sort of circuits and attach streams to them. + * \brief Launch the right sort of circuits and attach the right streams to + * them. + * + * As distinct from circuitlist.c, which manages lookups to find circuits, and + * circuitbuild.c, which handles the logistics of circuit construction, this + * module keeps track of which streams can be attached to which circuits (in + * circuit_get_best()), and attaches streams to circuits (with + * circuit_try_attaching_streams(), connection_ap_handshake_attach_circuit(), + * and connection_ap_handshake_attach_chosen_circuit(). + * + * This module also makes sure that we are building circuits for all of the + * predicted ports, using circuit_remove_handled_ports(), + * circuit_stream_is_being_handled(), and circuit_build_needed_cirs(). It + * handles launching circuits for specific targets using + * circuit_launch_by_extend_info(). + * + * This is also where we handle expiring circuits that have been around for + * too long without actually completing, along with the circuit_build_timeout + * logic in circuitstats.c. **/

#include "or.h"