nihilist/tor
1
0
Fork 0
mirror of https://gitlab.torproject.org/tpo/core/tor.git synced 2024-11-24 04:13:28 +01:00
Code Issues Packages Projects Releases Wiki Activity

Doxygenize the file-level documentation of transports.c.

Browse Source
This commit is contained in:
George Kadianakis 2011-12-16 11:01:56 +01:00
parent 960f62bd82
commit 6d35f08e01
1 changed files with 77 additions and 78 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

155
src/or/transports.c
View File

@ -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)