X-Git-Url: http://plrg.eecs.uci.edu/git/?p=cdsspec-compiler.git;a=blobdiff_plain;f=action.h;h=dc560174bee561ca9f32fcec2d11d358ab040782;hp=abf55318cd3ba379ea198420fad4ce70bfc570ea;hb=9508fe09d2eeaaf7fbe7193d9cb81b3bc66316b5;hpb=776279c18c4a4e6b763c4aeffc65fafe37205824

diff --git a/action.h b/action.h
index abf5531..dc56017 100644
--- a/action.h
+++ b/action.h
@@ -12,6 +12,7 @@
 #include "memoryorder.h"
 #include "modeltypes.h"
 
+/* Forward declarations */
 class ClockVector;
 class Thread;
 class Promise;
@@ -27,16 +28,15 @@ using std::memory_order_release;
 using std::memory_order_acq_rel;
 using std::memory_order_seq_cst;
 
-/** Note that this value can be legitimately used by a program, and
- *  hence by iteself does not indicate no value. */
+/**
+ * @brief A recognizable don't-care value for use in the ModelAction::value
+ * field
+ *
+ * Note that this value can be legitimately used by a program, and hence by
+ * iteself does not indicate no value.
+ */
 #define VALUE_NONE 0xdeadbeef
 
-/** A special value to represent a successful trylock */
-#define VALUE_TRYSUCCESS 1
-
-/** A special value to represent a failed trylock */
-#define VALUE_TRYFAILED 0
-
 /** @brief Represents an action type, identifying one of several types of
  * ModelAction */
 typedef enum action_type {
@@ -69,7 +69,12 @@ class Node;
 class ClockVector;
 
 /**
- * The ModelAction class encapsulates an atomic action.
+ * @brief Represents a single atomic action
+ *
+ * A ModelAction is always allocated as non-snapshotting, because it is used in
+ * multiple executions during backtracking. Except for fake uninitialized
+ * (ATOMIC_UNINIT) ModelActions, each action is assigned a unique sequence
+ * number.
  */
 class ModelAction {
 public:
@@ -168,38 +173,61 @@ public:
 	MEMALLOC
 private:
 
-	/** Type of action (read, write, thread create, thread yield, thread join) */
+	/** @brief Type of action (read, write, RMW, fence, thread create, etc.) */
 	action_type type;
 
-	/** The memory order for this operation. */
+	/** @brief The memory order for this operation. */
 	memory_order order;
 
-	/** A pointer to the memory location for this action. */
+	/** @brief A pointer to the memory location for this action. */
 	void *location;
 
-	/** The thread id that performed this action. */
+	/** @brief The thread id that performed this action. */
 	thread_id_t tid;
 
-	/** The value written (for write or RMW; undefined for read) */
+	/** @brief The value written (for write or RMW; undefined for read) */
 	uint64_t value;
 
-	/** The action that this action reads from. Only valid for reads */
+	/**
+	 * @brief The store that this action reads from
+	 *
+	 * Only valid for reads
+	 */
 	const ModelAction *reads_from;
 
-	/** The promise that this action reads from. Only valid for reads */
+	/**
+	 * @brief The promise that this action reads from
+	 *
+	 * Only valid for reads
+	 */
 	Promise *reads_from_promise;
 
-	/** The last fence release from the same thread */
+	/** @brief The last fence release from the same thread */
 	const ModelAction *last_fence_release;
 
-	/** A back reference to a Node in NodeStack, if this ModelAction is
-	 * saved on the NodeStack. */
+	/**
+	 * @brief A back reference to a Node in NodeStack
+	 *
+	 * Only set if this ModelAction is saved on the NodeStack. (A
+	 * ModelAction can be thrown away before it ever enters the NodeStack.)
+	 */
 	Node *node;
 
+	/**
+	 * @brief The sequence number of this action
+	 *
+	 * Except for ATOMIC_UNINIT actions, this number should be unique and
+	 * should represent the action's position in the execution order.
+	 */
 	modelclock_t seq_number;
 
-	/** The clock vector stored with this action; only needed if this
-	 * action is a store release? */
+	/**
+	 * @brief The clock vector for this operation
+	 *
+	 * Technically, this is only needed for potentially synchronizing
+	 * (e.g., non-relaxed) operations, but it is very handy to have these
+	 * vectors for all operations.
+	 */
 	ClockVector *cv;
 
 	bool sleep_flag;