Doxygenize the file-level documentation of transports.c.

/**

 * \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

/** 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)