From: Brian Norris <banorris@uci.edu>
Date: Wed, 8 Aug 2012 00:59:44 +0000 (-0700)
Subject: main, threads: improve comments regarding thread stepping
X-Git-Tag: pldi2013~286
X-Git-Url: http://plrg.eecs.uci.edu/git/?p=model-checker.git;a=commitdiff_plain;h=08b08df583f48064ec920b56162526f38b1db481

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 73b3b0c..62acd90 100644
--- 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 f240106..33bb992 100644
--- 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) {