From c6d4a00c5fac0ca22d1a24bc7fc37a6751b74a95 Mon Sep 17 00:00:00 2001 From: Roger Dingledine Date: Sun, 9 May 2004 16:47:25 +0000 Subject: [PATCH] more doxygen markup plenty more remains svn:r1824 --- src/or/buffers.c | 77 +++++++++++------------ src/or/command.c | 33 +++++----- src/or/connection_or.c | 62 ++++++++++--------- src/or/cpuworker.c | 42 +++++++------ src/or/directory.c | 29 ++++----- src/or/dirserv.c | 51 ++++++++-------- src/or/dns.c | 74 +++++++++++----------- src/or/main.c | 112 ++++++++++++++++----------------- src/or/rendclient.c | 32 +++++----- src/or/rendcommon.c | 32 +++++----- src/or/rendmid.c | 15 ++--- src/or/rendservice.c | 74 +++++++++++----------- src/or/router.c | 63 +++++++++---------- src/or/routerlist.c | 136 +++++++++++++++++++++-------------------- 14 files changed, 432 insertions(+), 400 deletions(-) diff --git a/src/or/buffers.c b/src/or/buffers.c index 880703d109..85921e3b50 100644 --- a/src/or/buffers.c +++ b/src/or/buffers.c @@ -1,4 +1,4 @@ -/* Copyright 2001,2002,2003 Roger Dingledine, Matej Pfajfar. */ +/* Copyright 2001 Matej Pfajfar, 2001-2004 Roger Dingledine. */ /* See LICENSE for licensing information */ /* $Id$ */ @@ -13,8 +13,8 @@ struct buf_t { uint32_t magic; /**< Magic cookie for debugging: Must be set to BUFFER_MAGIC */ char *mem; /**< Storage for data in the buffer */ - size_t len; /**< Maximum amount of data that 'mem' can hold. */ - size_t datalen; /**< Number of bytes currently in 'mem'. */ + size_t len; /**< Maximum amount of data that mem can hold. */ + size_t datalen; /**< Number of bytes currently in mem. */ }; /** Size, in bytes, for newly allocated buffers. Should be a power of 2. */ @@ -26,7 +26,7 @@ struct buf_t { * than this size. */ #define MIN_BUF_SHRINK_SIZE (16*1024) -/** Change a buffer's capacity. new_capacity must be \<= buf->datalen. */ +/** Change a buffer's capacity. new_capacity must be \<= buf->datalen. */ static INLINE void buf_resize(buf_t *buf, size_t new_capacity) { tor_assert(buf->datalen <= new_capacity); @@ -35,7 +35,7 @@ static INLINE void buf_resize(buf_t *buf, size_t new_capacity) buf->len = new_capacity; } -/** If the buffer is not large enough to hold "capacity" bytes, resize +/** If the buffer is not large enough to hold capacity bytes, resize * it so that it can. (The new size will be a power of 2 times the old * size.) */ @@ -82,7 +82,7 @@ static INLINE void buf_shrink_if_underfull(buf_t *buf) { buf_resize(buf, new_len); } -/** Remove the first 'n' bytes from buf. +/** Remove the first n bytes from buf. */ static INLINE void buf_remove_from_front(buf_t *buf, size_t n) { tor_assert(buf->datalen >= n); @@ -91,8 +91,8 @@ static INLINE void buf_remove_from_front(buf_t *buf, size_t n) { buf_shrink_if_underfull(buf); } -/** Find the first instance of the str_len byte string 'sr' on the - * buf_len byte string 'bufstr'. Strings are not necessary +/** Find the first instance of the str_len byte string str on the + * buf_len byte string bufstr. Strings are not necessary * NUL-terminated. If none exists, return -1. Otherwise, return index * of the first character in bufstr _after_ the first instance of str. */ @@ -116,7 +116,7 @@ static int find_mem_in_mem(const char *str, int str_len, return -1; } -/** Create and return a new buf with capacity 'size'. +/** Create and return a new buf with capacity size. */ buf_t *buf_new_with_capacity(size_t size) { buf_t *buf; @@ -137,33 +137,33 @@ buf_t *buf_new() return buf_new_with_capacity(INITIAL_BUF_SIZE); } -/** Remove all data from 'buf' */ +/** Remove all data from buf */ void buf_clear(buf_t *buf) { buf->datalen = 0; } -/** Return the number of bytes stored in 'buf' */ +/** Return the number of bytes stored in buf */ size_t buf_datalen(const buf_t *buf) { return buf->datalen; } -/** Return the maximum bytes that can be stored in 'buf' before buf +/** Return the maximum bytes that can be stored in buf before buf * needs to resize. */ size_t buf_capacity(const buf_t *buf) { return buf->len; } -/** For testing only: Return a pointer to the raw memory stored in 'buf'. +/** For testing only: Return a pointer to the raw memory stored in buf. */ const char *_buf_peek_raw_buffer(const buf_t *buf) { return buf->mem; } -/** Release storage held by 'buf'. +/** Release storage held by buf. */ void buf_free(buf_t *buf) { assert_buf_ok(buf); @@ -172,9 +172,9 @@ void buf_free(buf_t *buf) { tor_free(buf); } -/** Read from socket s, writing onto end of buf. Read at most - * 'at_most' bytes, resizing the buffer as necessary. If read() - * returns 0, set *reached_eof to 1 and return 0. Return -1 on error; +/** Read from socket s, writing onto end of buf. Read at most + * at_most bytes, resizing the buffer as necessary. If read() + * returns 0, set *reached_eof to 1 and return 0. Return -1 on error; * else return the number of bytes read. Return 0 if read() would * block. */ @@ -247,17 +247,14 @@ int read_to_buf_tls(tor_tls *tls, size_t at_most, buf_t *buf) { return r; } -/** Write data from 'buf' to the socket 's'. Write at most - * *buf_flushlen bytes, and decrement *buf_flushlen by the number of - * bytes actually written. Return the number of bytes written on - * success, -1 on failure. Return 0 if write() would block. +/** Write data from buf to the socket s. Write at most + * *buf_flushlen bytes, decrement *buf_flushlen by + * the number of bytes actually written, and remove the written bytes + * from the buffer. Return the number of bytes written on success, + * -1 on failure. Return 0 if write() would block. */ int flush_buf(int s, buf_t *buf, int *buf_flushlen) { - /* push from buf onto s - * then memmove to front of buf - * return -1 or how many bytes you just flushed */ - int write_result; assert_buf_ok(buf); @@ -306,7 +303,9 @@ int flush_buf_tls(tor_tls *tls, buf_t *buf, int *buf_flushlen) return r; } -/** Append string_len bytes from 'string' to the end of 'buf'. +/** Append string_len bytes from string to the end of + * buf. + * * Return the new length of the buffer on success, -1 on failure. */ int write_to_buf(const char *string, int string_len, buf_t *buf) { @@ -329,9 +328,8 @@ int write_to_buf(const char *string, int string_len, buf_t *buf) { return buf->datalen; } - -/* Remove string_len bytes from the front of 'buf', and store them - * into 'string'. Return the new buffer size. string_len must be <= +/** Remove string_len bytes from the front of buf, and store them + * into string. Return the new buffer size. string_len must be \<= * the number of bytes on the buffer. */ int fetch_from_buf(char *string, size_t string_len, buf_t *buf) { @@ -350,15 +348,15 @@ int fetch_from_buf(char *string, size_t string_len, buf_t *buf) { return buf->datalen; } -/** There is a (possibly incomplete) http statement on *buf, of the +/** There is a (possibly incomplete) http statement on buf, of the * form "\%s\\r\\n\\r\\n\%s", headers, body. (body may contain nuls.) * If a) the headers include a Content-Length field and all bytes in * the body are present, or b) there's no Content-Length field and * all headers are present, then: * - * - strdup headers into *headers_out, and nul-terminate it. - * - memdup body into *body_out, and nul-terminate it. - * - Then remove them from buf, and return 1. + * - strdup headers into *headers_out, and nul-terminate it. + * - memdup body into *body_out, and nul-terminate it. + * - Then remove them from buf, and return 1. * * - If headers or body is NULL, discard that part of the buf. * - If a headers or body doesn't fit in the arg, return -1. @@ -427,7 +425,7 @@ int fetch_from_buf_http(buf_t *buf, return 1; } -/** There is a (possibly incomplete) socks handshake on buf, of one +/** There is a (possibly incomplete) socks handshake on buf, of one * of the forms * - socks4: "socksheader username\\0" * - socks4a: "socksheader username\\0 destaddr\\0" @@ -435,16 +433,16 @@ int fetch_from_buf_http(buf_t *buf, * - socks5 phase two: "version command 0 addresstype..." * If it's a complete and valid handshake, and destaddr fits in * MAX_SOCKS_ADDR_LEN bytes, then pull the handshake off the buf, - * assign to req, and return 1. + * assign to req, and return 1. * * If it's invalid or too big, return -1. * * Else it's not all there yet, leave buf alone and return 0. * - * If you want to specify the socks reply, write it into req->reply - * and set req->replylen, else leave req->replylen alone. + * If you want to specify the socks reply, write it into req->reply + * and set req->replylen, else leave req->replylen alone. * - * If returning 0 or -1, req->address and req->port are undefined. + * If returning 0 or -1, req->address and req->port are undefined. */ int fetch_from_buf_socks(buf_t *buf, socks_request_t *req) { unsigned char len; @@ -618,7 +616,7 @@ int fetch_from_buf_socks(buf_t *buf, socks_request_t *req) { } } -/** Log an error and exit if 'buf' is corrupted. +/** Log an error and exit if buf is corrupted. */ void assert_buf_ok(buf_t *buf) { @@ -628,7 +626,6 @@ void assert_buf_ok(buf_t *buf) tor_assert(buf->datalen <= buf->len); } - /* Local Variables: mode:c diff --git a/src/or/command.c b/src/or/command.c index 559ef74b95..3afe638c3f 100644 --- a/src/or/command.c +++ b/src/or/command.c @@ -2,26 +2,31 @@ /* See LICENSE for licensing information */ /* $Id$ */ +/** + * \file command.c + * \brief Functions for processing incoming cells + **/ + #include "or.h" -extern or_options_t options; /* command-line and config-file options */ +extern or_options_t options; /**< command-line and config-file options */ -/* keep statistics about how many of each type of cell we've received */ +/** keep statistics about how many of each type of cell we've received */ unsigned long stats_n_padding_cells_processed = 0; unsigned long stats_n_create_cells_processed = 0; unsigned long stats_n_created_cells_processed = 0; unsigned long stats_n_relay_cells_processed = 0; unsigned long stats_n_destroy_cells_processed = 0; -/* These are the main four functions for processing cells */ +/** These are the main four functions for processing cells */ static void command_process_create_cell(cell_t *cell, connection_t *conn); static void command_process_created_cell(cell_t *cell, connection_t *conn); static void command_process_relay_cell(cell_t *cell, connection_t *conn); static void command_process_destroy_cell(cell_t *cell, connection_t *conn); -/* This is a wrapper function around the actual function that processes - * 'cell' that just arrived on 'conn'. Increment *time by the number of - * microseconds used by the call to *func(cell, conn). +/** This is a wrapper function around the actual function that processes the + * cell that just arrived on conn. Increment *time + * by the number of microseconds used by the call to *func(cell, conn). */ static void command_time_process_cell(cell_t *cell, connection_t *conn, int *time, void (*func)(cell_t *, connection_t *)) { @@ -41,7 +46,7 @@ static void command_time_process_cell(cell_t *cell, connection_t *conn, int *tim *time += time_passed; } -/* Process a cell that was just received on conn. Keep internal +/** Process a cell that was just received on conn. Keep internal * statistics about how many of each cell we've processed so far * this second, and the total number of microseconds it took to * process each type of cell. @@ -107,7 +112,7 @@ void command_process_cell(cell_t *cell, connection_t *conn) { } } -/* Process a 'create' cell that just arrived from conn. Make a new circuit +/** Process a 'create' cell that just arrived from conn. Make a new circuit * with the p_circ_id specified in cell. Put the circuit in state * onionskin_pending, and pass the onionskin to the cpuworker. Circ will * get picked up again when the cpuworker finishes decrypting it. @@ -137,9 +142,9 @@ static void command_process_create_cell(cell_t *cell, connection_t *conn) { log_fn(LOG_DEBUG,"success: handed off onionskin."); } -/* Process a 'created' cell that just arrived from conn. Find the circuit - * that it's intended for. If you're not the origin of the circuit, package - * the 'created' cell in an 'extended' relay cell and pass it back. If you +/** Process a 'created' cell that just arrived from conn. Find the circuit + * that it's intended for. If we're not the origin of the circuit, package + * the 'created' cell in an 'extended' relay cell and pass it back. If we * are the origin of the circuit, send it to circuit_finish_handshake() to * finish processing keys, and then call circuit_send_next_onion_skin() to * extend to the next hop in the circuit if necessary. @@ -180,7 +185,7 @@ static void command_process_created_cell(cell_t *cell, connection_t *conn) { } } -/* Process a 'relay' cell that just arrived from conn. Make sure +/** Process a 'relay' cell that just arrived from conn. Make sure * it came in with a recognized circ_id. Pass it on to * circuit_receive_relay_cell() for actual processing. */ @@ -216,8 +221,8 @@ static void command_process_relay_cell(cell_t *cell, connection_t *conn) { } } -/* Process a 'destroy' cell that just arrived from conn. Find the - * circ that it refers to (if any). +/** Process a 'destroy' cell that just arrived from + * conn. Find the circ that it refers to (if any). * * If the circ is in state * onionskin_pending, then call onion_pending_remove() to remove it diff --git a/src/or/connection_or.c b/src/or/connection_or.c index 3c1b22e540..bab0969ca0 100644 --- a/src/or/connection_or.c +++ b/src/or/connection_or.c @@ -2,17 +2,23 @@ /* See LICENSE for licensing information */ /* $Id$ */ +/** + * \file connection_or.c + * \brief Functions to handle OR connections, TLS handshaking, and + * cells on the network. + **/ + #include "or.h" -extern or_options_t options; /* command-line and config-file options */ +extern or_options_t options; /**< command-line and config-file options */ static int connection_tls_finish_handshake(connection_t *conn); static int connection_or_process_cells_from_inbuf(connection_t *conn); /**************************************************************/ -/* Pack the cell_t host-order structure 'src' into network-order - * in the buffer 'dest'. See tor-spec.txt for details about the +/** Pack the cell_t host-order structure src into network-order + * in the buffer dest. See tor-spec.txt for details about the * wire format. */ static void cell_pack(char *dest, const cell_t *src) { @@ -21,8 +27,8 @@ static void cell_pack(char *dest, const cell_t *src) { memcpy(dest+3, src->payload, CELL_PAYLOAD_SIZE); } -/* Unpack the network-order buffer 'src' into a host-order - * cell_t structure 'dest'. +/** Unpack the network-order buffer src into a host-order + * cell_t structure dest. */ static void cell_unpack(cell_t *dest, const char *src) { dest->circ_id = ntohs(*(uint16_t*)(src)); @@ -30,9 +36,7 @@ static void cell_unpack(cell_t *dest, const char *src) { memcpy(dest->payload, src+3, CELL_PAYLOAD_SIZE); } -/**************************************************************/ - -/* Handle any new bytes that have come in on connection 'conn'. +/** Handle any new bytes that have come in on connection conn. * If conn is in 'open' state, hand it to * connection_or_process_cells_from_inbuf() * (else do nothing). @@ -52,7 +56,7 @@ int connection_or_process_inbuf(connection_t *conn) { return connection_or_process_cells_from_inbuf(conn); } -/* Connection 'conn' has finished writing and has no bytes left on +/** Connection conn has finished writing and has no bytes left on * its outbuf. * * If it's in state 'connecting', then take a look at the socket, and @@ -68,7 +72,8 @@ int connection_or_finished_flushing(connection_t *conn) { switch(conn->state) { case OR_CONN_STATE_CONNECTING: - if (getsockopt(conn->s, SOL_SOCKET, SO_ERROR, (void*)&e, &len) < 0) { /* not yet */ + if (getsockopt(conn->s, SOL_SOCKET, SO_ERROR, (void*)&e, &len) < 0) { + /* not yet */ if(!ERRNO_IS_CONN_EINPROGRESS(tor_socket_errno(conn->s))) { log_fn(LOG_DEBUG,"in-progress connect failed. Removing."); connection_mark_for_close(conn,0); @@ -97,9 +102,7 @@ int connection_or_finished_flushing(connection_t *conn) { } } -/*********************/ - -/* Initialize conn to include all the relevant data from router. +/** Initialize conn to include all the relevant data from router. * This function is called either from connection_or_connect(), if * we initiated the connect, or from connection_tls_finish_handshake() * if the other side initiated it. @@ -115,11 +118,11 @@ connection_or_init_conn_from_router(connection_t *conn, routerinfo_t *router) { conn->address = tor_strdup(router->address); } -/* Launch a new OR connection to 'router'. +/** Launch a new OR connection to router. * - * If router is me, do nothing. If we're already connected to router, + * If router is me, do nothing. If we're already connected to router, * return that connection. If the connect is in progress, set conn's - * state to 'connecting' and return. If connect to router succeeds, call + * state to 'connecting' and return. If connect to router succeeds, call * connection_tls_start_handshake() on it. * * This function is called from router_retry_connections(), for @@ -170,13 +173,13 @@ connection_t *connection_or_connect(routerinfo_t *router) { return NULL; } -/* Begin the tls handshake with conn. 'receiving' is 0 if we initiated - * the connection, else it's 1. +/** Begin the tls handshake with conn. receiving is 0 if + * we initiated the connection, else it's 1. * - * Assign a new tls object to conn->tls, begin reading on conn, and pass - * conn to connection_tls_continue_handshake(). + * Assign a new tls object to conn->tls, begin reading on conn, and pass + * conn to connection_tls_continue_handshake(). * - * Return -1 if conn is broken, else return 0. + * Return -1 if conn is broken, else return 0. */ int connection_tls_start_handshake(connection_t *conn, int receiving) { conn->state = OR_CONN_STATE_HANDSHAKING; @@ -193,10 +196,10 @@ int connection_tls_start_handshake(connection_t *conn, int receiving) { return 0; } -/* Move forward with the tls handshake. If it finishes, hand - * conn to connection_tls_finish_handshake(). +/** Move forward with the tls handshake. If it finishes, hand + * conn to connection_tls_finish_handshake(). * - * Return -1 if conn is broken, else return 0. + * Return -1 if conn is broken, else return 0. */ int connection_tls_continue_handshake(connection_t *conn) { switch(tor_tls_handshake(conn->tls)) { @@ -217,7 +220,7 @@ int connection_tls_continue_handshake(connection_t *conn) { return 0; } -/* The tls handshake is finished. +/** The tls handshake is finished. * * Make sure we are happy with the person we just handshaked with: * If it's an OP (that is, it has no certificate), make sure I'm an OR. @@ -301,7 +304,7 @@ connection_tls_finish_handshake(connection_t *conn) { return 0; } -/* Pack 'cell' into wire-format, and write it onto conn's outbuf. */ +/** Pack cell into wire-format, and write it onto conn's outbuf. */ void connection_or_write_cell_to_buf(const cell_t *cell, connection_t *conn) { char networkcell[CELL_NETWORK_SIZE]; char *n = networkcell; @@ -314,8 +317,11 @@ void connection_or_write_cell_to_buf(const cell_t *cell, connection_t *conn) { connection_write_to_buf(n, CELL_NETWORK_SIZE, conn); } -/* Process cells from conn's inbuf. Loop: while inbuf contains a cell, pull - * it off the inbuf, unpack it, and hand it to command_process_cell(). +/** Process cells from conn's inbuf. + * + * Loop: while inbuf contains a cell, pull it off the inbuf, unpack it, + * and hand it to command_process_cell(). + * * Always return 0. */ static int connection_or_process_cells_from_inbuf(connection_t *conn) { diff --git a/src/or/cpuworker.c b/src/or/cpuworker.c index d57119f915..53ff4a156d 100644 --- a/src/or/cpuworker.c +++ b/src/or/cpuworker.c @@ -2,26 +2,34 @@ /* See LICENSE for licensing information */ /* $Id$ */ -/***** - * cpuworker.c: Run computation-intensive tasks (generally for crypto) in +/** + * \file cpuworker.c + * \brief Run computation-intensive tasks (generally for crypto) in * a separate execution context. [OR only.] * * Right now, we only use this for processing onionskins. - *****/ + **/ #include "or.h" -extern or_options_t options; /* command-line and config-file options */ +extern or_options_t options; /**< command-line and config-file options */ +/** The maximum number of cpuworker processes we will keep around */ #define MAX_CPUWORKERS 16 +/** The minimum number of cpuworker processes we will keep around */ #define MIN_CPUWORKERS 1 +/** The tag specifies which circuit this onionskin was from */ #define TAG_LEN 8 +/** How many bytes are sent from tor to the cpuworker? */ #define LEN_ONION_QUESTION (1+TAG_LEN+ONIONSKIN_CHALLENGE_LEN) +/** How many bytes are sent from the cpuworker back to tor? */ #define LEN_ONION_RESPONSE (1+TAG_LEN+ONIONSKIN_REPLY_LEN+40+32) +/** How many cpuworkers we have running right now */ static int num_cpuworkers=0; +/** How many of the running cpuworkers have an assigned task right now */ static int num_cpuworkers_busy=0; -/* We need to spawn new cpuworkers whenever we rotate the onion keys +/** We need to spawn new cpuworkers whenever we rotate the onion keys * on platforms where execution contexts==processes. This variable stores * the last time we got a key rotation event.*/ static time_t last_rotation_time=0; @@ -31,21 +39,21 @@ static int spawn_cpuworker(void); static void spawn_enough_cpuworkers(void); static void process_pending_task(connection_t *cpuworker); -/* Initialize the cpuworker subsystem. +/** Initialize the cpuworker subsystem. */ void cpu_init(void) { last_rotation_time=time(NULL); spawn_enough_cpuworkers(); } -/* Called when we're done sending a request to a cpuworker. */ +/** Called when we're done sending a request to a cpuworker. */ int connection_cpu_finished_flushing(connection_t *conn) { tor_assert(conn && conn->type == CONN_TYPE_CPUWORKER); connection_stop_writing(conn); return 0; } -/* Pack addr,port,and circ_id; set *tag to the result. (See note on +/** Pack addr,port,and circ_id; set *tag to the result. (See note on * cpuworker_main for wire format.) */ static void tag_pack(char *tag, uint32_t addr, uint16_t port, uint16_t circ_id) { *(uint32_t *)tag = addr; @@ -53,7 +61,7 @@ static void tag_pack(char *tag, uint32_t addr, uint16_t port, uint16_t circ_id) *(uint16_t *)(tag+6) = circ_id; } -/* Unpack 'tag' into addr, port, and circ_id. +/** Unpack 'tag' into addr, port, and circ_id. */ static void tag_unpack(const char *tag, uint32_t *addr, uint16_t *port, uint16_t *circ_id) { struct in_addr in; @@ -66,7 +74,7 @@ static void tag_unpack(const char *tag, uint32_t *addr, uint16_t *port, uint16_t log_fn(LOG_DEBUG,"onion was from %s:%d, circ_id %d.", inet_ntoa(in), *port, *circ_id); } -/* Called when the onion key has changed and we need to spawn new +/** Called when the onion key has changed and we need to spawn new * cpuworkers. Close all currently idle cpuworkers, and mark the last * rotation time as now. */ @@ -82,7 +90,7 @@ void cpuworkers_rotate(void) spawn_enough_cpuworkers(); } -/* Called when we get data from a cpuworker. If the answer is not complete, +/** Called when we get data from a cpuworker. If the answer is not complete, * wait for a complete answer. If the cpuworker closes the connection, * mark it as closed and spawn a new one as needed. If the answer is complete, * process it as appropriate. @@ -162,8 +170,7 @@ done_processing: return 0; } - -/* Implement a cpuworker. 'data' is an fdarray as returned by socketpair. +/** Implement a cpuworker. 'data' is an fdarray as returned by socketpair. * Read and writes from fdarray[1]. Reads requests, writes answers. * * Request format: @@ -249,7 +256,7 @@ int cpuworker_main(void *data) { return 0; /* windows wants this function to return an int */ } -/* Launch a new cpuworker. +/** Launch a new cpuworker. */ static int spawn_cpuworker(void) { int fd[2]; @@ -285,7 +292,7 @@ static int spawn_cpuworker(void) { return 0; /* success */ } -/* If we have too few or too many active cpuworkers, try to spawn new ones +/** If we have too few or too many active cpuworkers, try to spawn new ones * or kill idle ones. */ static void spawn_enough_cpuworkers(void) { @@ -305,7 +312,7 @@ static void spawn_enough_cpuworkers(void) { } } -/* Take a pending task from the queue and assign it to 'cpuworker' */ +/** Take a pending task from the queue and assign it to 'cpuworker' */ static void process_pending_task(connection_t *cpuworker) { circuit_t *circ; @@ -320,7 +327,7 @@ static void process_pending_task(connection_t *cpuworker) { log_fn(LOG_WARN,"assign_to_cpuworker failed. Ignoring."); } -/* if cpuworker is defined, assert that he's idle, and use him. else, +/** if cpuworker is defined, assert that he's idle, and use him. else, * look for an idle cpuworker and use him. if none idle, queue task onto * the pending onion list and return. * If question_type is CPUWORKER_TASK_ONION then task is a circ. @@ -371,4 +378,3 @@ int assign_to_cpuworker(connection_t *cpuworker, unsigned char question_type, c-basic-offset:2 End: */ - diff --git a/src/or/directory.c b/src/or/directory.c index 85813a834c..2964e4e2c2 100644 --- a/src/or/directory.c +++ b/src/or/directory.c @@ -4,9 +4,10 @@ #include "or.h" -/***** - * directory.c: Implement directory HTTP protocol. - *****/ +/** + * \file directory.c + * \brief Implement directory HTTP protocol. + **/ static void directory_send_command(connection_t *conn, int purpose, const char *payload, int payload_len); @@ -16,9 +17,9 @@ static int directory_handle_command(connection_t *conn); extern or_options_t options; /* command-line and config-file options */ -/* URL for publishing rendezvous descriptors. */ +/** URL for publishing rendezvous descriptors. */ char rend_publish_string[] = "/rendezvous/publish"; -/* Prefix for downloading rendezvous descriptors. */ +/** Prefix for downloading rendezvous descriptors. */ char rend_fetch_url[] = "/rendezvous/"; #define MAX_HEADERS_SIZE 10000 @@ -26,7 +27,7 @@ char rend_fetch_url[] = "/rendezvous/"; /********* END VARIABLES ************/ -/* Launch a new connection to the directory server 'router' to upload +/** Launch a new connection to the directory server 'router' to upload * or download a service or rendezvous descriptor. 'purpose' determines what * kind of directory connection we're launching, and must be one of * DIR_PURPOSE_{FETCH|UPLOAD}_{DIR|RENDDESC}. @@ -117,7 +118,7 @@ void directory_initiate_command(routerinfo_t *router, int purpose, } } -/* Queue an appropriate HTTP command on conn->outbuf. The args +/** Queue an appropriate HTTP command on conn->outbuf. The args * 'purpose', 'payload', and 'payload_len' are as in * directory_initiate_command. */ @@ -163,7 +164,7 @@ static void directory_send_command(connection_t *conn, int purpose, } } -/* Parse an HTTP request string 'headers' of the form "%s %s HTTP/1..." +/** Parse an HTTP request string 'headers' of the form "%s %s HTTP/1..." * If it's well-formed, point *url to the second %s, * null-terminate it (this modifies headers!) and return 0. * Otherwise, return -1. @@ -185,7 +186,7 @@ int parse_http_url(char *headers, char **url) { return 0; } -/* Parse an HTTP response string 'headers' of the form "HTTP/1.%d %d%s\r\n...". +/** Parse an HTTP response string 'headers' of the form "HTTP/1.%d %d%s\r\n...". * If it's well-formed, assign *code, point *message to the first * non-space character after code if there is one and message is non-NULL * (else leave it alone), and return 0. @@ -210,7 +211,7 @@ int parse_http_response(char *headers, int *code, char **message) { return 0; } -/* Read handler for directory connections. (That's connections *to* +/** Read handler for directory connections. (That's connections *to* * directory servers and connections *at* directory servers.) */ int connection_dir_process_inbuf(connection_t *conn) { @@ -361,7 +362,7 @@ static char answer403[] = "HTTP/1.0 403 Unapproved server\r\n\r\n"; static char answer404[] = "HTTP/1.0 404 Not found\r\n\r\n"; static char answer503[] = "HTTP/1.0 503 Directory unavailable\r\n\r\n"; -/* Helper function: called when a dirserver gets a complete HTTP GET +/** Helper function: called when a dirserver gets a complete HTTP GET * request. Look for a request for a directory or for a rendezvous * service descriptor. On finding one, write a response into * conn->outbuf. If the request is unrecognized, send a 404. @@ -427,7 +428,7 @@ static int directory_handle_command_get(connection_t *conn, return 0; } -/* Helper function: called when a dirserver gets a complete HTTP POST +/** Helper function: called when a dirserver gets a complete HTTP POST * request. Look for an uploaded server descriptor or rendezvous * service descriptor. On finding one, process it and write a * response into conn->outbuf. If the request is unrecognized, send a @@ -481,7 +482,7 @@ static int directory_handle_command_post(connection_t *conn, return 0; } -/* Called when a dirserver receives data on a directory connection; +/** Called when a dirserver receives data on a directory connection; * looks for an HTTP request. If the request is complete, remove it * from the inbuf, try to process it; otherwise, leave it on the * buffer. Return a 0 on success, or -1 on error. @@ -520,7 +521,7 @@ static int directory_handle_command(connection_t *conn) { return r; } -/* Write handler for directory connections; called when all data has +/** Write handler for directory connections; called when all data has * been flushed. Handle a completed connection: close the connection * or wait for a response as appropriate. */ diff --git a/src/or/dirserv.c b/src/or/dirserv.c index 128dd8276a..9c4612aea1 100644 --- a/src/or/dirserv.c +++ b/src/or/dirserv.c @@ -4,19 +4,20 @@ #include "or.h" -/***** - * dirserv.c: Directory server core implementation. +/** + * \file dirserv.c + * \brief Directory server core implementation. *****/ -/* How old do we allow a router to get before removing it? (seconds) */ +/** How old do we allow a router to get before removing it? (seconds) */ #define ROUTER_MAX_AGE (60*60*24) -/* How far in the future do we allow a router to get? (seconds) */ +/** How far in the future do we allow a router to get? (seconds) */ #define ROUTER_ALLOW_SKEW (30*60) -extern or_options_t options; /* command-line and config-file options */ +extern or_options_t options; /**< command-line and config-file options */ -/* Do we need to regenerate the directory when someone asks for it? */ +/** Do we need to regenerate the directory when someone asks for it? */ static int the_directory_is_dirty = 1; static int list_running_servers(char **nicknames_out); @@ -29,12 +30,12 @@ typedef struct fingerprint_entry_t { char *fingerprint; } fingerprint_entry_t; -/* List of nickname->identity fingerprint mappings for all the routers +/** List of nickname->identity fingerprint mappings for all the routers * that we recognize. Used to prevent Sybil attacks. */ static fingerprint_entry_t fingerprint_list[MAX_ROUTERS_IN_DIR]; static int n_fingerprints = 0; -/* Add the fingerprint 'fp' for the nickname 'nickname' to the global +/** Add the fingerprint 'fp' for the nickname 'nickname' to the global * list of recognized identity key fingerprints. */ void /* Should be static; exposed for testing */ @@ -53,7 +54,7 @@ add_fingerprint_to_dir(const char *nickname, const char *fp) ++n_fingerprints; } -/* Add the nickname and fingerprint for this OR to the recognized list. +/** Add the nickname and fingerprint for this OR to the recognized list. */ int dirserv_add_own_fingerprint(const char *nickname, crypto_pk_env_t *pk) @@ -67,7 +68,7 @@ dirserv_add_own_fingerprint(const char *nickname, crypto_pk_env_t *pk) return 0; } -/* Parse the nickname->fingerprint mappings stored in the file named +/** Parse the nickname->fingerprint mappings stored in the file named * 'fname'. The file format is line-based, with each non-blank * holding one nickname, some space, and a fingerprint for that * nickname. On success, replace the current fingerprint list with @@ -129,7 +130,7 @@ dirserv_parse_fingerprint_file(const char *fname) return -1; } -/* Check whether 'router' has a nickname/identity key combination that +/** Check whether 'router' has a nickname/identity key combination that * we recognize from the fingerprint list. Return 1 if router's * identity and nickname match, -1 if we recognize the nickname but * the identity key is wrong, and 0 if the nickname is not known. */ @@ -166,7 +167,7 @@ dirserv_router_fingerprint_is_known(const routerinfo_t *router) } } -/* Return true iff any router named 'nickname' is in the fingerprint +/** Return true iff any router named 'nickname' is in the fingerprint * list. */ static int router_nickname_is_approved(const char *nickname) @@ -180,7 +181,7 @@ router_nickname_is_approved(const char *nickname) return 0; } -/* Clear the current fingerprint list. */ +/** Clear the current fingerprint list. */ void dirserv_free_fingerprint_list() { @@ -196,7 +197,7 @@ dirserv_free_fingerprint_list() * Descriptor list */ -/* A directory server's view of a server descriptor. Contains both +/** A directory server's view of a server descriptor. Contains both * parsed and unparsed versions. */ typedef struct descriptor_entry_t { char *nickname; @@ -206,11 +207,11 @@ typedef struct descriptor_entry_t { routerinfo_t *router; } descriptor_entry_t; -/* List of all server descriptors that this dirserv is holding. */ +/** List of all server descriptors that this dirserv is holding. */ static descriptor_entry_t *descriptor_list[MAX_ROUTERS_IN_DIR]; static int n_descriptors = 0; -/* Release the storage held by 'desc' */ +/** Release the storage held by 'desc' */ static void free_descriptor_entry(descriptor_entry_t *desc) { tor_free(desc->descriptor); @@ -219,7 +220,7 @@ static void free_descriptor_entry(descriptor_entry_t *desc) free(desc); } -/* Release all storage that the dirserv is holding for server +/** Release all storage that the dirserv is holding for server * descriptors. */ void dirserv_free_descriptors() @@ -231,7 +232,7 @@ dirserv_free_descriptors() n_descriptors = 0; } -/* Parse the server descriptor at *desc and maybe insert it into the +/** Parse the server descriptor at *desc and maybe insert it into the * list of service descriptors, and (if the descriptor is well-formed) * advance *desc immediately past the descriptor's end. * @@ -349,7 +350,7 @@ dirserv_add_descriptor(const char **desc) return 1; } -/* Remove all descriptors whose nicknames or fingerprints we don't +/** Remove all descriptors whose nicknames or fingerprints we don't * recognize. (Descriptors that used to be good can become * unrecognized when we reload the fingerprint list.) */ @@ -367,7 +368,7 @@ directory_remove_unrecognized(void) } } -/* Mark the directory as 'dirty' -- when we're next asked for a +/** Mark the directory as 'dirty' -- when we're next asked for a * directory, we will rebuild it instead of reusing the most recently * generated one. */ @@ -377,7 +378,7 @@ directory_set_dirty() the_directory_is_dirty = 1; } -/* Load all descriptors from an earlier directory stored in the string +/** Load all descriptors from an earlier directory stored in the string * 'dir'. */ int @@ -396,7 +397,7 @@ dirserv_init_from_directory_string(const char *dir) return 0; } -/* Set *nicknames_out to a comma-separated list of all the ORs that we +/** Set *nicknames_out to a comma-separated list of all the ORs that we * believe are currently running (because we have open connections to * them). Return 0 on success; -1 on error. */ @@ -440,7 +441,7 @@ list_running_servers(char **nicknames_out) return 0; } -/* Remove any descriptors from the directory that are more than ROUTER_MAX_AGE +/** Remove any descriptors from the directory that are more than ROUTER_MAX_AGE * seconds old. */ void @@ -461,7 +462,7 @@ dirserv_remove_old_servers(void) } } -/* Dump all routers currently in the directory into the string , using +/** Dump all routers currently in the directory into the string , using * at most characters, and signing the directory with . * Return 0 on success, -1 on failure. */ @@ -535,9 +536,11 @@ dirserv_dump_directory_to_string(char *s, unsigned int maxlen, return -1; } +/** XXX */ static char *the_directory = NULL; static int the_directory_len = -1; +/** XXX */ size_t dirserv_get_directory(const char **directory) { char *new_directory; diff --git a/src/or/dns.c b/src/or/dns.c index 0c3d77edc2..e094ab884f 100644 --- a/src/or/dns.c +++ b/src/or/dns.c @@ -2,9 +2,10 @@ /* See LICENSE for licensing information */ /* $Id$ */ -/***** - * dns.c: Resolve hostnames in separate processes. - *****/ +/** + * \file dns.c + * \brief Resolve hostnames in separate processes. + **/ /* See http://elvin.dstc.com/ListArchive/elvin-dev/archive/2001/09/msg00027.html * for some approaches to asynchronous dns. We will want to switch once one of @@ -14,47 +15,49 @@ #include "or.h" #include "tree.h" -extern or_options_t options; /* command-line and config-file options */ +extern or_options_t options; /**< command-line and config-file options */ -/* Longest hostname we're willing to resolve. */ +/** Longest hostname we're willing to resolve. */ #define MAX_ADDRESSLEN 256 -/* Maximum DNS processes to spawn. */ +/** Maximum DNS processes to spawn. */ #define MAX_DNSWORKERS 50 -/* Minimum DNS processes to spawn. */ +/** Minimum DNS processes to spawn. */ #define MIN_DNSWORKERS 3 -/* If more than this many processes are idle, shut down the extras. */ +/** If more than this many processes are idle, shut down the extras. */ #define MAX_IDLE_DNSWORKERS 10 -/* Possible outcomes from hostname lookup: permanent failure, +/** Possible outcomes from hostname lookup: permanent failure, * transient (retryable) failure, and success */ #define DNS_RESOLVE_FAILED_TRANSIENT 1 #define DNS_RESOLVE_FAILED_PERMANENT 2 #define DNS_RESOLVE_SUCCEEDED 3 +/** How many dnsworkers we have running right now */ int num_dnsworkers=0; +/** How many of the running dnsworkers have an assigned task right now */ int num_dnsworkers_busy=0; -/* Linked list of connections waiting for a DNS answer. */ +/** Linked list of connections waiting for a DNS answer. */ struct pending_connection_t { struct connection_t *conn; struct pending_connection_t *next; }; -/* A DNS request: possibly completed, possibly pending; cached_resolve +/** A DNS request: possibly completed, possibly pending; cached_resolve * structs are stored at the OR side in a splay tree, and as a linked * list from oldest to newest. */ struct cached_resolve { SPLAY_ENTRY(cached_resolve) node; - char address[MAX_ADDRESSLEN]; /* the hostname to be resolved */ - uint32_t addr; /* in host order. I know I'm horrible for assuming ipv4 */ - char state; /* 0 is pending; 1 means answer is valid; 2 means resolve failed */ + char address[MAX_ADDRESSLEN]; /**< the hostname to be resolved */ + uint32_t addr; /**< in host order. I know I'm horrible for assuming ipv4 */ + char state; /**< 0 is pending; 1 means answer is valid; 2 means resolve failed */ #define CACHE_STATE_PENDING 0 #define CACHE_STATE_VALID 1 #define CACHE_STATE_FAILED 2 - uint32_t expire; /* remove items from cache after this time */ + uint32_t expire; /**< remove items from cache after this time */ struct pending_connection_t *pending_connections; struct cached_resolve *next; }; @@ -67,10 +70,10 @@ int dnsworker_main(void *data); static int spawn_dnsworker(void); static void spawn_enough_dnsworkers(void); -/* Splay tree of cached_resolve objects */ +/** Splay tree of cached_resolve objects */ static SPLAY_HEAD(cache_tree, cached_resolve) cache_root; -/* Function to compare hashed resolves on their addresses; used to +/** Function to compare hashed resolves on their addresses; used to * implement splay trees. */ static int compare_cached_resolves(struct cached_resolve *a, struct cached_resolve *b) { @@ -81,21 +84,22 @@ static int compare_cached_resolves(struct cached_resolve *a, SPLAY_PROTOTYPE(cache_tree, cached_resolve, node, compare_cached_resolves); SPLAY_GENERATE(cache_tree, cached_resolve, node, compare_cached_resolves); -/* Initialize the DNS cache */ +/** Initialize the DNS cache */ static void init_cache_tree(void) { SPLAY_INIT(&cache_root); } -/* Initialize the DNS subsystem; called by the OR process. */ +/** Initialize the DNS subsystem; called by the OR process. */ void dns_init(void) { init_cache_tree(); spawn_enough_dnsworkers(); } -static struct cached_resolve *oldest_cached_resolve = NULL; /* linked list, */ -static struct cached_resolve *newest_cached_resolve = NULL; /* oldest to newest */ +/** linked list of resolved addresses, oldest to newest */ +static struct cached_resolve *oldest_cached_resolve = NULL; +static struct cached_resolve *newest_cached_resolve = NULL; -/* Remove every cached_resolve whose 'expire' time is before 'now' +/** Remove every cached_resolve whose 'expire' time is before 'now' * from the cache. */ static void purge_expired_resolves(uint32_t now) { struct cached_resolve *resolve; @@ -120,7 +124,7 @@ static void purge_expired_resolves(uint32_t now) { } } -/* See if we have a cache entry for 'exitconn->address'. if so, +/** See if we have a cache entry for 'exitconn->address'. if so, * if resolve valid, put it into exitconn->addr and return 1. * If resolve failed, return -1. * @@ -201,7 +205,7 @@ int dns_resolve(connection_t *exitconn) { return assign_to_dnsworker(exitconn); } -/* Find or spawn a dns worker process to handle resolving +/** Find or spawn a dns worker process to handle resolving * exitconn->address; tell that dns worker to begin resolving. */ static int assign_to_dnsworker(connection_t *exitconn) { @@ -236,7 +240,7 @@ static int assign_to_dnsworker(connection_t *exitconn) { return 0; } -/* Remove 'conn' from the list of connections waiting for conn->address. +/** Remove 'conn' from the list of connections waiting for conn->address. */ void connection_dns_remove(connection_t *conn) { @@ -279,7 +283,7 @@ void connection_dns_remove(connection_t *conn) } } -/* Log an error and abort if conn is waiting for a DNS resolve. +/** Log an error and abort if conn is waiting for a DNS resolve. */ void assert_connection_edge_not_dns_pending(connection_t *conn) { struct pending_connection_t *pend; @@ -294,7 +298,7 @@ void assert_connection_edge_not_dns_pending(connection_t *conn) { } } -/* Log an error and abort if any connection waiting for a DNS resolve is +/** Log an error and abort if any connection waiting for a DNS resolve is * corrupted. */ void assert_all_pending_dns_resolves_ok(void) { struct pending_connection_t *pend; @@ -309,7 +313,7 @@ void assert_all_pending_dns_resolves_ok(void) { } } -/* Mark all connections waiting for 'address' for close. Then cancel +/** Mark all connections waiting for 'address' for close. Then cancel * the resolve for 'address' itself, and remove any cached results for * 'address' from the cache. */ @@ -347,7 +351,7 @@ void dns_cancel_pending_resolve(char *address) { dns_purge_resolve(resolve); } -/* Remove 'resolve' from the cache. +/** Remove 'resolve' from the cache. */ static void dns_purge_resolve(struct cached_resolve *resolve) { struct cached_resolve *tmp; @@ -373,7 +377,7 @@ static void dns_purge_resolve(struct cached_resolve *resolve) { tor_free(resolve); } -/* Called on the OR side when a DNS worker tells us the outcome of a DNS +/** 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. ('address' is a NUL-terminated string containing the * address to look up; 'addr' is an IPv4 address in host order; 'outcome' is @@ -459,14 +463,14 @@ static void dns_found_answer(char *address, uint32_t addr, char outcome) { * Connection between OR and dnsworker *****/ -/* Write handler: called when we've pushed a request to a dnsworker. */ +/** Write handler: called when we've pushed a request to a dnsworker. */ int connection_dns_finished_flushing(connection_t *conn) { tor_assert(conn && conn->type == CONN_TYPE_DNSWORKER); connection_stop_writing(conn); return 0; } -/* Read handler: called when we get data from a dnsworker. If the +/** Read handler: called when we get data from a dnsworker. If the * connection is closed, mark the dnsworker as dead. Otherwise, see * if we have a complete answer. If so, call dns_found_answer on the * result. If not, wait. Returns 0. */ @@ -510,7 +514,7 @@ int connection_dns_process_inbuf(connection_t *conn) { return 0; } -/* Implementation for DNS workers; this code runs in a separate +/** Implementation for DNS workers; this code runs in a separate * execution context. It takes as its argument an fdarray as returned * by socketpair(), and communicates via fdarray[1]. The protocol is * as follows: @@ -578,7 +582,7 @@ int dnsworker_main(void *data) { return 0; /* windows wants this function to return an int */ } -/* Launch a new DNS worker; return 0 on success, -1 on failure. +/** Launch a new DNS worker; return 0 on success, -1 on failure. */ static int spawn_dnsworker(void) { int fd[2]; @@ -614,7 +618,7 @@ static int spawn_dnsworker(void) { return 0; /* success */ } -/* If we have too many or too few DNS workers, spawn or kill some. +/** If we have too many or too few DNS workers, spawn or kill some. */ static void spawn_enough_dnsworkers(void) { int num_dnsworkers_needed; /* aim to have 1 more than needed, diff --git a/src/or/main.c b/src/or/main.c index 5a8ae948c4..dafd52e49e 100644 --- a/src/or/main.c +++ b/src/or/main.c @@ -2,9 +2,10 @@ /* See LICENSE for licensing information */ /* $Id$ */ -/***** - * main.c: Tor main loop and startup functions. - *****/ +/** + * \file main.c + * \brief Tor main loop and startup functions. + **/ #include "or.h" @@ -15,42 +16,42 @@ static int init_from_config(int argc, char **argv); /********* START VARIABLES **********/ -/* declared in connection.c */ +/** declared in connection.c */ extern char *conn_state_to_string[][_CONN_TYPE_MAX+1]; -or_options_t options; /* command-line and config-file options */ -int global_read_bucket; /* max number of bytes I can read this second */ +or_options_t options; /**< command-line and config-file options */ +int global_read_bucket; /**< max number of bytes I can read this second */ -/* What was the read bucket before the last call to prepare_for_pool? +/** What was the read bucket before the last call to prepare_for_pool? * (used to determine how many bytes we've read). */ static int stats_prev_global_read_bucket; -/* How many bytes have we read since we started the process? */ +/** How many bytes have we read since we started the process? */ static uint64_t stats_n_bytes_read = 0; -/* How many seconds have we been running? */ +/** How many seconds have we been running? */ static long stats_n_seconds_reading = 0; -/* Array of all open connections; each element corresponds to the element of +/** Array of all open connections; each element corresponds to the element of * poll_array in the same position. The first nfds elements are valid. */ static connection_t *connection_array[MAXCONNECTIONS] = { NULL }; -/* Array of pollfd objects for calls to poll(). */ +/** Array of pollfd objects for calls to poll(). */ static struct pollfd poll_array[MAXCONNECTIONS]; -static int nfds=0; /* number of connections currently active */ +static int nfds=0; /**< number of connections currently active */ #ifndef MS_WINDOWS /* do signal stuff only on unix */ -static int please_dumpstats=0; /* whether we should dump stats during the loop */ -static int please_reset=0; /* whether we just got a sighup */ -static int please_reap_children=0; /* whether we should waitpid for exited children */ +static int please_dumpstats=0; /**< whether we should dump stats during the loop */ +static int please_reset=0; /**< whether we just got a sighup */ +static int please_reap_children=0; /**< whether we should waitpid for exited children */ #endif /* signal stuff */ -/* we set this to 1 when we've fetched a dir, to know whether to complain +/** We set this to 1 when we've fetched a dir, to know whether to complain * yet about unrecognized nicknames in entrynodes, exitnodes, etc. * Also, we don't try building circuits unless this is 1. */ int has_fetched_directory=0; -/* we set this to 1 when we've opened a circuit, so we can print a log +/** We set this to 1 when we've opened a circuit, so we can print a log * entry to inform the user that Tor is working. */ int has_completed_circuit=0; @@ -64,7 +65,7 @@ int has_completed_circuit=0; * ****************************************************************************/ -/* Add 'conn' to the array of connections that we can poll on. The +/** Add conn to the array of connections that we can poll on. The * connection's socket must be set; the connection starts out * non-reading and non-writing. */ @@ -95,7 +96,7 @@ int connection_add(connection_t *conn) { return 0; } -/* Remove the connection from the global list, and remove the +/** Remove the connection from the global list, and remove the * corresponding poll entry. Calling this function will shift the last * connection (if any) into the position occupied by conn. */ @@ -126,16 +127,17 @@ int connection_remove(connection_t *conn) { return 0; } -/* Set *array to an array of all connections, and *n to the length - * of the array. *array and *n must not be modified. +/** Set *array to an array of all connections, and *n + * to the length of the array. *array and *n must not + * be modified. */ void get_connection_array(connection_t ***array, int *n) { *array = connection_array; *n = nfds; } -/* Set the event mask on 'conn' to 'events'. (The form of the event mask is - * as for poll().) +/** Set the event mask on conn to events. (The form of +* the event mask is as for poll().) */ void connection_watch_events(connection_t *conn, short events) { @@ -144,13 +146,13 @@ void connection_watch_events(connection_t *conn, short events) { poll_array[conn->poll_index].events = events; } -/* Return true iff the 'conn' is listening for read events. */ +/** Return true iff conn is listening for read events. */ int connection_is_reading(connection_t *conn) { tor_assert(conn && conn->poll_index >= 0); return poll_array[conn->poll_index].events & POLLIN; } -/* Tell the main loop to stop notifying 'conn' of any read events. */ +/** Tell the main loop to stop notifying conn of any read events. */ void connection_stop_reading(connection_t *conn) { tor_assert(conn && conn->poll_index >= 0 && conn->poll_index < nfds); @@ -159,31 +161,31 @@ void connection_stop_reading(connection_t *conn) { poll_array[conn->poll_index].events -= POLLIN; } -/* Tell the main loop to start notifying 'conn' of any read events. */ +/** Tell the main loop to start notifying conn of any read events. */ void connection_start_reading(connection_t *conn) { tor_assert(conn && conn->poll_index >= 0 && conn->poll_index < nfds); poll_array[conn->poll_index].events |= POLLIN; } -/* Return true iff the 'conn' is listening for write events. */ +/** Return true iff conn is listening for write events. */ int connection_is_writing(connection_t *conn) { return poll_array[conn->poll_index].events & POLLOUT; } -/* Tell the main loop to stop notifying 'conn' of any write events. */ +/** Tell the main loop to stop notifying conn of any write events. */ void connection_stop_writing(connection_t *conn) { tor_assert(conn && conn->poll_index >= 0 && conn->poll_index < nfds); if(poll_array[conn->poll_index].events & POLLOUT) poll_array[conn->poll_index].events -= POLLOUT; } -/* Tell the main loop to start notifying 'conn' of any write events. */ +/** Tell the main loop to start notifying conn of any write events. */ void connection_start_writing(connection_t *conn) { tor_assert(conn && conn->poll_index >= 0 && conn->poll_index < nfds); poll_array[conn->poll_index].events |= POLLOUT; } -/* Called when the connection at connection_array[i] has a read event, +/** Called when the connection at connection_array[i] has a read event, * or it has pending tls data waiting to be read: checks for validity, * catches numerous errors, and dispatches to connection_handle_read. */ @@ -224,7 +226,7 @@ static void conn_read(int i) { assert_all_pending_dns_resolves_ok(); } -/* Called when the connection at connection_array[i] has a write event: +/** Called when the connection at connection_array[i] has a write event: * checks for validity, catches numerous errors, and dispatches to * connection_handle_write. */ @@ -255,7 +257,7 @@ static void conn_write(int i) { assert_all_pending_dns_resolves_ok(); } -/* If the connection at connection_array[i] is marked for close, then: +/** If the connection at connection_array[i] is marked for close, then: * - If it has data that it wants to flush, try to flush it. * - If it _still_ has data to flush, and conn->hold_open_until_flushed is * true, then leave the connection open and return. @@ -322,7 +324,7 @@ static void conn_close_if_marked(int i) { } } -/* This function is called whenever we successfully pull down a directory */ +/** This function is called whenever we successfully pull down a directory */ void directory_has_arrived(void) { log_fn(LOG_INFO, "A directory has arrived."); @@ -338,7 +340,7 @@ void directory_has_arrived(void) { } } -/* Perform regular maintenance tasks for a single connection. This +/** Perform regular maintenance tasks for a single connection. This * function gets run once per second per connection by run_housekeeping. */ static void run_connection_housekeeping(int i, time_t now) { @@ -382,7 +384,7 @@ static void run_connection_housekeeping(int i, time_t now) { } } -/* Perform regular maintenance tasks. This function gets run once per +/** Perform regular maintenance tasks. This function gets run once per * second by prepare_for_poll. */ static void run_scheduled_events(time_t now) { @@ -392,7 +394,7 @@ static void run_scheduled_events(time_t now) { int i; - /* 1a. Every MIN_ONION_KEY_LIFETIME seconds, rotate the onion keys, + /** 1a. Every MIN_ONION_KEY_LIFETIME seconds, rotate the onion keys, * shut down and restart all cpuworkers, and update the directory if * necessary. */ @@ -406,7 +408,7 @@ static void run_scheduled_events(time_t now) { router_upload_dir_desc_to_dirservers(); } - /* 1b. Every MAX_SSL_KEY_LIFETIME seconds, we change our TLS context. */ + /** 1b. Every MAX_SSL_KEY_LIFETIME seconds, we change our TLS context. */ if (!last_rotated_certificate) last_rotated_certificate = now; if (options.ORPort && last_rotated_certificate+MAX_SSL_KEY_LIFETIME < now) { @@ -420,7 +422,7 @@ static void run_scheduled_events(time_t now) { * XXXX them at all. */ } - /* 1c. Every DirFetchPostPeriod seconds, we get a new directory and upload + /** 1c. Every DirFetchPostPeriod seconds, we get a new directory and upload * our descriptor (if any). */ if(time_to_fetch_directory < now) { /* it's time to fetch a new directory and/or post our descriptor */ @@ -445,14 +447,14 @@ static void run_scheduled_events(time_t now) { } - /* 2. Every second, we examine pending circuits and prune the + /** 2. Every second, we examine pending circuits and prune the * ones which have been pending for more than a few seconds. * We do this before step 3, so it can try building more if * it's not comfortable with the number of available circuits. */ circuit_expire_building(now); - /* 2b. Also look at pending streams and prune the ones that 'began' + /** 2b. Also look at pending streams and prune the ones that 'began' * a long time ago but haven't gotten a 'connected' yet. * Do this before step 3, so we can put them back into pending * state to be picked up by the new circuit. @@ -460,11 +462,11 @@ static void run_scheduled_events(time_t now) { connection_ap_expire_beginning(); - /* 2c. And expire connections that we've held open for too long. + /** 2c. And expire connections that we've held open for too long. */ connection_expire_held_open(); - /* 3. Every second, we try a new circuit if there are no valid + /** 3. Every second, we try a new circuit if there are no valid * circuits. Every NewCircuitPeriod seconds, we expire circuits * that became dirty more than NewCircuitPeriod seconds ago, * and we make a new circ if there are no clean circuits. @@ -472,22 +474,22 @@ static void run_scheduled_events(time_t now) { if(has_fetched_directory) circuit_build_needed_circs(now); - /* 4. We do housekeeping for each connection... */ + /** 4. We do housekeeping for each connection... */ for(i=0;i