From: Brian Norris <banorris@uci.edu>
Date: Mon, 20 Aug 2012 18:22:32 +0000 (-0700)
Subject: model: document ModelChecker::mo_graph
X-Git-Tag: pldi2013~266
X-Git-Url: http://plrg.eecs.uci.edu/git/?p=model-checker.git;a=commitdiff_plain;h=1d1a5597f254b812fab97dea48e076b54f53d7e6

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 10f84c5..fcdc69f 100644
--- 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;
 };