commit 6d35f08e014cc750239b77e41aa8de9460c615bd Author: George Kadianakis <desnacked@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)