[Author Prev][Author Next][Thread Prev][Thread Next][Author Index][Thread Index]
[or-cvs] r8256: Add some doxygen, concentrated in dns.c (in tor/trunk: . src/or)
Author: nickm
Date: 2006-08-27 23:16:02 -0400 (Sun, 27 Aug 2006)
New Revision: 8256
Modified:
tor/trunk/
tor/trunk/src/or/buffers.c
tor/trunk/src/or/dns.c
tor/trunk/src/or/eventdns.c
Log:
r8609@Kushana: nickm | 2006-08-27 17:24:27 -0400
Add some doxygen, concentrated in dns.c
Property changes on: tor/trunk
___________________________________________________________________
Name: svk:merge
- 17f730b7-d419-0410-b50f-85ee4b70197a:/local/or/tor/trunk:8290
1f724f9b-111a-0410-b636-93f1a77c1813:/local/or/tor/trunk:8207
96637b51-b116-0410-a10e-9941ebb49b64:/tor/branches/spec:7005
c95137ef-5f19-0410-b913-86e773d04f59:/tor/branches/eventdns:8608
c95137ef-5f19-0410-b913-86e773d04f59:/tor/branches/mmap:7030
c95137ef-5f19-0410-b913-86e773d04f59:/tor/branches/oo-connections:6950
c95137ef-5f19-0410-b913-86e773d04f59:/tor/branches/trans-ap:7315
c95137ef-5f19-0410-b913-86e773d04f59:/tor/trunk:8576
+ 17f730b7-d419-0410-b50f-85ee4b70197a:/local/or/tor/trunk:8290
1f724f9b-111a-0410-b636-93f1a77c1813:/local/or/tor/trunk:8207
96637b51-b116-0410-a10e-9941ebb49b64:/tor/branches/spec:7005
c95137ef-5f19-0410-b913-86e773d04f59:/tor/branches/eventdns:8609
c95137ef-5f19-0410-b913-86e773d04f59:/tor/branches/mmap:7030
c95137ef-5f19-0410-b913-86e773d04f59:/tor/branches/oo-connections:6950
c95137ef-5f19-0410-b913-86e773d04f59:/tor/branches/trans-ap:7315
c95137ef-5f19-0410-b913-86e773d04f59:/tor/trunk:8576
Modified: tor/trunk/src/or/buffers.c
===================================================================
--- tor/trunk/src/or/buffers.c 2006-08-28 03:15:55 UTC (rev 8255)
+++ tor/trunk/src/or/buffers.c 2006-08-28 03:16:02 UTC (rev 8256)
@@ -58,11 +58,15 @@
char *cur; /**< The first byte used for storing data in the buffer. */
size_t highwater; /**< Largest observed datalen since last buf_shrink */
size_t len; /**< Maximum amount of data that <b>mem</b> can hold. */
- size_t memsize; /**< DOCDOC */
+ size_t memsize; /**< How many bytes did we actually allocate? Can be less
+ * than 'len' if we shortened 'len' by a few bytes to make
+ * zlib wrap around more easily. */
size_t datalen; /**< Number of bytes currently in <b>mem</b>. */
};
+/** How many bytes, total, are used in all buffers? */
uint64_t buf_total_used = 0;
+/** How many bytes, total, are allocated in all buffers? */
uint64_t buf_total_alloc = 0;
/** Size, in bytes, for newly allocated buffers. Should be a power of 2. */
@@ -1292,7 +1296,10 @@
return 1;
}
-/** DOCDOC */
+/** Compress on uncompress the <b>data_len</b> bytes in <b>data</b> using the
+ * zlib state <b>state</b>, appending the result to <b>buf</b>. If
+ * <b>done</b> is true, flush the data in the state and finish the
+ * compression/uncompression. Return -1 on failure, 0 on success. */
int
write_to_buf_zlib(buf_t *buf, tor_zlib_state_t *state,
const char *data, size_t data_len,
Modified: tor/trunk/src/or/dns.c
===================================================================
--- tor/trunk/src/or/dns.c 2006-08-28 03:15:55 UTC (rev 8255)
+++ tor/trunk/src/or/dns.c 2006-08-28 03:16:02 UTC (rev 8256)
@@ -51,6 +51,15 @@
static int num_dnsworkers_busy=0;
/** When did we last rotate the dnsworkers? */
static time_t last_rotation_time=0;
+#else
+/** Have we currently configured nameservers with eventdns? */
+static int nameservers_configured = 0;
+/** What was the resolv_conf fname we last used when configuring the
+ * nameservers? Used to check whether we need to reconfigure. */
+static char *resolv_conf_fname = NULL;
+/** What was the mtime on the resolv.conf file we last used when configuring
+ * the nameservers? Used to check whether we need to reconfigure. */
+static time_t resolv_conf_mtime = 0;
#endif
/** Linked list of connections waiting for a DNS answer. */
@@ -92,6 +101,7 @@
uint8_t state; /**< Is this cached entry pending/done/valid/failed? */
time_t expire; /**< Remove items from cache after this time. */
uint32_t ttl; /**< What TTL did the nameserver tell us? */
+ /** Connections that want to know when we get an answer for this resolve. */
pending_connection_t *pending_connections;
} cached_resolve_t;
@@ -116,13 +126,6 @@
#endif
static void assert_resolve_ok(cached_resolve_t *resolve);
-#ifdef USE_EVENTDNS
-/* DOCDOC */
-static int nameservers_configured = 0;
-static char *resolv_conf_fname = NULL;
-static time_t resolv_conf_mtime = 0;
-#endif
-
/** Hash table of cached_resolve objects. */
static HT_HEAD(cache_map, cached_resolve_t) cache_root;
@@ -136,6 +139,7 @@
return !strncmp(a->address, b->address, MAX_ADDRESSLEN);
}
+/** Hash function for cached_resolve objects */
static INLINE unsigned int
cached_resolve_hash(cached_resolve_t *a)
{
@@ -155,6 +159,7 @@
}
#ifdef USE_EVENTDNS
+/** Helper: called by eventdns when eventdns wants to log something. */
static void
eventdns_log_cb(int warn, const char *msg)
{
@@ -162,6 +167,8 @@
get_options()->SafeLogging) {
log(LOG_INFO, LD_EXIT, "eventdns: Resolve requested.");
return;
+ } else if (!strcmpstart(msg, "Search: ")) {
+ return;
}
log(warn?LOG_WARN:LOG_INFO, LD_EXIT, "eventdns: %s", msg);
}
@@ -181,7 +188,7 @@
return 0;
}
-/* DOCDOC */
+/** Called when DNS-related options change (or may have changed) */
void
dns_reset(void)
{
@@ -203,6 +210,8 @@
#endif
}
+/** Helper: Given a TTL from a DNS response, determine what TTL to give the
+ * OP that asked us to resolve it. */
uint32_t
dns_clip_ttl(uint32_t ttl)
{
@@ -214,6 +223,8 @@
return ttl;
}
+/** Helper: Given a TTL from a DNS response, determine how long to hold it in
+ * our cache. */
static uint32_t
dns_get_expiry_ttl(uint32_t ttl)
{
@@ -266,7 +277,7 @@
resolve);
}
-/** Free all storage held in the DNS cache */
+/** Free all storage held in the DNS cache and related structures. */
void
dns_free_all(void)
{
@@ -280,6 +291,9 @@
if (cached_resolve_pqueue)
smartlist_free(cached_resolve_pqueue);
cached_resolve_pqueue = NULL;
+#ifdef USE_EVENTDNS
+ tor_free(resolv_conf_fname);
+#endif
}
/** Remove every cached_resolve whose <b>expire</b> time is before <b>now</b>
@@ -660,6 +674,9 @@
tor_free(resolve);
}
+/** Helper: adds an entry to the DNS cache mapping <b>address</b> to the ipv4
+ * address 'addr'. 'ttl is a cache ttl; 'outcome' is one of
+ * DNS_RESOLVE_{FAILED_TRANSIENT|FAILED_PERMANENT|SUCCEEDED}. */
static void
add_answer_to_cache(const char *address, uint32_t addr, char outcome,
uint32_t ttl)
@@ -680,11 +697,11 @@
set_expiry(resolve, time(NULL) + dns_get_expiry_ttl(ttl));
}
-/** Called on the OR side when a DNS worker tells us the outcome of a DNS
- * resolve: tell all pending connections about the result of the lookup, and
- * cache the value. (<b>address</b> is a NUL-terminated string containing the
- * address to look up; <b>addr</b> is an IPv4 address in host order;
- * <b>outcome</b> is one of
+/** Called on the OR side when a DNS worker or the eventdns library tells us
+ * the outcome of a DNS resolve: tell all pending connections about the result
+ * of the lookup, and cache the value. (<b>address</b> is a NUL-terminated
+ * string containing the address to look up; <b>addr</b> is an IPv4 address in
+ * host order; <b>outcome</b> is one of
* DNS_RESOLVE_{FAILED_TRANSIENT|FAILED_PERMANENT|SUCCEEDED}.
*/
static void
@@ -862,6 +879,8 @@
return 0;
}
+/** Called when a connection to a dnsworker hits an EOF; this only happens
+ * when a dnsworker dies unexpectedly. */
int
connection_dns_reached_eof(connection_t *conn)
{
@@ -1180,6 +1199,9 @@
return 0;
}
#else /* !USE_EVENTDNS */
+
+/** Eventdns helper: return true iff the eventdns result <b>err</b> is
+ * a transient failure. */
static int
eventdns_err_is_transient(int err)
{
@@ -1193,6 +1215,7 @@
return 0;
}
}
+/* Dummy function; never called with eventdns enabled. */
int
connection_dns_finished_flushing(connection_t *conn)
{
@@ -1200,6 +1223,7 @@
tor_assert(0);
return 0;
}
+/* Dummy function; never called with eventdns enabled. */
int
connection_dns_process_inbuf(connection_t *conn)
{
@@ -1207,6 +1231,7 @@
tor_assert(0);
return 0;
}
+/* Dummy function; never called with eventdns enabled. */
int
connection_dns_reached_eof(connection_t *conn)
{
@@ -1215,7 +1240,11 @@
return 0;
}
-/* DOCDOC */
+/** Configure eventdns nameservers if force is true, or if the configuration
+ * has changed since the last time we called this function. On Unix, this
+ * reads from options->ResolvConf or /etc/resolv.conf; on Windows, this reads
+ * from options->ResolvConf or the registry. Return 0 on success or -1 on
+ * failure. */
static int
configure_nameservers(int force)
{
@@ -1283,7 +1312,9 @@
return 0;
}
-/* XXX DOCDOC */
+/** For eventdns: Called when we get an answer for a request we launched.
+ * See eventdns.h for arguments; 'arg' holds the address we tried to resolve.
+ */
static void
eventdns_callback(int result, char type, int count, int ttl, void *addresses,
void *arg)
@@ -1318,16 +1349,21 @@
tor_free(string_address);
}
-/* XXX DOCDOC */
+/** For eventdns: start resolving as necessary to find the target for
+ * <b>exitconn</b> */
static int
launch_resolve(edge_connection_t *exitconn)
{
char *addr = tor_strdup(exitconn->_base.address);
int r;
int options = get_options()->SearchDomains ? 0 : DNS_QUERY_NO_SEARCH;
- if (!nameservers_configured)
+ /* What? Nameservers not configured? Sounds like a bug. */
+ if (!nameservers_configured) {
+ log_warn(LD_EXIT, "Harmless bug: nameservers not configured, but resolve "
+ "launched. Configuring.");
if (configure_nameservers(1) < 0)
return -1;
+ }
log_info(LD_EXIT, "Launching eventdns request for %s",
escaped_safe_str(exitconn->_base.address));
r = eventdns_resolve_ipv4(exitconn->_base.address, options,
@@ -1350,6 +1386,7 @@
}
#endif /* USE_EVENTDNS */
+/** Exit with an assertion if <b>resolve</b> is corrupt. */
static void
assert_resolve_ok(cached_resolve_t *resolve)
{
@@ -1368,6 +1405,7 @@
}
#ifdef DEBUG_DNS_CACHE
+/** Exit with an assertion if the DNS cache is corrupt. */
static void
_assert_cache_ok(void)
{
Modified: tor/trunk/src/or/eventdns.c
===================================================================
--- tor/trunk/src/or/eventdns.c 2006-08-28 03:15:55 UTC (rev 8255)
+++ tor/trunk/src/or/eventdns.c 2006-08-28 03:16:02 UTC (rev 8256)
@@ -1579,7 +1579,7 @@
(int)(u8)((a>>8 )&0xff),
(int)(u8)((a>>16)&0xff),
(int)(u8)((a>>24)&0xff));
- log(0, "reverse resolve requested for %s", buf);
+ log(0, "Resolve requested for %s (reverse)", buf);
req = request_new(TYPE_PTR, buf, flags, callback, ptr);
if (!req) return 1;
request_submit(req);