From 9209688c955f7924af15da0c79c70948eb481b8c Mon Sep 17 00:00:00 2001
From: Brian Demsky <bdemsky@uci.edu>
Date: Tue, 10 Jul 2012 20:39:58 -0700
Subject: [PATCH] documentation

---
 cyclegraph.cc | 19 +++++++++++++++++++
 cyclegraph.h  |  1 -
 datarace.cc   | 25 ++++++++++++++++++++++++-
 3 files changed, 43 insertions(+), 2 deletions(-)

diff --git a/cyclegraph.cc b/cyclegraph.cc
index 8788bfeb..750086c5 100644
--- a/cyclegraph.cc
+++ b/cyclegraph.cc
@@ -1,10 +1,14 @@
 #include "cyclegraph.h"
 #include "action.h"
 
+/** Initializes a CycleGraph object. */
+
 CycleGraph::CycleGraph() {
 	hasCycles=false;
 }
 
+/** Returns the CycleNode for a given ModelAction. */
+
 CycleNode * CycleGraph::getNode(ModelAction * action) {
 	CycleNode *node=actionToNode.get(action);
 	if (node==NULL) {
@@ -14,6 +18,8 @@ CycleNode * CycleGraph::getNode(ModelAction * action) {
 	return node;
 }
 
+/** Adds an edge between two ModelActions. */
+
 void CycleGraph::addEdge(ModelAction *from, ModelAction *to) {
 	CycleNode *fromnode=getNode(from);
 	CycleNode *tonode=getNode(to);
@@ -24,6 +30,8 @@ void CycleGraph::addEdge(ModelAction *from, ModelAction *to) {
 	fromnode->addEdge(tonode);
 }
 
+/** Checks whether the first CycleNode can reach the second one. */
+
 bool CycleGraph::checkReachable(CycleNode *from, CycleNode *to) {
 	std::vector<CycleNode *> queue;
 	HashTable<CycleNode *, CycleNode *, uintptr_t, 4> discovered;
@@ -47,14 +55,25 @@ bool CycleGraph::checkReachable(CycleNode *from, CycleNode *to) {
 	return false;
 }
 
+/** Returns whether a CycleGraph contains cycles. */
+bool checkForCycles() {
+	return hasCycles;
+}
+
+/** Constructor for a CycleNode. */
+
 CycleNode::CycleNode(ModelAction *modelaction) {
 	action=modelaction;
 }
 
+/** Returns a vector of the edges from a CycleNode. */
+
 std::vector<CycleNode *> * CycleNode::getEdges() {
 	return &edges;
 }
 
+/** Adds an edge to a CycleNode. */
+
 void CycleNode::addEdge(CycleNode * node) {
 	edges.push_back(node);
 }
diff --git a/cyclegraph.h b/cyclegraph.h
index df9d46c1..a748c779 100644
--- a/cyclegraph.h
+++ b/cyclegraph.h
@@ -19,7 +19,6 @@ class CycleGraph {
 	CycleNode * getNode(ModelAction *);
 	HashTable<ModelAction *, CycleNode *, uintptr_t, 4> actionToNode;
 	bool checkReachable(CycleNode *from, CycleNode *to);
-
 	bool hasCycles;
 
 };
diff --git a/datarace.cc b/datarace.cc
index 0fd263cc..29ace0ad 100644
--- a/datarace.cc
+++ b/datarace.cc
@@ -5,14 +5,19 @@
 
 struct ShadowTable *root;
 
+/** This function initialized the data race detector. */
+
 void initRaceDetector() {
 	root=(struct ShadowTable *) calloc(sizeof(struct ShadowTable),1);
 }
 
+/** This function looks up the entry in the shadow table corresponding
+		to a given address.*/
+
 static uint64_t * lookupAddressEntry(void * address) {
 	struct ShadowTable *currtable=root;
 #ifdef BIT48
-	currtable=(struct ShadowTable *) currtable->array[(((uintptr_t)address)>>32)&0xffff];
+	currtable=(struct ShadowTable *) currtable->array[(((uintptr_t)address)>>32)&MASK16BIT];
 	if (currtable==NULL) {
 		currtable=(struct ShadowTable *) (root->array[(((uintptr_t)address)>>32)&MASK16BIT]=calloc(sizeof(struct ShadowTable),1));
 	}
@@ -40,6 +45,11 @@ static bool clock_may_race(ClockVector *clock1, thread_id_t tid1,
 	return tid1 != tid2 && clock2 != 0 && clock1->getClock(tid2) <= clock2;
 }
 
+/** 
+ * Expands a record from the compact form to the full form.  This is
+ * necessary for multiple readers or for very large thread ids or time
+ * stamps. */
+
 static void expandRecord(uint64_t * shadow) {
 	uint64_t shadowval=*shadow;
 
@@ -63,10 +73,15 @@ static void expandRecord(uint64_t * shadow) {
 	*shadow=(uint64_t) record;
 }
 
+/** This function is called when we detect a data race.*/
+
 static void reportDataRace() {
 	printf("The reportDataRace method should report useful things about this datarace!\n");
 }
 
+/** This function does race detection for a write on an expanded
+ *		record. */
+
 void fullRaceCheckWrite(thread_id_t thread, uint64_t * shadow, ClockVector *currClock) {
 	struct RaceRecord * record=(struct RaceRecord *) (*shadow);
 
@@ -101,6 +116,9 @@ void fullRaceCheckWrite(thread_id_t thread, uint64_t * shadow, ClockVector *curr
 	record->writeClock=ourClock;
 }
 
+/** This function does race detection on a write.
+ */
+
 void raceCheckWrite(thread_id_t thread, void *location, ClockVector *currClock) {
 	uint64_t * shadow=lookupAddressEntry(location);
 	uint64_t shadowval=*shadow;
@@ -143,6 +161,9 @@ void raceCheckWrite(thread_id_t thread, void *location, ClockVector *currClock)
 	*shadow = ENCODEOP(0, 0, threadid, ourClock);
 }
 
+/** This function does race detection on a read for an expanded
+ *	record. */
+
 void fullRaceCheckRead(thread_id_t thread, uint64_t * shadow, ClockVector *currClock) {
 	struct RaceRecord * record=(struct RaceRecord *) (*shadow);
 
@@ -200,6 +221,8 @@ void fullRaceCheckRead(thread_id_t thread, uint64_t * shadow, ClockVector *currC
 	record->numReads=copytoindex+1;
 }
 
+/** This function does race detection on a read. */
+
 void raceCheckRead(thread_id_t thread, void *location, ClockVector *currClock) {
 	uint64_t * shadow=lookupAddressEntry(location);
 	uint64_t shadowval=*shadow;
-- 
2.34.1