commit 61629b4f6ccb06ec190c4078797fcb48d83208d5 Author: George Kadianakis <desnacked@riseup.net> Date: Sun Jun 15 19:02:35 2014 -0700 Document choose_random_entry_impl() and populate_live_entry_guards(). --- src/or/entrynodes.c | 40 +++++++++++++++++++++++++++++++++++++--- 1 file changed, 37 insertions(+), 3 deletions(-) diff --git a/src/or/entrynodes.c b/src/or/entrynodes.c index 360c738..3dcb8f7 100644 --- a/src/or/entrynodes.c +++ b/src/or/entrynodes.c @@ -997,8 +997,25 @@ choose_random_dirguard(dirinfo_type_t type) return choose_random_entry_impl(NULL, 1, type, NULL); } -/* DOCDOCODC - Return 1 if we should choose a guard right away. */ +/** Filter <b>all_entry_guards</b> for usable entry guards and put them + * in <b>live_entry_guards</b>. We filter based on whether the node is + * currently alive, and on whether it satisfies the restrictions + * imposed by the other arguments of this function. + * + * We don't place more guards than NumEntryGuards in <b>live_entry_guards</b>. + * + * If <b>chosen_exit</b> is set, it contains the exit node of this + * circuit. Make sure to not use it or its family as an entry guard. + * + * If <b>need_uptime</b> is set, we are looking for a stable entry guard. + * if <b>need_capacity</b> is set, we are looking for a fast entry guard. + * + * The rest of the arguments are the same as in choose_random_entry_impl(). + * + * Return 1 if we should choose a guard right away. Return 0 if we + * should try to add more nodes to our list before deciding on a + * guard. + */ STATIC int populate_live_entry_guards(smartlist_t *live_entry_guards, const smartlist_t *all_entry_guards, @@ -1058,7 +1075,24 @@ populate_live_entry_guards(smartlist_t *live_entry_guards, return retval; } -/** Helper for choose_random{entry,dirguard}. */ +/** Pick a node to be used as the entry guard of a circuit. + * + * If <b>state</b> is set, it contains the information we know about + * the upcoming circuit. + * + * If <b>for_directory</b> is set, we are looking for a directory guard. + * + * <b>dirinfo_type</b> contains the kind of directory information we + * are looking for in our node. + * + * If <b>n_options_out</b> is set, we set it to the number of + * candidate guard nodes we had before picking a specific guard node. + * + * On success, return the node that should be used as the entry guard + * of the circuit. Return NULL if no such node could be found. + * + * Helper for choose_random{entry,dirguard}. +*/ static const node_t * choose_random_entry_impl(cpath_build_state_t *state, int for_directory, dirinfo_type_t dirinfo_type, int *n_options_out)