GoVector

This library can be added to a Go project to generate a ShiViz-compatible vector-clock timestamped log of events in a concurrent or distributed system. GoVec is compatible with Go 1.4+

• govec/ : Contains the Library and all its dependencies
• example/ : Contains a client server example instrumented with GoVec
• test/ : A small set of tests for the library
• broker/ : Automatic live integration with ShiViz (Under Development)

Usage

To use GoVec you must have a correctly configured go development environment, see How to write Go Code

Once you set up your environment, GoVec can be installed with the go tool command:

go get github.com/DistributedClocks/GoVector

gofmt will automatically add imports for GoVec. If you do not have a working version of gofmt GoVec can be imported by adding:

    "import github.com/DistributedClocks/GoVector/govec"

Index

type GoLog

func InitGoVector(ProcessName, LogName string) *GoLog

func InitGoVectorMultipleExecutions(ProcessName, LogName string) *GoLog

func PrepareSend(LogMessage string, buf interface{}) []byte

func UnpackReceive(LogMessage string, buf []byte, unpack interface{})

func LogLocalEvent(string LogMessage)

func LogThis(Message string, ProcessID string, VCString string) bool

func DisableLogging()

type GoLog

	type GoLog struct{
		// contains filtered or unexported fields
	}

The GoLog struct provides an interface to creating and maintaining vector timestamp entries in the generated log file

func InitGoVector

	func InitGoVector(ProcessName, LogName string) *GoLog

Returns a Go Log Struct taking in two arguments and truncates previous logs:

• MyProcessName (string): local process name; must be unique in your distributed system.
• LogFileName (string) : name of the log file that will store info. Any old log with the same name will be truncated

func InitGoVectorMultipleExecutions

	func InitGoVectorMultipleExecutions(ProcessName, LogName string) *GoLog

Returns a Go Log Struct taking in two arguments without truncating previous log entry:

• MyProcessName (string): local process name; must be unique in your distributed system.
• LogFileName (string) : name of the log file that will store info. Each run will append to log file separated by "=== Execution # ==="

func PrepareSend

	func PrepareSend(LogMessage string, buf interface{}) byte[]

This function is meant to be used immediately before sending. LogMessage will be logged along with the time of the send buf is encode-able data (structure or basic type) Returned is an encoded byte array with logging information

This function is meant to be called before sending a packet. Usually, it should Update the Vector Clock for its own process, package with the clock using gob support and return the new byte array that should be sent onwards using the Send Command

func UnpackReceive

	func UnpackReceive(LogMessage string, buf byte[], unpack interface{})

UnpackReceive is used to unmarshall network data into local structures. LogMessage will be logged along with the vector time the receive happened buf is the network data, previously packaged by PrepareSend unpack is a pointer to a structure, the same as was packed by PrepareSend

This function is meant to be called immediately after receiving a packet. It unpacks the data by the program, the vector clock. It updates vector clock and logs it. and returns the user data

func LogLocalEvent

	func LogLocalEvent(LogMessage string)

Increments current vector timestamp and logs it into Log File.

func LogThis

func LogThis(Message string, ProcessID string, VCString string) bool

Logs a message along with a processID and a vector clock, the VCString must be a valid vector clock, true is returned on success

func DisableLogging

	func DisableLogging()

Disables Logging. Log messages will not appear in Log file any longer. Note: For the moment, the vector clocks are going to continue being updated.

Examples

The following is a basic example of how this library can be used

	package main

	import "./govec"

	func main() {
		Logger := govec.InitGoVector("MyProcess", "LogFile")
		
		//In Sending Process
		
		//Prepare a Message
		messagepayload := []byte("samplepayload")
		finalsend := Logger.PrepareSend("Sending Message", messagepayload)
		
		//send message
		connection.Write(finalsend)

		//In Receiving Process
		
		//receive message
		recbuf := Logger.UnpackReceive("Receiving Message", finalsend)

		//Can be called at any point 
		Logger.LogLocalEvent("Example Complete")
		
		Logger.DisableLogging()
		//No further events will be written to log file
	}

This produces the log "LogFile.txt" :

MyProcess {"MyProcess":1}
Initialization Complete
MyProcess {"MyProcess":2}
Sending Message
MyProcess {"MyProcess":3}
Receiving Message
MyProcess {"MyProcess":4}
Example Complete

An executable example of a similar program can be found in Examples/ClientServer.go