Merge remote-tracking branch 'asn-mytor/bug4726'

src/or/transports.c

@@ -4,6 +4,83 @@
 /**
  * \file transports.c
  * \brief Pluggable Transports related code.
+ *
+ * \details
+ * Each managed proxy is represented by a <b>managed_proxy_t</b>.
+ * 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.
+ *
+ * In every run_scheduled_event() tick, we attempt to launch and then
+ * 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. 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.
+ *
+ * <b>In a little more detail:</b>
+ *
+ * While we are serially parsing torrc, we store all the transports
+ * that a proxy should spawn in its <em>transports_to_launch</em>
+ * 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 <em>transports</em> 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
+ * pointers to transport_t can be transformed into dangling pointers
+ * at any point by the circuitbuild.c subsystem, and so we replace all
+ * transport_t pointers with strings describing the transport names.
+ * We can still go from a transport name to a transport_t using the
+ * fact that each transport name uniquely identifies a transport_t.
+ *
+ * <b>In even more detail, this is what happens when a SIGHUP
+ * occurs:</b>
+ *
+ * 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 mark using the <b>marked_for_removal</b> element).
+ * 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 (using the <b>got_hup</b> element).
+ * We also clear their <b>transports_to_launch</b> list so that we can
+ * put there the transports we need to launch 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 also spawns the new transports.
+ * If the post-SIGHUP <b>transports_to_launch</b> 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
+ * spawned by managed proxies that we find in our torrc.
+ * We do that so that if we don't need to restart a managed proxy, we
+ * can continue using its old transports normally.
+ * If we end up restarting the proxy, we destroy and unregister all
+ * old transports from the circuitbuild.c subsystem.
  **/
 
 #define PT_PRIVATE
@@ -64,84 +141,6 @@ static smartlist_t *managed_proxy_list = NULL;
 /** Number of still unconfigured proxies. */
 static int unconfigured_proxies_n = 0;
 
-/** "The main idea is:"
-
-    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.
-
-    In every run_scheduled_event() tick, we attempt to launch and then
-    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. 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
-    (marked_for_removal).
-    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 (got_hup).
-    We also clear their 'transports_to_launch' list so that we can put
-    there the transports we need to launch 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 also spawns the new transports.
-    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
-    spawned by managed proxies that we find in our torrc.
-    We do that so that if we don't need to restart a managed proxy, we
-    can continue using its old transports normally.
-    If we end up restarting the proxy, we destroy and unregister all
-    old transports from the circuitbuild.c subsystem.
-*/
-
 /** Return true if there are still unconfigured managed proxies. */
 int
 pt_proxies_configuration_pending(void)