[Author Prev][Author Next][Thread Prev][Thread Next][Author Index][Thread Index]
[or-cvs] r9476: Resolve remaining DOCDOC comments. (in tor/trunk: . src/or)
Author: nickm
Date: 2007-02-02 13:58:11 -0500 (Fri, 02 Feb 2007)
New Revision: 9476
Modified:
tor/trunk/
tor/trunk/src/or/circuitlist.c
tor/trunk/src/or/connection_edge.c
tor/trunk/src/or/control.c
tor/trunk/src/or/directory.c
tor/trunk/src/or/routerlist.c
Log:
r12123@Kushana: nickm | 2007-02-02 13:57:42 -0500
Resolve remaining DOCDOC comments.
Property changes on: tor/trunk
___________________________________________________________________
svk:merge ticket from /tor/trunk [r12123] on c95137ef-5f19-0410-b913-86e773d04f59
Modified: tor/trunk/src/or/circuitlist.c
===================================================================
--- tor/trunk/src/or/circuitlist.c 2007-02-02 18:58:04 UTC (rev 9475)
+++ tor/trunk/src/or/circuitlist.c 2007-02-02 18:58:11 UTC (rev 9476)
@@ -634,12 +634,10 @@
return NULL;
}
-/** Return the first circuit in global_circuitlist after <b>start</b>
- * whose purpose is <b>purpose</b> is purpose, and (if set) whose
- * <b>digest</b> matches the rend_pk_digest field. Return NULL if no
- * circuit is found.
- * If <b>start</b> is NULL, begin at the start of the list.
- * DOCDOC origin.
+/** Return the first circuit originating here in global_circuitlist after
+ * <b>start</b> whose purpose is <b>purpose</b> is purpose, and where
+ * <b>digest</b> (if set) matches the rend_pk_digest field. Return NULL if no
+ * circuit is found. If <b>start</b> is NULL, begin at the start of the list.
*/
origin_circuit_t *
circuit_get_next_by_pk_and_purpose(origin_circuit_t *start,
@@ -666,7 +664,9 @@
return NULL;
}
-/* DOCDOC */
+/** Return the first OR circuit in the global list whose purpose is
+ * <b>purpose</b>, and whose rend_token is the <b>len</b>-byte
+ * <b>token</b>. */
static or_circuit_t *
circuit_get_by_rend_token_and_purpose(uint8_t purpose, const char *token,
size_t len)
Modified: tor/trunk/src/or/connection_edge.c
===================================================================
--- tor/trunk/src/or/connection_edge.c 2007-02-02 18:58:04 UTC (rev 9475)
+++ tor/trunk/src/or/connection_edge.c 2007-02-02 18:58:11 UTC (rev 9476)
@@ -632,7 +632,8 @@
}
}
-/* DOCDOC */
+/** Remove <b>ent</b> (which must be mapped to by <b>address</b>) from the
+ * client address maps. */
static void
addressmap_ent_remove(const char *address, addressmap_entry_t *ent)
{
@@ -708,7 +709,9 @@
/* it's fine to rewrite a rewrite, but don't loop forever */
}
-/* DOCDOC */
+/** If we have a cached reverse DNS entry for the address stored in the
+ * <b>maxlen</b>-byte buffer <b>address</b> (typically, a dotted quad) with
+ * the cached value and return 1. Otherwise return 0. */
static int
addressmap_rewrite_reverse(char *address, size_t maxlen)
{
@@ -898,7 +901,15 @@
client_dns_set_addressmap_impl(address, valbuf, exitname, ttl);
}
-/** DOCDOC */
+/** Add a cache entry noting that <b>address</b> (ordinarily a dotted quad)
+ * resolved via a RESOLVE_PTR request to the hostname <b>v</b>.
+ *
+ * If <b>exitname</b> is defined, then append the addresses with
+ * ".exitname.exit" before registering the mapping.
+ *
+ * If <b>ttl</b> is nonnegative, the mapping will be valid for
+ * <b>ttl</b>seconds; otherwise, we use the default.
+ */
static void
client_dns_set_reverse_addressmap(const char *address, const char *v,
const char *exitname,
@@ -2003,11 +2014,10 @@
* socks version, etc, and mark <b>conn</b> as completed with SOCKS
* handshaking.
*
- * If <b>reply</b> is defined, then write <b>replylen</b> bytes of it
- * to conn and return, else reply based on <b>status</b>.
- *
- * If <b>reply</b> is undefined, <b>status</b> can't be 0.
- * DOCDOC endreason
+ * If <b>reply</b> is defined, then write <b>replylen</b> bytes of it to conn
+ * and return, else reply based on <b>endreason</b> (one of
+ * END_STREAM_REASON_*). If <b>reply</b> is undefined, <b>endreason</b> can't 0
+ * or REASON_DONE. Send endreason to the controller, if appropriate.
*/
void
connection_ap_handshake_socks_reply(edge_connection_t *conn, char *reply,
Modified: tor/trunk/src/or/control.c
===================================================================
--- tor/trunk/src/or/control.c 2007-02-02 18:58:04 UTC (rev 9475)
+++ tor/trunk/src/or/control.c 2007-02-02 18:58:11 UTC (rev 9476)
@@ -631,7 +631,13 @@
/* Send an event to all v1 controllers that are listening for code
* <b>event</b>. The event's body is given by <b>msg</b>.
*
- * docdoc which, is_extended */
+ * If <b>which</b> & SHORT_NAMES, the event contains short-format names: send
+ * it to controllers that haven't enabled the VERBOSE_NAMES feature. If
+ * <b>which</b> & LONG_NAMES, the event contains long-format names: sent it
+ * to contollers that <em>have</em> enabled VERBOSE_NAMES.
+ *
+ * The EXTENDED_FORMAT and NONEXTENDED_FORMAT flags behaves similarly with
+ * respect to the EXTENDED_EVENTS feature. */
static void
send_control1_event_string(uint16_t event, event_format_t which,
const char *msg)
@@ -3118,7 +3124,8 @@
return 0;
}
-/* DOCDOC */
+/** Convert the reason for ending a stream <b>reason</b> into the format used
+ * in STREAM events. Return NULL if the reason is unrecognized.*/
static const char *
stream_end_reason_to_string(int reason)
{
@@ -3585,7 +3592,8 @@
return 0;
}
-/* DOCDOC takes a list of local_routerstatus_t */
+/** Called when the local_routerstatus_ts <b>statuses</b> have changed: sends
+ * an NS event to any controller that cares. */
int
control_event_networkstatus_changed(smartlist_t *statuses)
{
@@ -3612,7 +3620,8 @@
return 0;
}
-/* DOCDOC */
+/** Called when a single local_routerstatus_t has changed: Sends an NS event
+ * to any countroller that cares. */
int
control_event_networkstatus_changed_single(local_routerstatus_t *rs)
{
@@ -3638,7 +3647,10 @@
return 0;
}
-/* DOCDOC */
+/** Helper: sents a status event where <b>type</b> is one of
+ * EVENT_STATUS_{GENERAL,CLIENT,SERVER}, where <b>severity</b> is one of
+ * LOG_{NOTICE,WARN,ERR}, and where <b>format</b> is a print-style format
+ * string corresponding to <b>args</b>. */
static int
control_event_status(int type, int severity, const char *format, va_list args)
{
@@ -3683,7 +3695,8 @@
return 0;
}
-/* DOCDOC */
+/** Format and send an EVENT_STATUS_GENERAL event whose main text is obtained
+ * by formatting the arguments using the printf-style <b>format</b> */
int
control_event_general_status(int severity, const char *format, ...)
{
@@ -3698,7 +3711,8 @@
return r;
}
-/* DOCDOC */
+/** Format and send an EVENT_STATUS_CLIENT event whose main text is obtained
+ * by formatting the arguments using the printf-style <b>format</b> */
int
control_event_client_status(int severity, const char *format, ...)
{
@@ -3713,7 +3727,8 @@
return r;
}
-/* DOCDOC */
+/** Format and send an EVENT_STATUS_SERVER event whose main text is obtained
+ * by formatting the arguments using the printf-style <b>format</b> */
int
control_event_server_status(int severity, const char *format, ...)
{
@@ -3728,7 +3743,9 @@
return r;
}
-/** DOCDOC */
+/** Called when the status of an entry guard with the given <b>nickname</b>
+ * and identity <b>digest</b> has changed to <b>status</b>: tells any
+ * controllers that care. */
int
control_event_guard(const char *nickname, const char *digest,
const char *status)
Modified: tor/trunk/src/or/directory.c
===================================================================
--- tor/trunk/src/or/directory.c 2007-02-02 18:58:04 UTC (rev 9475)
+++ tor/trunk/src/or/directory.c 2007-02-02 18:58:11 UTC (rev 9476)
@@ -1444,10 +1444,13 @@
#undef INSTRUMENT_DOWNLOADS
#ifdef INSTRUMENT_DOWNLOADS
-/** DOCDOC */
+/** Map used to keep track of how much data we've up/downloaded in what kind
+ * of request. Maps from request type to pointer to uint64_t. */
static strmap_t *request_bytes_map = NULL;
-/** DOCDOC */
+/** Called when we just transmitted or received <b>bytes</b> worth of data
+ * because of a request of type <b>key</b> (an arbitrary identifier): adds
+ * <b>bytes</b> to the total associated with key. */
static void
note_request(const char *key, size_t bytes)
{
@@ -1463,7 +1466,8 @@
*n += bytes;
}
-/** DOCDOC */
+/** Return a newly allocated string holding a summary of bytes used per
+ * request type. */
char *
directory_dump_request_log(void)
{
Modified: tor/trunk/src/or/routerlist.c
===================================================================
--- tor/trunk/src/or/routerlist.c 2007-02-02 18:58:04 UTC (rev 9475)
+++ tor/trunk/src/or/routerlist.c 2007-02-02 18:58:11 UTC (rev 9476)
@@ -906,6 +906,7 @@
* If <b>need_uptime</b> is non-zero, we require a minimum uptime.
* If <b>need_capacity</b> is non-zero, we require a minimum advertised
* bandwidth.
+ * If <b>need_guard</b>, we require that the router is a possible entry guard.
*/
int
router_is_unreliable(routerinfo_t *router, int need_uptime,
@@ -939,7 +940,10 @@
* If <b>statuses</b> is zero, then <b>sl</b> is a list of
* routerinfo_t's. Otherwise it's a list of routerstatus_t's.
*
- * DOCDOC for_exit
+ * If <b>for_exit</b>, we're picking an exit node: consider all nodes'
+ * bandwidth equally regardless of their Exit status. If not <b>for_exit</b>,
+ * we're picking a non-exit node: weight exit-node's bandwidth downwards
+ * depending on the smallness of the fraction of Exit-to-total bandwidth.
*/
static void *
smartlist_choose_by_bandwidth(smartlist_t *sl, int for_exit, int statuses)
@@ -972,6 +976,9 @@
this_bw = status->is_fast ? 40000 : 20000;
else /* assume it'll be the average we've seen so far */
this_bw = (uint32_t)(partial/i);
+ /*XXXX012 The above calculation is an awful hack, and makes our
+ * algorithm hard to describe sanely. Could we do better with a second
+ * pass through the list? -NM */
}
} else {
router = smartlist_get(sl, i);
@@ -1063,8 +1070,11 @@
* a minimum uptime, return one of those.
* If <b>need_capacity</b> is non-zero, weight your choice by the
* advertised capacity of each router.
- *
- * DOCDOC allow_invalid, need_guard, weight_for_exit
+ * If ! <b>allow_invalid</b>, consider only Valid routers.
+ * If <b>need_guard</b>, consider only Guard routers.
+ * If <b>weight_for_exit</b>, we weight bandwidths as if picking an exit node,
+ * otherwise we weight bandwidths for picking a relay node (that is, possibly
+ * discounting exit nodes).
*/
routerinfo_t *
router_choose_random_node(const char *preferred,
@@ -3782,15 +3792,13 @@
/** Initiate new router downloads as needed, using the strategy for
* non-directory-servers.
*
- * We only allow one router descriptor download at a time.
- * If we have less than two network-status documents, we ask
- * a directory for "all descriptors."
- * Otherwise, we ask for all descriptors that we think are different
- * from what we have.
+ * We don't launch any downloads if there are fewer than MAX_DL_TO_DELAY
+ * descriptors to get and less than MAX_CLIENT_INTERVAL_WITHOUT_REQUEST
+ * seconds have passed.
*
- * DOCDOC The above comment doesn't match the behavior of the function.
- * I guess one of them is wrong, and I guess it's the comment. -RD
- */
+ * Otherwise, we ask for all descriptors that we think are different from what
+ * we have, and that we don't currently have an in-progress download attempt
+ * for. */
static void
update_router_descriptor_client_downloads(time_t now)
{