model/threads: add documentation comments

Document {get,set}_pending(), has_asserted()/set_assert(), etc.

diff --git a/model.cc b/model.cc
index 503253af17a5dc0ba4727b3dcff08d1dfcbf07d2..856a33d2cdfa13d2db741797d4fc0f1681a9fd04 100644 (file)
--- 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 d4d2da29e82a7fc1c58a2a61db7ee61aac7206a5..fd0314ad6b9fa34ac5a42c0fd9cfd94f6f552753 100644 (file)
--- 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;