Update the transports.c documentation based on the new data.

src/or/transports.c

@@ -56,23 +56,81 @@ static smartlist_t *managed_proxy_list = NULL;
 /** Number of still unconfigured proxies. */
 static int unconfigured_proxies_n = 0;
 
-/*  The main idea here is:
+/** "The main idea is:"
 
-    A managed proxy is represented by a managed_proxy_t struct and can
-    spawn multiple transports.
+    Each managed proxy is represented by a 'managed_proxy_t'.
+    Each managed proxy can support multiple transports.
+    Each managed proxy gets configured through a multistep process.
+
+    'managed_proxy_list' contains all the managed proxies this tor
+    instance is supporting.
+    In the 'managed_proxy_list' there are 'unconfigured_proxies_n'
+    managed proxies that are still unconfigured.
 
-    managed_proxy_list is a list of all the unconfigured managed
-    proxies; everytime we find a managed proxy in torrc we add it in
-    that list.
     In every run_scheduled_event() tick, we attempt to launch and then
-    configure each managed proxy, using the configuration protocol
-    defined in the 180_pluggable_transport.txt proposal. A managed
-    proxy might need several ticks to get fully configured.
+    configure the unconfiged managed proxies, using the configuration
+    protocol defined in the 180_pluggable_transport.txt proposal. A
+    managed proxy might need several ticks to get fully configured.
 
     When a managed proxy is fully configured, we register all its
-    transports to the circuitbuild.c subsystem - like we do with
-    external proxies - and then free the managed proxy struct
-    since it's no longer needed. */
+    transports to the circuitbuild.c subsystem. At that point the
+    transports are owned by the circuitbuild.c subsystem.
+
+    When a managed proxy fails to follow the 180 configuration
+    protocol, it gets marked as broken and gets destroyed.
+
+    "In a little more technical detail:"
+
+    While we are serially parsing torrc, we store all the transports
+    that a proxy should spawn in its 'transports_to_launch' element.
+
+    When we finish reading the torrc, we spawn the managed proxy and
+    expect {S,C}METHOD lines from its output. We add transports
+    described by METHOD lines to its 'transports' element, as
+    'transport_t' structs.
+
+    When the managed proxy stops spitting METHOD lines (signified by a
+    '{S,C}METHODS DONE' message) we register all the transports
+    collected to the circuitbuild.c subsystem. At this point, the
+    'transport_t's can be transformed into dangling pointers at any
+    point by the circuitbuild.c subsystem, and so we replace all
+    'transport_t's with strings describing the transport names.  We
+    can still go from a transport name to a 'transport_t' using the
+    fact that transport names uniquely identify 'transport_t's.
+
+    "In even more technical detail I shall describe what happens when
+    the SIGHUP bell tolls:"
+
+    We immediately destroy all unconfigured proxies (We shouldn't have
+    unconfigured proxies in the first place, except when SIGHUP rings
+    immediately after tor is launched.).
+
+    We mark all managed proxies and transports to signify that they
+    must be removed if they don't contribute by the new torrc. We also
+    mark all managed proxies to signify that they might need to be
+    restarted so that they end up supporting all the transports the
+    new torrc wants them to support.
+    We also clear the 'transports_to_launch' list so that we can put
+    there the transports we need to launch on each proxy according to
+    the new torrc.
+
+    We then start parsing torrc again, everytime we encounter a
+    transport line using a known pre-SIGHUP managed proxy, we cleanse
+    that proxy from the removal mark.
+
+    We also mark it as unconfigured so that on the next scheduled
+    events tick, we investigate whether we need to restart the proxy
+    so that it spawns the new 'transport_to_launch' list. Of course,
+    if the post-SIGHUP 'transports_to_launch' list is identical to the
+    pre-SIGHUP one, it means that no changes were introduced to this
+    proxy during the SIGHUP and no restart has to take place.
+
+    During the post-SIGHUP torrc parsing, we unmark all transports we
+    encounter. This happens in the case that no restart is needed, we
+    can continue using the old transports normally. If we end up
+    restarting the proxy, we destroy and unregister all old transports
+    from the circuitbuild.c subsystem since they become useless.
+*/
 
 /** Return true if there are still unconfigured managed proxies. */
 int