commit dc79504e2abc50921963a50671d122287d6a65c5
Author: Nick Mathewson <nickm(a)torproject.org>
Date: Thu Oct 27 10:25:26 2016 -0400
Document main.c a lot better
---
src/or/main.c | 165 ++++++++++++++++++++++++++++++++++++++++++++++++++--------
1 file changed, 144 insertions(+), 21 deletions(-)
diff --git a/src/or/main.c b/src/or/main.c
index 013e301..617c784 100644
--- a/src/or/main.c
+++ b/src/or/main.c
@@ -8,6 +8,42 @@
* \file main.c
* \brief Toplevel module. Handles signals, multiplexes between
* connections, implements main loop, and drives scheduled events.
+ *
+ * For the main loop itself; see run_main_loop_once(). It invokes the rest of
+ * Tor mostly through Libevent callbacks. Libevent callbacks can happen when
+ * a timer elapses, a signal is received, a socket is ready to read or write,
+ * or an event is manually activated.
+ *
+ * Most events in Tor are driven from these callbacks:
+ * <ul>
+ * <li>conn_read_callback() and conn_write_callback() here, which are
+ * invoked when a socket is ready to read or write respectively.
+ * <li>signal_callback(), which handles incoming signals.
+ * </ul>
+ * Other events are used for specific purposes, or for building more complex
+ * control structures. If you search for usage of tor_libevent_new(), you
+ * will find all the events that we construct in Tor.
+ *
+ * Tor has numerous housekeeping operations that need to happen
+ * regularly. They are handled in different ways:
+ * <ul>
+ * <li>The most frequent operations are handled after every read or write
+ * event, at the end of connection_handle_read() and
+ * connection_handle_write().
+ *
+ * <li>The next most frequent operations happen after each invocation of the
+ * main loop, in run_main_loop_once().
+ *
+ * <li>Once per second, we run all of the operations listed in
+ * second_elapsed_callback(), and in its child, run_scheduled_events().
+ *
+ * <li>Once-a-second operations are handled in second_elapsed_callback().
+ *
+ * <li>More infrequent operations take place based on the periodic event
+ * driver in periodic.c . These are stored in the periodic_events[]
+ * table.
+ * </ul>
+ *
**/
#define MAIN_PRIVATE
@@ -1408,13 +1444,13 @@ run_scheduled_events(time_t now)
pt_configure_remaining_proxies();
}
+/* Periodic callback: Every MIN_ONION_KEY_LIFETIME seconds, rotate the onion
+ * keys, shut down and restart all cpuworkers, and update our descriptor if
+ * necessary.
+ */
static int
rotate_onion_key_callback(time_t now, const or_options_t *options)
{
- /* 1a. Every MIN_ONION_KEY_LIFETIME seconds, rotate the onion keys,
- * shut down and restart all cpuworkers, and update the directory if
- * necessary.
- */
if (server_mode(options)) {
time_t rotation_time = get_onion_key_set_at()+MIN_ONION_KEY_LIFETIME;
if (rotation_time > now) {
@@ -1434,6 +1470,9 @@ rotate_onion_key_callback(time_t now, const or_options_t *options)
return PERIODIC_EVENT_NO_UPDATE;
}
+/* Periodic callback: Every 30 seconds, check whether it's time to make new
+ * Ed25519 subkeys.
+ */
static int
check_ed_keys_callback(time_t now, const or_options_t *options)
{
@@ -1451,6 +1490,11 @@ check_ed_keys_callback(time_t now, const or_options_t *options)
return PERIODIC_EVENT_NO_UPDATE;
}
+/**
+ * Periodic callback: Every {LAZY,GREEDY}_DESCRIPTOR_RETRY_INTERVAL,
+ * see about fetching descriptors, microdescriptors, and extrainfo
+ * documents.
+ */
static int
launch_descriptor_fetches_callback(time_t now, const or_options_t *options)
{
@@ -1465,6 +1509,10 @@ launch_descriptor_fetches_callback(time_t now, const or_options_t *options)
return GREEDY_DESCRIPTOR_RETRY_INTERVAL;
}
+/**
+ * Periodic event: Rotate our X.509 certificates and TLS keys once every
+ * MAX_SSL_KEY_LIFETIME_INTERNAL.
+ */
static int
rotate_x509_certificate_callback(time_t now, const or_options_t *options)
{
@@ -1490,6 +1538,10 @@ rotate_x509_certificate_callback(time_t now, const or_options_t *options)
return MAX_SSL_KEY_LIFETIME_INTERNAL;
}
+/**
+ * Periodic callback: once an hour, grab some more entropy from the
+ * kernel and feed it to our CSPRNG.
+ **/
static int
add_entropy_callback(time_t now, const or_options_t *options)
{
@@ -1506,6 +1558,10 @@ add_entropy_callback(time_t now, const or_options_t *options)
return ENTROPY_INTERVAL;
}
+/**
+ * Periodic callback: if we're an authority, make sure we test
+ * the routers on the network for reachability.
+ */
static int
launch_reachability_tests_callback(time_t now, const or_options_t *options)
{
@@ -1517,6 +1573,10 @@ launch_reachability_tests_callback(time_t now, const or_options_t *options)
return REACHABILITY_TEST_INTERVAL;
}
+/**
+ * Periodic callback: if we're an authority, discount the stability
+ * information (and other rephist information) that's older.
+ */
static int
downrate_stability_callback(time_t now, const or_options_t *options)
{
@@ -1528,6 +1588,10 @@ downrate_stability_callback(time_t now, const or_options_t *options)
return safe_timer_diff(now, next);
}
+/**
+ * Periodic callback: if we're an authority, record our measured stability
+ * information from rephist in an mtbf file.
+ */
static int
save_stability_callback(time_t now, const or_options_t *options)
{
@@ -1540,6 +1604,10 @@ save_stability_callback(time_t now, const or_options_t *options)
return SAVE_STABILITY_INTERVAL;
}
+/**
+ * Periodic callback: if we're an authority, check on our authority
+ * certificate (the one that authenticates our authority signing key).
+ */
static int
check_authority_cert_callback(time_t now, const or_options_t *options)
{
@@ -1552,6 +1620,10 @@ check_authority_cert_callback(time_t now, const or_options_t *options)
return CHECK_V3_CERTIFICATE_INTERVAL;
}
+/**
+ * Periodic callback: If our consensus is too old, recalculate whether
+ * we can actually use it.
+ */
static int
check_expired_networkstatus_callback(time_t now, const or_options_t *options)
{
@@ -1571,6 +1643,9 @@ check_expired_networkstatus_callback(time_t now, const or_options_t *options)
return CHECK_EXPIRED_NS_INTERVAL;
}
+/**
+ * Periodic callback: Write statistics to disk if appropriate.
+ */
static int
write_stats_file_callback(time_t now, const or_options_t *options)
{
@@ -1618,6 +1693,9 @@ write_stats_file_callback(time_t now, const or_options_t *options)
return safe_timer_diff(now, next_time_to_write_stats_files);
}
+/**
+ * Periodic callback: Write bridge statistics to disk if appropriate.
+ */
static int
record_bridge_stats_callback(time_t now, const or_options_t *options)
{
@@ -1645,6 +1723,9 @@ record_bridge_stats_callback(time_t now, const or_options_t *options)
return PERIODIC_EVENT_NO_UPDATE;
}
+/**
+ * Periodic callback: Clean in-memory caches every once in a while
+ */
static int
clean_caches_callback(time_t now, const or_options_t *options)
{
@@ -1658,6 +1739,10 @@ clean_caches_callback(time_t now, const or_options_t *options)
return CLEAN_CACHES_INTERVAL;
}
+/**
+ * Periodic callback: Clean the cache of failed hidden service lookups
+ * frequently frequently.
+ */
static int
rend_cache_failure_clean_callback(time_t now, const or_options_t *options)
{
@@ -1669,20 +1754,21 @@ rend_cache_failure_clean_callback(time_t now, const or_options_t *options)
return 30;
}
+/**
+ * Periodic callback: If we're a server and initializing dns failed, retry.
+ */
static int
retry_dns_callback(time_t now, const or_options_t *options)
{
(void)now;
#define RETRY_DNS_INTERVAL (10*60)
- /* If we're a server and initializing dns failed, retry periodically. */
if (server_mode(options) && has_dns_init_failed())
dns_init();
return RETRY_DNS_INTERVAL;
}
- /* 2. Periodically, we consider force-uploading our descriptor
- * (if we've passed our internal checks). */
-
+/** Periodic callback: consider rebuilding or and re-uploading our descriptor
+ * (if we've passed our internal checks). */
static int
check_descriptor_callback(time_t now, const or_options_t *options)
{
@@ -1709,6 +1795,11 @@ check_descriptor_callback(time_t now, const or_options_t *options)
return CHECK_DESCRIPTOR_INTERVAL;
}
+/**
+ * Periodic callback: check whether we're reachable (as a relay), and
+ * whether our bandwidth has changed enough that we need to
+ * publish a new descriptor.
+ */
static int
check_for_reachability_bw_callback(time_t now, const or_options_t *options)
{
@@ -1745,13 +1836,13 @@ check_for_reachability_bw_callback(time_t now, const or_options_t *options)
return CHECK_DESCRIPTOR_INTERVAL;
}
+/**
+ * Periodic event: once a minute, (or every second if TestingTorNetwork, or
+ * during client bootstrap), check whether we want to download any
+ * networkstatus documents. */
static int
fetch_networkstatus_callback(time_t now, const or_options_t *options)
{
- /* 2c. Every minute (or every second if TestingTorNetwork, or during
- * client bootstrap), check whether we want to download any networkstatus
- * documents. */
-
/* How often do we check whether we should download network status
* documents? */
const int we_are_bootstrapping = networkstatus_consensus_is_bootstrapping(
@@ -1773,12 +1864,13 @@ fetch_networkstatus_callback(time_t now, const or_options_t *options)
return networkstatus_dl_check_interval;
}
+/**
+ * Periodic callback: Every 60 seconds, we relaunch listeners if any died. */
static int
retry_listeners_callback(time_t now, const or_options_t *options)
{
(void)now;
(void)options;
- /* 3d. And every 60 seconds, we relaunch listeners if any died. */
if (!net_is_disabled()) {
retry_all_listeners(NULL, NULL, 0);
return 60;
@@ -1786,6 +1878,9 @@ retry_listeners_callback(time_t now, const or_options_t *options)
return PERIODIC_EVENT_NO_UPDATE;
}
+/**
+ * Periodic callback: as a server, see if we have any old unused circuits
+ * that should be expired */
static int
expire_old_ciruits_serverside_callback(time_t now, const or_options_t *options)
{
@@ -1795,6 +1890,10 @@ expire_old_ciruits_serverside_callback(time_t now, const or_options_t *options)
return 11;
}
+/**
+ * Periodic event: if we're an exit, see if our DNS server is telling us
+ * obvious lies.
+ */
static int
check_dns_honesty_callback(time_t now, const or_options_t *options)
{
@@ -1817,6 +1916,10 @@ check_dns_honesty_callback(time_t now, const or_options_t *options)
return 12*3600 + crypto_rand_int(12*3600);
}
+/**
+ * Periodic callback: if we're the bridge authority, write a networkstatus
+ * file to disk.
+ */
static int
write_bridge_ns_callback(time_t now, const or_options_t *options)
{
@@ -1829,6 +1932,9 @@ write_bridge_ns_callback(time_t now, const or_options_t *options)
return PERIODIC_EVENT_NO_UPDATE;
}
+/**
+ * Periodic callback: poke the tor-fw-helper app if we're using one.
+ */
static int
check_fw_helper_app_callback(time_t now, const or_options_t *options)
{
@@ -1852,7 +1958,9 @@ check_fw_helper_app_callback(time_t now, const or_options_t *options)
return PORT_FORWARDING_CHECK_INTERVAL;
}
-/** Callback to write heartbeat message in the logs. */
+/**
+ * Periodic callback: write the heartbeat message in the logs.
+ */
static int
heartbeat_callback(time_t now, const or_options_t *options)
{
@@ -2358,19 +2466,26 @@ run_main_loop_once(void)
/* Make it easier to tell whether libevent failure is our fault or not. */
errno = 0;
#endif
- /* All active linked conns should get their read events activated. */
+
+ /* All active linked conns should get their read events activated,
+ * so that libevent knows to run their callbacks. */
SMARTLIST_FOREACH(active_linked_connection_lst, connection_t *, conn,
event_active(conn->read_event, EV_READ, 1));
called_loop_once = smartlist_len(active_linked_connection_lst) ? 1 : 0;
+ /* Make sure we know (about) what time it is. */
update_approx_time(time(NULL));
- /* poll until we have an event, or the second ends, or until we have
- * some active linked connections to trigger events for. */
+ /* Here it is: the main loop. Here we tell Libevent to poll until we have
+ * an event, or the second ends, or until we have some active linked
+ * connections to trigger events for. Libevent will wait till one
+ * of these happens, then run all the appropriate callbacks. */
loop_result = event_base_loop(tor_libevent_get_base(),
called_loop_once ? EVLOOP_ONCE : 0);
- /* let catch() handle things like ^c, and otherwise don't worry about it */
+ /* Oh, the loop failed. That might be an error that we need to
+ * catch, but more likely, it's just an interrupted poll() call or something,
+ * and we should try again. */
if (loop_result < 0) {
int e = tor_socket_errno(-1);
/* let the program survive things like ^z */
@@ -2393,9 +2508,17 @@ run_main_loop_once(void)
}
}
- /* This will be pretty fast if nothing new is pending. Note that this gets
- * called once per libevent loop, which will make it happen once per group
- * of events that fire, or once per second. */
+ /* And here is where we put callbacks that happen "every time the event loop
+ * runs." They must be very fast, or else the whole Tor process will get
+ * slowed down.
+ *
+ * Note that this gets called once per libevent loop, which will make it
+ * happen once per group of events that fire, or once per second. */
+
+ /* If there are any pending client connections, try attaching them to
+ * circuits (if we can.) This will be pretty fast if nothing new is
+ * pending.
+ */
connection_ap_attach_pending(0);
return 1;