[or-cvs] r9385: Document a few undocumented functions and arguments. (in tor/trunk: . src/or)
nickm at seul.org
nickm at seul.org
Mon Jan 22 07:51:07 UTC 2007
Author: nickm
Date: 2007-01-22 02:51:06 -0500 (Mon, 22 Jan 2007)
New Revision: 9385
Modified:
tor/trunk/
tor/trunk/src/or/hibernate.c
tor/trunk/src/or/main.c
tor/trunk/src/or/or.h
tor/trunk/src/or/router.c
tor/trunk/src/or/routerlist.c
tor/trunk/src/or/routerparse.c
Log:
r9715 at catbus: nickm | 2007-01-22 02:51:04 -0500
Document a few undocumented functions and arguments.
Property changes on: tor/trunk
___________________________________________________________________
svk:merge ticket from /tor/trunk [r9715] on 8246c3cf-6607-4228-993b-4d95d33730f1
Modified: tor/trunk/src/or/hibernate.c
===================================================================
--- tor/trunk/src/or/hibernate.c 2007-01-22 07:27:37 UTC (rev 9384)
+++ tor/trunk/src/or/hibernate.c 2007-01-22 07:51:06 UTC (rev 9385)
@@ -940,7 +940,11 @@
}
}
-/** DOCDOC */
+/** Helper function: called when we get a GETINFO request for an
+ * accounting-related key on the control connection <b>conn</b>. If we can
+ * answer the request for <b>question</b>, then set *<b>answer</b> to a newly
+ * allocated string holding the result. Otherwise, set *<b>answer</b> to
+ * NULL. */
int
getinfo_helper_accounting(control_connection_t *conn,
const char *question, char **answer)
Modified: tor/trunk/src/or/main.c
===================================================================
--- tor/trunk/src/or/main.c 2007-01-22 07:27:37 UTC (rev 9384)
+++ tor/trunk/src/or/main.c 2007-01-22 07:51:06 UTC (rev 9385)
@@ -1088,7 +1088,8 @@
dns_servers_relaunch_checks();
}
-/* DOCDOC */
+/** Forget what we've learned about the correctness of our DNS servers, and
+ * start learning again. */
void
dns_servers_relaunch_checks(void)
{
@@ -2285,7 +2286,9 @@
}
#endif
-/** DOCDOC */
+/** Main entry point for the Tor process. Called from main(). */
+/* This function is distinct from main() only so we can link main.c into
+ * the unittest binary without conflicting with the unittests' main. */
int
tor_main(int argc, char *argv[])
{
Modified: tor/trunk/src/or/or.h
===================================================================
--- tor/trunk/src/or/or.h 2007-01-22 07:27:37 UTC (rev 9384)
+++ tor/trunk/src/or/or.h 2007-01-22 07:51:06 UTC (rev 9385)
@@ -916,8 +916,23 @@
int refcnt; /**< Reference count for this cached_dir_t. */
} cached_dir_t;
+/** Enum used to remember where a signed_descriptor_t is stored and how to
+ * manage the memory for signed_descriptor_body. */
typedef enum {
- SAVED_NOWHERE=0, SAVED_IN_CACHE, SAVED_IN_JOURNAL
+ /** The descriptor isn't stored on disk at all: the copy in memory is
+ * canonical; the saved_offset field is meaningless. */
+ SAVED_NOWHERE=0,
+ /** The descriptor is stored in the cached_routers file: the
+ * signed_descriptor_body is meaningless; the signed_descriptor_len and
+ * saved_offset are used to index into the mmaped cache file. */
+ SAVED_IN_CACHE,
+ /** The descriptor is stored in the cached_routers.new file: the
+ * signed_descriptor_body and saved_offset fields are both set. */
+ /* FFFF (We could also mmap the file and grow the mmap as needed, or
+ * lazy-load the descriptor text by using seek and read. We don't, for
+ * now.)
+ */
+ SAVED_IN_JOURNAL
} saved_location_t;
/** Information need to cache an onion router's descriptor. */
Modified: tor/trunk/src/or/router.c
===================================================================
--- tor/trunk/src/or/router.c 2007-01-22 07:27:37 UTC (rev 9384)
+++ tor/trunk/src/or/router.c 2007-01-22 07:51:06 UTC (rev 9385)
@@ -381,7 +381,7 @@
/** Whether we can reach our DirPort from the outside. */
static int can_reach_dir_port = 0;
-/** DOCDOC */
+/** Forget what we have learned about our reachability status. */
void
router_reset_reachability(void)
{
@@ -769,7 +769,8 @@
return body;
}
-/*DOCDOC*/
+/** A list of nicknames that we've warned about including in our family
+ * declaration verbatim rather than as digests. */
static smartlist_t *warned_nonexistent_family = NULL;
static int router_guess_address_from_dir_headers(uint32_t *guess);
@@ -1315,7 +1316,13 @@
strspn(s,HEX_CHARACTERS)==HEX_DIGEST_LEN);
}
-/** DOCDOC buf must have MAX_VERBOSE_NICKNAME_LEN+1 bytes. */
+/** Set <b>buf</b> (which must have MAX_VERBOSE_NICKNAME_LEN+1 bytes) to the
+ * verbose representation of the identity of <b>router</b>. The format is:
+ * A dollar sign.
+ * The upper-case hexadecimal encoding of the SHA1 hash of router's identity.
+ * A "=" if the router is named; a "~" if it is not.
+ * The router's nickname.
+ **/
void
router_get_verbose_nickname(char *buf, routerinfo_t *router)
{
Modified: tor/trunk/src/or/routerlist.c
===================================================================
--- tor/trunk/src/or/routerlist.c 2007-01-22 07:27:37 UTC (rev 9384)
+++ tor/trunk/src/or/routerlist.c 2007-01-22 07:51:06 UTC (rev 9385)
@@ -186,7 +186,8 @@
}
/** Add the <b>len</b>-type router descriptor in <b>s</b> to the router
- * journal. */
+ * journal; change its saved_locatino to SAVED_IN_JOURNAL and set its
+ * offset appropriately. */
static int
router_append_to_journal(signed_descriptor_t *desc)
{
@@ -1316,7 +1317,9 @@
return digestmap_get(routerlist->desc_digest_map, digest);
}
-/* DOCDOC Not always nul-terminated. */
+/** Return a pointer to the signed textual representation of a descriptor.
+ * The returned string is not guaranteed to be NUL-terminated: the string's
+ * length will be in desc->signed_descriptor_len. */
const char *
signed_descriptor_get_body(signed_descriptor_t *desc)
{
@@ -2146,14 +2149,14 @@
}
/** Given a string <b>s</b> containing some routerdescs, parse it and put the
- * routers into our directory. If <b>from_cache</b> is false, the routers
- * are in response to a query to the network: cache them.
+ * routers into our directory. If saved_location is SAVED_NOWHERE, the routers
+ * are in response to a query to the network: cache them by adding them to
+ * the journal.
*
* If <b>requested_fingerprints</b> is provided, it must contain a list of
* uppercased identity fingerprints. Do not update any router whose
* fingerprint is not on the list; after updating a router, remove its
* fingerprint from the list.
- * DOCDOC saved_location
*/
void
router_load_routers_from_string(const char *s, saved_location_t saved_location,
@@ -3975,9 +3978,9 @@
return have_min_dir_info;
}
-/** DOCDOC
- * Must change when authorities change, networkstatuses change, or list of
- * routerdescs changes, or number of running routers changes.
+/** Called when our internal view of the directory has changed. This can be
+ * when the authorities change, networkstatuses change, the list of routerdescs
+ * changes, or number of running routers changes.
*/
static void
router_dir_info_changed(void)
@@ -3985,7 +3988,9 @@
need_to_update_have_min_dir_info = 1;
}
-/** DOCDOC */
+/** Change the value of have_min_dir_info, setting it true iff we have enough
+ * network and router information to build circuits. Clear the value of
+ * need_to_update_have_min_dir_info. */
static void
update_router_have_minimum_dir_info(void)
{
@@ -4251,7 +4256,8 @@
return 0;
}
-/*DOCDOC*/
+/** Assert that the internal representation of <b>rl</b> is
+ * self-consistent. */
static void
routerlist_assert_ok(routerlist_t *rl)
{
Modified: tor/trunk/src/or/routerparse.c
===================================================================
--- tor/trunk/src/or/routerparse.c 2007-01-22 07:27:37 UTC (rev 9384)
+++ tor/trunk/src/or/routerparse.c 2007-01-22 07:51:06 UTC (rev 9385)
@@ -632,8 +632,13 @@
* descriptors, parses them and stores the result in <b>dest</b>. All routers
* are marked running and valid. Advances *s to a point immediately
* following the last router entry. Ignore any trailing router entries that
- * are not complete. Returns 0 on success and -1 on failure.
- * DOCDOC saved_location
+ * are not complete.
+ *
+ * If <b>saved_location</b> isn't SAVED_IN_CACHE, make a local copy of each
+ * descriptor in the signed_descriptor_body field of each routerinfo_t. If it
+ * isn't SAVED_NOWHERE, remember the offset of each descriptor.
+ *
+ * Returns 0 on success and -1 on failure.
*/
int
router_parse_list_from_string(const char **s, smartlist_t *dest,
@@ -719,8 +724,9 @@
/** Helper function: reads a single router entry from *<b>s</b> ...
* *<b>end</b>. Mallocs a new router and returns it if all goes well, else
- * returns NULL.
- * DOCDOC cache_copy
+ * returns NULL. If <b>cache_copy</b> is true, duplicate the contents of
+ * s through end into the signed_descriptor_body of the resulting
+ * routerinfo_t.
*/
routerinfo_t *
router_parse_entry_from_string(const char *s, const char *end,
More information about the tor-commits
mailing list