[Author Prev][Author Next][Thread Prev][Thread Next][Author Index][Thread Index]
[or-cvs] r8536: Doxygen comments for code in common. Also simplify a few cod (in tor/trunk: . src/common)
- To: or-cvs@xxxxxxxxxxxxx
- Subject: [or-cvs] r8536: Doxygen comments for code in common. Also simplify a few cod (in tor/trunk: . src/common)
- From: nickm@xxxxxxxx
- Date: Fri, 29 Sep 2006 14:13:38 -0400 (EDT)
- Delivered-to: archiver@seul.org
- Delivered-to: or-cvs-outgoing@seul.org
- Delivered-to: or-cvs@seul.org
- Delivery-date: Fri, 29 Sep 2006 14:13:45 -0400
- Reply-to: or-talk@xxxxxxxxxxxxx
- Sender: owner-or-cvs@xxxxxxxxxxxxx
Author: nickm
Date: 2006-09-29 14:13:37 -0400 (Fri, 29 Sep 2006)
New Revision: 8536
Modified:
tor/trunk/
tor/trunk/src/common/container.c
tor/trunk/src/common/crypto.c
tor/trunk/src/common/log.c
tor/trunk/src/common/torgzip.c
tor/trunk/src/common/util.c
Log:
r9008@Kushana: nickm | 2006-09-29 13:50:10 -0400
Doxygen comments for code in common. Also simplify a few code paths to be more clear/speedy/correct.
Property changes on: tor/trunk
___________________________________________________________________
svk:merge ticket from /tor/trunk [r9008] on c95137ef-5f19-0410-b913-86e773d04f59
Modified: tor/trunk/src/common/container.c
===================================================================
--- tor/trunk/src/common/container.c 2006-09-29 18:13:33 UTC (rev 8535)
+++ tor/trunk/src/common/container.c 2006-09-29 18:13:37 UTC (rev 8536)
@@ -493,10 +493,23 @@
smartlist_uniq(sl, _compare_string_ptrs, NULL);
}
-#define LEFT_CHILD(i) ( ((i)+1)*2 - 1)
-#define RIGHT_CHILD(i) ( ((i)+1)*2 )
-#define PARENT(i) ( ((i)+1)/2 - 1)
+/* Heap-based priority queue implementation for O(lg N) insert and remove.
+ * Recall that the heap property is that, for every index I, h[I] <
+ * H[LEFT_CHILD[I]] and h[I] < H[RIGHT_CHILD[I]].
+ */
+/* For a 1-indexed array, we would use LEFT_CHILD[x] = 2*x and RIGHT_CHILD[x]
+ * = 2*x + 1. But this is C, so we have to adjust a little. */
+//#define LEFT_CHILD(i) ( ((i)+1)*2 - 1)
+//#define RIGHT_CHILD(i) ( ((i)+1)*2 )
+//#define PARENT(i) ( ((i)+1)/2 - 1)
+#define LEFT_CHILD(i) ( 2*(i) + 1 )
+#define RIGHT_CHILD(i) ( 2*(i) + 2 )
+#define PARENT(i) ( ((i)-1) / 2 )
+
+/** Helper. <b>sl</b> may have at most one violation of the heap property:
+ * the item at <b>idx</b> may be greater than one or both of its children.
+ * Restore the heap property. */
static INLINE void
smartlist_heapify(smartlist_t *sl,
int (*compare)(const void *a, const void *b),
@@ -528,6 +541,8 @@
}
}
+/** Insert <b>item</b> into the heap stored in <b>sl</b>, where order
+ * is determined by <b>compare</b> */
void
smartlist_pqueue_add(smartlist_t *sl,
int (*compare)(const void *a, const void *b),
@@ -549,6 +564,9 @@
}
}
+/** Remove and return the top-priority item from the heap stored in <b>sl</b>,
+ * where order is determined by <b>compare</b>. <b>sl</b> must not be
+ * empty. */
void *
smartlist_pqueue_pop(smartlist_t *sl,
int (*compare)(const void *a, const void *b))
@@ -564,6 +582,8 @@
return top;
}
+/** Assert that the heap property is correctly maintained by the heap stored
+ * in <b>sl</b>, where order is determined by <b>compare</b>. */
void
smartlist_pqueue_assert_ok(smartlist_t *sl,
int (*compare)(const void *a, const void *b))
@@ -609,13 +629,14 @@
DEFINE_MAP_STRUCTS(strmap_t, char *key, strmap_);
DEFINE_MAP_STRUCTS(digestmap_t, char key[DIGEST_LEN], digestmap_);
-/** Helper: compare strmap_t_entry objects by key value. */
+/** Helper: compare strmap_entry_t objects by key value. */
static INLINE int
strmap_entries_eq(strmap_entry_t *a, strmap_entry_t *b)
{
return !strcmp(a->key, b->key);
}
+/** Helper: return a hash value for a strmap_entry_t */
static INLINE unsigned int
strmap_entry_hash(strmap_entry_t *a)
{
@@ -629,6 +650,7 @@
return !memcmp(a->key, b->key, DIGEST_LEN);
}
+/** Helper: return a hash value for a digest_map_t */
static INLINE unsigned int
digestmap_entry_hash(digestmap_entry_t *a)
{
@@ -1029,6 +1051,7 @@
return HT_EMPTY(&map->head);
}
+/** Return the number of items in <b>map</b> */
int
strmap_size(strmap_t *map)
{
Modified: tor/trunk/src/common/crypto.c
===================================================================
--- tor/trunk/src/common/crypto.c 2006-09-29 18:13:33 UTC (rev 8535)
+++ tor/trunk/src/common/crypto.c 2006-09-29 18:13:37 UTC (rev 8536)
@@ -77,7 +77,9 @@
#define PRIVATE_KEY_OK(k) ((k) && (k)->key && (k)->key->p)
#ifdef TOR_IS_MULTITHREADED
+/** A number of prealloced mutexes for use by openssl. */
static tor_mutex_t **_openssl_mutexes = NULL;
+/** How many mutexes have we allocated for use by openssl? */
static int _n_openssl_mutexes = -1;
#endif
@@ -164,6 +166,7 @@
}
#ifndef NO_ENGINES
+/** Log any OpenSSL engines we're using at NOTICE. */
static void
log_engine(const char *fn, ENGINE *e)
{
@@ -1711,6 +1714,9 @@
return ret;
}
+/** Base-64 encode DIGEST_LINE bytes from <b>digest</b>, remove the trailing =
+ * and newline characters, and store the nul-terminated result in the first
+ * BASE64_DIGEST_LEN+1 bytes of <b>d64</b>. */
int
digest_to_base64(char *d64, const char *digest)
{
@@ -1721,6 +1727,9 @@
return 0;
}
+/** Given a base-64 encoded, nul-terminated digest in <b>d64</b> (without
+ * trailing newline or = characters), decode it and store the result in the
+ * first DIGEST_LEN bytes at <b>digest</b>. */
int
digest_from_base64(char *digest, const char *d64)
{
@@ -1803,6 +1812,7 @@
}
#ifdef TOR_IS_MULTITHREADED
+/** Helper: openssl uses this callback to manipulate mutexes. */
static void
_openssl_locking_cb(int mode, int n, const char *file, int line)
{
@@ -1819,6 +1829,8 @@
tor_mutex_release(_openssl_mutexes[n]);
}
+/** Helper: Construct mutexes, and set callbacks to help OpenSSL handle being
+ * multithreaded. */
static int
setup_openssl_threading(void)
{
Modified: tor/trunk/src/common/log.c
===================================================================
--- tor/trunk/src/common/log.c 2006-09-29 18:13:33 UTC (rev 8535)
+++ tor/trunk/src/common/log.c 2006-09-29 18:13:37 UTC (rev 8536)
@@ -60,8 +60,7 @@
}
}
-/** Helper: decide whether to include the function name in the log message.
- * */
+/** Helper: decide whether to include the function name in the log message. */
static INLINE int
should_log_function_name(uint32_t domain, int severity)
{
@@ -434,6 +433,8 @@
return 0;
}
+/** Adjust the configured severity of any logs whose callback function is
+ * <b>cb</b>. */
void
change_callback_log_severity(int loglevelMin, int loglevelMax,
log_callback cb)
@@ -577,7 +578,10 @@
}
#ifdef HAVE_EVENT_SET_LOG_CALLBACK
+/** A string which, if it appears in a libevent log, should be ignored. */
static const char *suppress_msg = NULL;
+/** Callback function passed to event_set_log() so we can intercept
+ * log messages from libevent. */
static void
libevent_logging_callback(int severity, const char *msg)
{
@@ -608,11 +612,13 @@
break;
}
}
+/** Set hook to intercept log messages from libevent. */
void
configure_libevent_logging(void)
{
event_set_log_callback(libevent_logging_callback);
}
+/** Ignore any libevent log message that contains <b>msg</b> */
void
suppress_libevent_log_msg(const char *msg)
{
Modified: tor/trunk/src/common/torgzip.c
===================================================================
--- tor/trunk/src/common/torgzip.c 2006-09-29 18:13:33 UTC (rev 8535)
+++ tor/trunk/src/common/torgzip.c 2006-09-29 18:13:37 UTC (rev 8536)
@@ -29,6 +29,8 @@
#include "log.h"
#include "torgzip.h"
+/** Set to 1 if zlib is a version that supports gzip; set to 0 if it doesn't;
+ * set to -1 if we haven't checked yet. */
static int gzip_is_supported = -1;
/** Return true iff we support gzip-based compression. Otherwise, we need to
@@ -49,6 +51,7 @@
return gzip_is_supported;
}
+/** Return the 'bits' value to tell zlib to use <b>method</b>.*/
static INLINE int
method_bits(compress_method_t method)
{
@@ -152,6 +155,10 @@
* buffer, using the method described in <b>method</b>. Store the uncompressed
* string in *<b>out</b>, and its length in *<b>out_len</b>. Return 0 on
* success, -1 on failure.
+ *
+ * If <b>complete_only</b> is true, we consider a truncated input as a
+ * failure; otherwise we decompress as much as we can. Warn about truncated
+ * or corrupt inputs at <b>protocol_warn_level</b>.
*/
int
tor_gzip_uncompress(char **out, size_t *out_len,
@@ -287,7 +294,9 @@
int compress;
};
-/** DOCDOC */
+/** Construct and return a tor_zlib_state_t object using <b>method</b>. If
+ * <b>compress</b>, it's for compression; otherwise it's for
+ * decompression. */
tor_zlib_state_t *
tor_zlib_new(int compress, compress_method_t method)
{
@@ -319,7 +328,16 @@
return NULL;
}
-/** DOCDOC */
+/** Compress/decommpress some bytes using <b>state</b>. Read up to
+ * *<b>in_len</b> bytes from *<b>in</b>, and write up to *<b>out_len</b> bytes
+ * to *<b>out</b>, adjusting the values as we go. If <b>finish</b> is true,
+ * we've reached the end of the input.
+ *
+ * Return TOR_ZLIB_DONE if we've finished the entire compression/decompression.
+ * Return TOR_ZLIB_OK if we're processed everything from the input.
+ * Return TOR_ZLIB_BUF_FULL if we're out of space on <b>out</b>.
+ * Return TOR_ZLIB_ERR if the stream is corrupt.
+ */
tor_zlib_output_t
tor_zlib_process(tor_zlib_state_t *state,
char **out, size_t *out_len,
@@ -349,7 +367,7 @@
return TOR_ZLIB_DONE;
case Z_BUF_ERROR:
if (state->stream.avail_in == 0)
- return Z_OK;
+ return TOR_ZLIB_OK;
return TOR_ZLIB_BUF_FULL;
case Z_OK:
if (state->stream.avail_out == 0 || finish)
@@ -362,7 +380,7 @@
}
}
-/** DOCDOC */
+/** Deallocate <b>state</b>. */
void
tor_zlib_free(tor_zlib_state_t *state)
{
Modified: tor/trunk/src/common/util.c
===================================================================
--- tor/trunk/src/common/util.c 2006-09-29 18:13:33 UTC (rev 8535)
+++ tor/trunk/src/common/util.c 2006-09-29 18:13:37 UTC (rev 8536)
@@ -493,6 +493,8 @@
return tor_mem_is_zero(digest, DIGEST_LEN);
}
+/* Helper: common code to check whether the result of a strtol or strtoul or
+ * strtoll is correct. */
#define CHECK_STRTOX_RESULT() \
/* Was at least one character converted? */ \
if (endptr == s) \
@@ -530,6 +532,7 @@
CHECK_STRTOX_RESULT();
}
+/** As tor_parse_log, but return an unsigned long */
unsigned long
tor_parse_ulong(const char *s, int base, unsigned long min,
unsigned long max, int *ok, char **next)
@@ -541,7 +544,8 @@
CHECK_STRTOX_RESULT();
}
-/** Only base 10 is guaranteed to work for now. */
+/** As tor_parse_log, but return a unit64_t. Only base 10 is guaranteed to
+ * work for now. */
uint64_t
tor_parse_uint64(const char *s, int base, uint64_t min,
uint64_t max, int *ok, char **next)
@@ -570,6 +574,10 @@
CHECK_STRTOX_RESULT();
}
+/** Encode the <b>srclen</b> bytes at <b>src</b> in a NUL-terminated,
+ * uppercase hexadecimal string; store it in the <b>destlen</b>-byte buffer
+ * <b>dest</b>.
+ */
void
base16_encode(char *dest, size_t destlen, const char *src, size_t srclen)
{
@@ -589,23 +597,35 @@
*cp = '\0';
}
-static const char HEX_DIGITS[] = "0123456789ABCDEFabcdef";
-
+/** Helper: given a hex digit, return its value, or -1 if it isn't hex. */
static INLINE int
hex_decode_digit(char c)
{
- const char *cp;
- int n;
- cp = strchr(HEX_DIGITS, c);
- if (!cp)
- return -1;
- n = cp-HEX_DIGITS;
- if (n<=15)
- return n; /* digit or uppercase */
- else
- return n-6; /* lowercase */
+ switch (c) {
+ case '0': return 0;
+ case '1': return 1;
+ case '2': return 2;
+ case '3': return 3;
+ case '4': return 4;
+ case '5': return 5;
+ case '6': return 6;
+ case '7': return 7;
+ case '8': return 8;
+ case '9': return 9;
+ case 'A': case 'a': return 10;
+ case 'B': case 'b': return 11;
+ case 'C': case 'c': return 12;
+ case 'D': case 'd': return 13;
+ case 'E': case 'e': return 14;
+ case 'F': case 'f': return 15;
+ default:
+ return -1;
+ }
}
+/** Given a hexadecimal string of <b>srclen</b> bytes in <b>src/b>, decode it
+ * and store the result in the <b>destlen</b>-byte buffer at <b>dest</b>.
+ * Return 0 on success, -1 on failure. */
int
base16_decode(char *dest, size_t destlen, const char *src, size_t srclen)
{
@@ -832,6 +852,11 @@
{ "Jan", "Feb", "Mar", "Apr", "May", "Jun",
"Jul", "Aug", "Sep", "Oct", "Nov", "Dec" };
+/** Set <b>buf</b> to the RFC1123 encoding of the GMT value of <b>t</b>.
+ * The buffer must be at least RFC1123_TIME_LEN+1 bytes long.
+ *
+ * (RFC1123 format is Fri, 29 Sep 2006 15:54:20 GMT)
+ */
void
format_rfc1123_time(char *buf, time_t t)
{
@@ -848,6 +873,11 @@
memcpy(buf+8, MONTH_NAMES[tm.tm_mon], 3);
}
+/** Parse the the RFC1123 encoding of some time (in GMT) from <b>buf</b>,
+ * and store the result in *<b>t</b>.
+ *
+ * Return 0 on succcess, -1 on failure.
+*/
int
parse_rfc1123_time(const char *buf, time_t *t)
{
@@ -896,6 +926,11 @@
return 0;
}
+/** Set <b>buf</b> to the ISO???? encoding of the local value of <b>t</b>.
+ * The buffer must be at least ISO_TIME_LEN+1 bytes long.
+ *
+ * (ISO???? format is 2006-10-29 10:57:20)
+ */
void
format_local_iso_time(char *buf, time_t t)
{
@@ -903,6 +938,9 @@
strftime(buf, ISO_TIME_LEN+1, "%Y-%m-%d %H:%M:%S", tor_localtime_r(&t, &tm));
}
+/** Set <b>buf</b> to the ISO???? encoding of the GMT value of <b>t</b>.
+ * The buffer must be at least ISO_TIME_LEN+1 bytes long.
+ */
void
format_iso_time(char *buf, time_t t)
{
@@ -1149,7 +1187,10 @@
return write_bytes_to_file(fname, str, strlen(str), bin);
}
-/* DOCDOC */
+/** Helper: given a set of flags as passed to open(2), open the file
+ * <b>fname</b> and write all the sized_chunk_t structs in <b>chunks</t> to
+ * the file. Do so as atomically as possible e.g. by opening temp files and
+ * renaming. */
static int
write_chunks_to_file_impl(const char *fname, const smartlist_t *chunks,
int open_flags)
@@ -1204,7 +1245,8 @@
return -1;
}
-/* DOCDOC */
+/* Given a smartlist of sized_chunk_t, write them atomically to a file
+ * <b>fname</b>, overwriting or creating the file as necessary. */
int
write_chunks_to_file(const char *fname, const smartlist_t *chunks, int bin)
{
@@ -1228,7 +1270,8 @@
return r;
}
-/* DOCDOC */
+/** As write_bytes_to_file, but if the file already exists, append the bytes
+ * to the end of the file instead of overwriting it. */
int
append_bytes_to_file(const char *fname, const char *str, size_t len,
int bin)