[tor-commits] [tor/master] Doxygenize the file-level documentation of transports.c.
nickm at torproject.org
nickm at torproject.org
Sat Dec 17 17:46:25 UTC 2011
commit 6d35f08e014cc750239b77e41aa8de9460c615bd
Author: George Kadianakis <desnacked at gmail.com>
Date: Fri Dec 16 11:01:56 2011 +0100
Doxygenize the file-level documentation of transports.c.
---
src/or/transports.c | 155 +++++++++++++++++++++++++--------------------------
1 files changed, 77 insertions(+), 78 deletions(-)
diff --git a/src/or/transports.c b/src/or/transports.c
index 06bc039..6ee4878 100644
--- a/src/or/transports.c
+++ b/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)
More information about the tor-commits
mailing list