main, threads: improve comments regarding thread stepping

The comment in thread_system_next was incorrect:
"Returns the 1 if there is another step and 0 otherwise."

Add a few comments throughout to help clarify this behavior.

diff --git a/main.cc b/main.cc
index 73b3b0c410d95fbdbd06190eadd35b25b1288e77..62acd90de18e4e05114b4519af0e707f5f954aa1 100644 (file)
--- a/main.cc
+++ b/main.cc
@@ -13,8 +13,9 @@
 #include "snapshot-interface.h"
 
 /**
- * The thread_system_next function takes the next step in the execution.
- * @return Returns the 1 if there is another step and 0 otherwise.
+ * The thread_system_next function takes the next step in the execution, if
+ * possible.
+ * @return Returns 0 (success) if there is another step and non-zero otherwise.
  */
 static int thread_system_next(void) {
        Thread *curr, *next;
@@ -24,20 +25,27 @@ static int thread_system_next(void) {
                if (curr->get_state() == THREAD_READY) {
                        model->check_current_action();
                        model->scheduler->add_thread(curr);
-               } else if (curr->get_state() == THREAD_RUNNING)
+               } else if (curr->get_state() == THREAD_RUNNING) {
                        /* Stopped while running; i.e., completed */
                        curr->complete();
-               else
+               } else {
                        ASSERT(false);
+               }
        }
        next = model->scheduler->next_thread();
+
+       /* Infeasible -> don't take any more steps */
        if (!model->isfeasible())
                return 1;
+
        if (next)
                next->set_state(THREAD_RUNNING);
        DEBUG("(%d, %d)\n", curr ? curr->get_id() : -1, next ? next->get_id() : -1);
+
+       /* next == NULL -> don't take any more steps */
        if (!next)
                return 1;
+       /* Return non-zero only if swap fails with an error */
        return Thread::swap(model->get_system_context(), next);
 }
 

diff --git a/threads.cc b/threads.cc
index f24010697d60f306de512ab40fecdece88875cdd..33bb99254e255db59b1045bbf94711535688487a 100644 (file)
--- a/threads.cc
+++ b/threads.cc
@@ -71,11 +71,27 @@ int Thread::create_context()
        return 0;
 }
 
+/**
+ * Swaps the current context to another thread of execution. This form switches
+ * from a user Thread to a system context.
+ * @param t Thread representing the current context
+ * @param ctxt Context to switch to
+ * @return Does not return, unless we return to Thread t's context. See
+ * swapcontext(3) (returns 0 for success, -1 for failure).
+ */
 int Thread::swap(Thread *t, ucontext_t *ctxt)
 {
        return swapcontext(&t->context, ctxt);
 }
 
+/**
+ * Swaps the current context to another thread of execution. This form switches
+ * from a system context to a user Thread.
+ * @param t Thread representing the current context
+ * @param ctxt Context to switch to
+ * @return Does not return, unless we return to Thread t's context. See
+ * swapcontext(3) (returns 0 for success, -1 for failure).
+ */
 int Thread::swap(ucontext_t *ctxt, Thread *t)
 {
        return swapcontext(ctxt, &t->context);
@@ -83,7 +99,6 @@ int Thread::swap(ucontext_t *ctxt, Thread *t)
 
 
 /** Terminate a thread and free its stack. */
-
 void Thread::complete()
 {
        if (state != THREAD_COMPLETED) {