Merge branch 'master' of https://github.com/DistributedClocks/GoVector

Merged comments

Author: wantonsolutions

.travis.yml

@@ -6,4 +6,8 @@ go:
  - master
 
 script:
- go test -v ./...
+ - go test -v ./...
+ - ./test.sh
+
+after_success:
+ - bash <(curl -s https://codecov.io/bash) -t 6e0ff3d8-4792-4b3e-aedf-c589ad356179

README.md

@@ -4,14 +4,16 @@
 [![GoDoc](https://godoc.org/github.com/DistributedClocks/GoVector?status.svg)](https://godoc.org/github.com/DistributedClocks/GoVector)
 [![Go Report Card](https://goreportcard.com/badge/github.com/DistributedClocks/GoVector)](https://goreportcard.com/report/github.com/DistributedClocks/GoVector)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-
+[![Coverage Status](https://img.shields.io/codecov/c/github/DistributedClocks/GoVector/master.svg)](https://codecov.io/gh/DistributedClocks/GoVector)
 
 
 GoVector is a vector clock logging library written in Go. The [vector
 clock algorithm](https://en.wikipedia.org/wiki/Vector_clock) is used
 to order events in distributed systems in the absence of a centralized
 clock. GoVector implements the vector clock algorithm and provides
-feature rich logging, and encoding infrastructure. Vector clock events
+feature rich logging, and encoding infrastructure. 
+
+Vector clock events
 are generated using 3 key functions `PrepareSend`, `UnpackReceive`,
 and `LogLocalEvent`. PrepareSend encodes messages for network
 transport, updates GoVectors local time, and logs a sending event.
@@ -24,12 +26,14 @@ This library can be added to a Go project to generate a
 timestamped log of events in a concurrent or distributed system.
 GoVector is compatible with Go 1.4+ 
 
-* govec/    : Contains the Library and all its dependencies
-* example/  : Contains some examples instrumented with different features of GoVector
+* govec/    	: Contains the Library and all its dependencies
+* govec/vclock	: Pure vector clock library
+* govec/vrpc	: Go's rpc with GoVector integration
+* example/  	: Contains some examples instrumented with different features of GoVector
 
-### Usage
+### Installation
 
-To use GoVector you must have a correctly configured go development
+To install GoVector you must have a correctly configured go development
 environment, see [How to write Go
 Code](https://golang.org/doc/code.html)
 
@@ -41,14 +45,7 @@ tool command:
 *gofmt* will automatically add imports for GoVector. If you do not
 have a working version of *gofmt* GoVector can be imported by adding:
 
-See GoVectors library documentation
-[here](https://godoc.org/github.com/DistributedClocks/GoVector/govec).
-
-- [ ] Write up priority example
-- [ ] Simple write up partial ordering
-- [ ] Write up limitations 1 process per machine
-
-###   Examples
+###   Usage
 
 The following is a basic example of how this library can be used 
 ```go
@@ -57,31 +54,41 @@ The following is a basic example of how this library can be used
 	import "github.com/DistributedClocks/GoVector/govec"
 
 	func main() {
+		//Initialize GoVector logger
 		Logger := govec.InitGoVector("MyProcess", "LogFile")
 
-		//In Sending Process
-		
-		//Prepare a Message
+		//Encode message, and update vector clock
 		messagepayload := []byte("samplepayload")
-		finalsend := Logger.PrepareSend("Sending Message", messagepayload)
+		vectorclockmessage := Logger.PrepareSend("Sending Message", messagepayload)
 
 		//send message
-		connection.Write(finalsend)
+		connection.Write(vectorclockmessage)
 
 		//In Receiving Process
-		
-		//receive message
-		recbuf := Logger.UnpackReceive("Receiving Message", finalsend)
+		connection.Read(vectorclockmessage)
+		//Decode message, and update local vector clock with received clock
+		Logger.UnpackReceive("Receiving Message", &messagepayload, vectorclockmessage)
 
-		//Can be called at any point 
+		//Log a local event
 		Logger.LogLocalEvent("Example Complete")
-		
-		Logger.DisableLogging()
-		//No further events will be written to log file
 	}
 ```
+For complete documentation and small examples see GoVectors [GoDoc](https://godoc.org/github.com/DistributedClocks/GoVector/govec), 
+
+### End to End Examples
+
+* Client-Server GoVector insturmentation [Examples/ClientServer.go](example/ClientServer/ClientServer.go)
+* RPC Client-Server program [Examples/RpcClientServer.go](example/RpcClientServer/RpcClientServer.go)
+
+### Motivation
+
+GoVector was initially developed as a pedagogical tool for students attending UBC's computer science course on distributed systems (CPSC 416). Students new to the development of distributed systems can reason about event orderings by visualizing their executions with [ShiViz](http://bestchai.bitbucket.io/shiviz/). Furthermore GoVectors marshaling functionality reduces student effort in writing networking code which is largely  boiler plate.
+
+As a result of student requests GoVector transformed into a general purpose logging tool. Additional features include optimized IO, priority logging, [TSViz](https://bestchai.bitbucket.io/tsviz/) compatibility and RPC instrumentation.
+
+### Output Example
 
-This produces the log "LogFile.txt" :
+The source code from the useage example produces the following log into a file named "LogFile.txt" :
 
 	MyProcess {"MyProcess":1}
 	Initialization Complete
@@ -92,11 +99,7 @@ This produces the log "LogFile.txt" :
 	MyProcess {"MyProcess":4}
 	Example Complete
 
-An executable example of a similar program can be found in
-[Examples/ClientServer.go](example/ClientServer/ClientServer.go)
 
-An executable example of a RPC Client-Server program can be found in 
-[Examples/RpcClientServer.go](example/RpcClientServer/RpcClientServer.go)
 
 
 Here is a sample output of the priority logger

test.sh

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+
+set -e
+echo "" > coverage.txt
+
+for d in $(go list ./... | grep -v vendor); do
+        go test -race -coverprofile=profile.out -covermode=atomic $d
+        if [ -f profile.out ]; then
+                cat profile.out >> coverage.txt
+                rm profile.out
+        fi
+done
+