[or-cvs] r9392: More doxygen comments: this time mainly around spooling and (in tor/trunk: . src/or)
nickm at seul.org
nickm at seul.org
Tue Jan 23 19:22:55 UTC 2007
Author: nickm
Date: 2007-01-23 14:22:52 -0500 (Tue, 23 Jan 2007)
New Revision: 9392
Modified:
tor/trunk/
tor/trunk/src/or/directory.c
tor/trunk/src/or/dirserv.c
tor/trunk/src/or/or.h
Log:
r11278 at catbus: nickm | 2007-01-23 14:22:27 -0500
More doxygen comments: this time mainly around spooling and storing directory information.
Property changes on: tor/trunk
___________________________________________________________________
svk:merge ticket from /tor/trunk [r11278] on 8246c3cf-6607-4228-993b-4d95d33730f1
Modified: tor/trunk/src/or/directory.c
===================================================================
--- tor/trunk/src/or/directory.c 2007-01-23 19:22:49 UTC (rev 9391)
+++ tor/trunk/src/or/directory.c 2007-01-23 19:22:52 UTC (rev 9392)
@@ -288,7 +288,9 @@
payload, payload_len);
}
-/** DOCDOC */
+/** Return true iff <b>conn</b> is the client side of a directory connection
+ * we launched to ourself in order to determine the reachability of our
+ * dir_port. */
static int
directory_conn_is_self_reachability_test(dir_connection_t *conn)
{
Modified: tor/trunk/src/or/dirserv.c
===================================================================
--- tor/trunk/src/or/dirserv.c 2007-01-23 19:22:49 UTC (rev 9391)
+++ tor/trunk/src/or/dirserv.c 2007-01-23 19:22:52 UTC (rev 9392)
@@ -977,7 +977,8 @@
}
}
-/** DOCDOC */
+/** Decrement the reference count on <b>d</b>, and free it if it no longer has
+ * any references. */
void
cached_dir_decref(cached_dir_t *d)
{
@@ -987,7 +988,8 @@
tor_free(d);
}
-/** DOCDOC */
+/** Allocate and return a new cached_dir_t containing the string <b>s</b>,
+ * published at <b>published</b>. */
static cached_dir_t *
new_cached_dir(char *s, time_t published)
{
@@ -1325,12 +1327,17 @@
the_v2_networkstatus_is_dirty + DIR_REGEN_SLACK_TIME < time(NULL);
}
+/* Thresholds for server performance: set by
+ * dirserv_compute_performance_thresholds, and used by
+ * generate_v2_networkstatus */
static uint32_t stable_uptime = 0; /* start at a safe value */
static uint32_t fast_bandwidth = 0;
static uint32_t guard_bandwidth = 0;
static uint64_t total_bandwidth = 0;
static uint64_t total_exit_bandwidth = 0;
+/** Helper: estimate the uptime of a router given its stated uptime and the
+ * amount of time since it last stated its stated uptime. */
static INLINE int
real_uptime(routerinfo_t *router, time_t now)
{
@@ -1359,6 +1366,8 @@
return 0;
}
+/** Helper: returns a tristate based on comparing **(uint32_t**)a to
+* **(uint32_t**)b. */
static int
_compare_uint32(const void **a, const void **b)
{
@@ -1952,6 +1961,9 @@
* below this threshold. */
#define DIRSERV_BUFFER_MIN 16384
+/** Spooling helper: called when we have no more data to spool to <b>conn</b>.
+ * Flushes any remaining data to be (un)compressed, and changes the spool
+ * source to NONE. Returns 0 on success, negative on failure. */
static int
connection_dirserv_finish_spooling(dir_connection_t *conn)
{
@@ -1964,7 +1976,12 @@
return 0;
}
-/** DOCDOC */
+/** Spooling helper: called when we're sending a bunch of server descriptors,
+ * and the outbuf has become too empty. Pulls some entries from
+ * fingerprint_stack, and writes the corresponding servers onto outbuf. If we
+ * run out of entries, flushes the zlib state and sets the spool source to
+ * NONE. Returns 0 on success, negative on failure.
+ */
static int
connection_dirserv_add_servers_to_outbuf(dir_connection_t *conn)
{
@@ -2014,7 +2031,12 @@
return 0;
}
-/** DOCDOC */
+/** Spooling helper: Called when we're sending a directory or networkstatus,
+ * and the outbuf has become too empty. Pulls some bytes from
+ * <b>conn</b>-\>cached_dir-\>dir_z, uncompresses them if appropriate, and
+ * puts them on the outbuf. If we run out of entries, flushes the zlib state
+ * and sets the spool source to NONE. Returns 0 on success, negative on
+ * failure. */
static int
connection_dirserv_add_dir_bytes_to_outbuf(dir_connection_t *conn)
{
@@ -2048,7 +2070,13 @@
return 0;
}
-/* DOCDOC */
+/* Spooling helper: Called when we're spooling networkstatus objects on
+ * <b>conn</b>, and the outbuf has become too empty. If the current
+ * networkstatus object (in <b>conn</b>-\>cached_dir) has more data, pull data
+ * from there. Otherwise, pop the next fingerprint from fingerprint_stack,
+ * and start spooling the next networkstatus. If we run out of entries,
+ * flushes the zlib state and sets the spool source to NONE. Returns 0 on
+ * success, negative on failure. */
static int
connection_dirserv_add_networkstatus_bytes_to_outbuf(dir_connection_t *conn)
{
Modified: tor/trunk/src/or/or.h
===================================================================
--- tor/trunk/src/or/or.h 2007-01-23 19:22:49 UTC (rev 9391)
+++ tor/trunk/src/or/or.h 2007-01-23 19:22:52 UTC (rev 9392)
@@ -524,9 +524,11 @@
#define RESOLVED_TYPE_ERROR_TRANSIENT 0xF0
#define RESOLVED_TYPE_ERROR 0xF1
-/* DOCDOC We should document the meaning of these. */
-/* Negative reasons are internal */
+/* Negative reasons are internal: we never send them in a DESTROY or TRUNCATE
+ * call; they only go to the controller for tracking */
+/** We couldn't build a path for this circuit. */
#define END_CIRC_REASON_NOPATH -2
+/** Catch-all "other" reason for closing origin circuits. */
#define END_CIRC_AT_ORIGIN -1
/* Reasons why we (or a remote OR) might close a circuit. See tor-spec.txt for
@@ -811,13 +813,18 @@
/* Used only for server sides of some dir connections, to implement
* "spooling" of directory material to the outbuf. Otherwise, we'd have
* to append everything to the outbuf in one enormous chunk. */
+ /** What exactly are we spooling right now? */
enum {
DIR_SPOOL_NONE=0, DIR_SPOOL_SERVER_BY_DIGEST, DIR_SPOOL_SERVER_BY_FP,
DIR_SPOOL_CACHED_DIR, DIR_SPOOL_NETWORKSTATUS
} dir_spool_src;
+ /** List of fingerprints for networkstatuses or desriptors to be spooled. */
smartlist_t *fingerprint_stack;
+ /** A cached_dir_t object that we're currently spooling out */
struct cached_dir_t *cached_dir;
+ /** The current offset into cached_dir. */
off_t cached_dir_offset;
+ /** The zlib object doing on-the-fly compression for spooled data. */
tor_zlib_state_t *zlib_state;
char rend_query[REND_SERVICE_ID_LEN+1]; /**< What rendezvous service are we
@@ -937,12 +944,21 @@
/** Information need to cache an onion router's descriptor. */
typedef struct signed_descriptor_t {
+ /** Pointer to the raw server descriptor. Not necessarily NUL-terminated.
+ * If saved_location is SAVED_IN_CACHE, this pointer is null. */
char *signed_descriptor_body;
+ /** Length of the server descriptor. */
size_t signed_descriptor_len;
+ /** Digest of the server descriptor, computed as specified in dir-spec.txt */
char signed_descriptor_digest[DIGEST_LEN];
+ /** Identity digest of the router. */
char identity_digest[DIGEST_LEN];
+ /** Declared publication time of the descriptor */
time_t published_on;
+ /** Where is the descriptor saved? */
saved_location_t saved_location;
+ /** If saved_location is SAVED_IN_CACHE or SAVED_IN_JOURNAL, the offset of
+ * this descriptor in the corresponding file. */
off_t saved_offset;
} signed_descriptor_t;
@@ -2632,10 +2648,10 @@
/** A cached rendezvous descriptor. */
typedef struct rend_cache_entry_t {
- size_t len; /** Length of <b>desc</b> */
- time_t received; /** When was the descriptor received? */
- char *desc; /** Service descriptor */
- rend_service_descriptor_t *parsed; /* Parsed value of 'desc' */
+ size_t len; /**< Length of <b>desc</b> */
+ time_t received; /**< When was the descriptor received? */
+ char *desc; /**< Service descriptor */
+ rend_service_descriptor_t *parsed; /**< Parsed value of 'desc' */
} rend_cache_entry_t;
void rend_cache_init(void);
More information about the tor-commits
mailing list