From 09c3eb5539455e82dcb357fbce82bf5974c3a37c Mon Sep 17 00:00:00 2001
From: Brian Norris <banorris@uci.edu>
Date: Fri, 15 Feb 2013 11:54:11 -0800
Subject: [PATCH] model/threads: add documentation comments

Document {get,set}_pending(), has_asserted()/set_assert(), etc.
---
 model.cc        | 17 +++++++++++++++++
 threads-model.h | 19 +++++++++++++++++++
 2 files changed, 36 insertions(+)

diff --git a/model.cc b/model.cc
index 503253a..856a33d 100644
--- a/model.cc
+++ b/model.cc
@@ -327,11 +327,22 @@ void ModelChecker::set_bad_synchronization()
 	priv->bad_synchronization = true;
 }
 
+/**
+ * Check whether the current trace has triggered an assertion which should halt
+ * its execution.
+ *
+ * @return True, if the execution should be aborted; false otherwise
+ */
 bool ModelChecker::has_asserted() const
 {
 	return priv->asserted;
 }
 
+/**
+ * Trigger a trace assertion which should cause this execution to be halted.
+ * This can be due to a detected bug or due to an infeasibility that should
+ * halt ASAP.
+ */
 void ModelChecker::set_assert()
 {
 	priv->asserted = true;
@@ -2755,6 +2766,12 @@ void ModelChecker::run()
 		add_thread(t);
 
 		do {
+			/*
+			 * Stash next pending action(s) for thread(s). There
+			 * should only need to stash one thread's action--the
+			 * thread which just took a step--plus the first step
+			 * for any newly-created thread
+			 */
 			for (unsigned int i = 0; i < get_num_threads(); i++) {
 				thread_id_t tid = int_to_id(i);
 				Thread *thr = get_thread(tid);
diff --git a/threads-model.h b/threads-model.h
index d4d2da2..fd0314a 100644
--- a/threads-model.h
+++ b/threads-model.h
@@ -95,8 +95,15 @@ public:
 		return wait_list[i];
 	}
 
+	/** @return The pending (next) ModelAction for this Thread
+	 *  @see Thread::pending */
 	ModelAction * get_pending() const { return pending; }
+
+	/** @brief Set the pending (next) ModelAction for this Thread
+	 *  @param act The pending ModelAction
+	 *  @see Thread::pending */
 	void set_pending(ModelAction *act) { pending = act; }
+
 	/**
 	 * Remove one ModelAction from the waiting list
 	 * @return The ModelAction that was removed from the waiting list
@@ -119,10 +126,22 @@ public:
 	 */
 private:
 	int create_context();
+
+	/** @brief The parent Thread which created this Thread */
 	Thread *parent;
+
+	/** @brief The THREAD_CREATE ModelAction which created this Thread */
 	ModelAction *creation;
 
+	/**
+	 * @brief The next ModelAction to be run by this Thread
+	 *
+	 * This action should be kept updated by the ModelChecker, so that we
+	 * always know what the next ModelAction's memory_order, action type,
+	 * and location are.
+	 */
 	ModelAction *pending;
+
 	void (*start_routine)(void *);
 	void *arg;
 	ucontext_t context;
-- 
2.34.1