model: document ModelChecker::mo_graph

The modification order graph is a complex data structure, and there are a few
pieces of high-level information that should be noted. For example, the edges
are actually directed from most recent to oldest, which is somewhat in reverse
of the usage in the literature, where

  a --mo--> b

means that a comes *before* b in the modification order. This convention can be
changed in the future, but it should be documented here.

diff --git a/model.h b/model.h
index 10f84c59ba6710ce1ad3a224d4d9f1784929254c..fcdc69fd9cf510fc1681e05c4b0edc346a4b0e31 100644 (file)
--- a/model.h
+++ b/model.h
@@ -121,7 +121,24 @@ private:
        std::vector<ModelAction *> *thrd_last_action;
        NodeStack *node_stack;
        ModelAction *next_backtrack;
+
+       /**
+        * @brief The modification order graph
+        *
+        * A direceted acyclic graph recording observations of the modification
+        * order on all the atomic objects in the system. This graph should
+        * never contain any cycles, as that represents a violation of the
+        * memory model (total ordering). This graph really consists of many
+        * disjoint (unconnected) subgraphs, each graph corresponding to a
+        * separate ordering on a distinct object.
+        *
+        * Note that the edges in this graph actually represent the "ordered
+        * after" relation, such that <tt>a --> b</tt> means <tt>a</tt> was
+        * ordered after <tt>b</tt>, or in the traditional sense of
+        * modification order, <tt>b --mo--> a</tt>.
+        */
        CycleGraph *mo_graph;
+
        bool failed_promise;
 };