Change return value of entry_guard_succeeded to an enum.

George pointed out that (-1,0,1) for (never usable, maybe usable
later, usable right now) was a pretty rotten convention that made
the code harder to read.

3 files changed, 26 insertions, 22 deletions

diff --git a/src/or/circuitbuild.c b/src/or/circuitbuild.c
index 5d0a04fe71..c7e116e853 100644
--- a/src/or/circuitbuild.c
+++ b/src/or/circuitbuild.c
@@ -964,28 +964,29 @@ circuit_send_next_onion_skin(origin_circuit_t *circ)
     memset(&ec, 0, sizeof(ec));
     if (!hop) {
       /* done building the circuit. whew. */
-      int r;
+      guard_usable_t r;
       if (get_options()->UseDeprecatedGuardAlgorithm) {
         // The circuit is usable; we already marked the guard as okay.
-        r = 1;
+        r = GUARD_USABLE_NOW;
       } else if (! circ->guard_state) {
         if (circuit_get_cpath_len(circ) != 1) {
           log_warn(LD_BUG, "%d-hop circuit %p with purpose %d has no "
                    "guard state",
                    circuit_get_cpath_len(circ), circ, circ->base_.purpose);
         }
-        r = 1;
+        r = GUARD_USABLE_NOW;
       } else {
         r = entry_guard_succeeded(&circ->guard_state);
       }
-      const int is_usable_for_streams = (r == 1);
-      if (r == 1) {
+      const int is_usable_for_streams = (r == GUARD_USABLE_NOW);
+      if (r == GUARD_USABLE_NOW) {
         circuit_set_state(TO_CIRCUIT(circ), CIRCUIT_STATE_OPEN);
-      } else if (r == 0) {
+      } else if (r == GUARD_MAYBE_USABLE_LATER) {
         // XXXX prop271 we might want to probe for whether this
         // XXXX one is ready even before the next second rolls over.
         circuit_set_state(TO_CIRCUIT(circ), CIRCUIT_STATE_GUARD_WAIT);
       } else {
+        tor_assert_nonfatal(r == GUARD_USABLE_NEVER);
         return - END_CIRC_REASON_INTERNAL;
       }
 
diff --git a/src/or/entrynodes.c b/src/or/entrynodes.c
index af1869f045..aa90566cf7 100644
--- a/src/or/entrynodes.c
+++ b/src/or/entrynodes.c
@@ -1965,28 +1965,26 @@ entry_guard_pick_for_circuit(guard_selection_t *gs,
 }
 
 /**
- * Called by the circuit building module when a circuit has succeeded:
- * informs the guards code that the guard in *<b>guard_state_p</b> is
- * working, and advances the state of the guard module.  On a -1 return
- * value, the circuit is broken and should not be used.  On a 1 return
- * value, the circuit is ready to use.  On a 0 return value, the circuit
- * should not be used until we find out whether preferred guards will
- * work for us.
- *
- * XXXXX prop271 tristates are ugly; reconsider that interface.
+ * Called by the circuit building module when a circuit has succeeded: informs
+ * the guards code that the guard in *<b>guard_state_p</b> is working, and
+ * advances the state of the guard module.  On a GUARD_USABLE_NEVER return
+ * value, the circuit is broken and should not be used.  On a GUARD_USABLE_NOW
+ * return value, the circuit is ready to use.  On a GUARD_MAYBE_USABLE_LATER
+ * return value, the circuit should not be used until we find out whether
+ * preferred guards will work for us.
  */
-int
+guard_usable_t
 entry_guard_succeeded(circuit_guard_state_t **guard_state_p)
 {
   if (get_options()->UseDeprecatedGuardAlgorithm)
-    return 1;
+    return GUARD_USABLE_NOW;
 
   if (BUG(*guard_state_p == NULL))
-    return -1;
+    return GUARD_USABLE_NEVER;
 
   entry_guard_t *guard = entry_guard_handle_get((*guard_state_p)->guard);
   if (! guard || BUG(guard->in_selection == NULL))
-    return -1;
+    return GUARD_USABLE_NEVER;
 
   unsigned newstate =
     entry_guards_note_guard_success(guard->in_selection, guard,
@@ -1996,9 +1994,9 @@ entry_guard_succeeded(circuit_guard_state_t **guard_state_p)
   (*guard_state_p)->state_set_at = approx_time();
 
   if (newstate == GUARD_CIRC_STATE_COMPLETE) {
-    return 1;
+    return GUARD_USABLE_NOW;
   } else {
-    return 0;
+    return GUARD_MAYBE_USABLE_LATER;
   }
 }
 
diff --git a/src/or/entrynodes.h b/src/or/entrynodes.h
index 21dab6ea18..ceccd0ff10 100644
--- a/src/or/entrynodes.h
+++ b/src/or/entrynodes.h
@@ -359,7 +359,12 @@ void circuit_guard_state_free(circuit_guard_state_t *state);
 int entry_guard_pick_for_circuit(guard_selection_t *gs,
                                  const node_t **chosen_node_out,
                                  circuit_guard_state_t **guard_state_out);
-int entry_guard_succeeded(circuit_guard_state_t **guard_state_p);
+typedef enum {
+  GUARD_USABLE_NEVER = -1,
+  GUARD_MAYBE_USABLE_LATER = 0,
+  GUARD_USABLE_NOW = 1,
+} guard_usable_t;
+guard_usable_t entry_guard_succeeded(circuit_guard_state_t **guard_state_p);
 void entry_guard_failed(circuit_guard_state_t **guard_state_p);
 void entry_guard_cancel(circuit_guard_state_t **guard_state_p);
 void entry_guard_chan_failed(channel_t *chan);