Merge pull request #50 from DistributedClocks/api_refactor

Refactor the GoVector API for v1.0 release

Author: vaastav

example/ClientServer/ClientServer.go

@@ -29,18 +29,19 @@ func client(listen, send string) {
 	Logger := govec.InitGoVector("client", "clientlogfile", govec.GetDefaultConfig())
 	// sending UDP packet to specified address and port
 	conn := setupConnection(SERVERPORT, CLIENTPORT)
+	opts := govec.GetDefaultLogOptions()
 
 	for i := 0; i < MESSAGES; i++ {
 		outgoingMessage := i
-		outBuf := Logger.PrepareSend("Sending message to server", outgoingMessage)
+		outBuf := Logger.PrepareSend("Sending message to server", outgoingMessage, opts)
 		_, errWrite := conn.Write(outBuf)
 		printErr(errWrite)
 
 		var inBuf [512]byte
 		var incommingMessage int
 		n, errRead := conn.Read(inBuf[0:])
 		printErr(errRead)
-		Logger.UnpackReceive("Received Message from server", inBuf[0:n], &incommingMessage)
+		Logger.UnpackReceive("Received Message from server", inBuf[0:n], &incommingMessage, opts)
 		fmt.Printf("GOT BACK : %d\n", incommingMessage)
 		time.Sleep(1)
 	}
@@ -62,11 +63,12 @@ func server(listen string) {
 	n = 1
 	nMinTwo = 1
 	nMinTwo = 1
+	opts := govec.GetDefaultLogOptions()
 
 	for i := 0; i < MESSAGES; i++ {
 		_, addr, err := conn.ReadFrom(buf[0:])
 		var incommingMessage int
-		Logger.UnpackReceive("Received Message From Client", buf[0:], &incommingMessage)
+		Logger.UnpackReceive("Received Message From Client", buf[0:], &incommingMessage, opts)
 		fmt.Printf("Received %d\n", incommingMessage)
 		printErr(err)
 
@@ -86,7 +88,7 @@ func server(listen string) {
 			break
 		}
 
-		outBuf := Logger.PrepareSend("Replying to client", n)
+		outBuf := Logger.PrepareSend("Replying to client", n, opts)
 
 		conn.WriteTo(outBuf, addr)
 		time.Sleep(1)

govec/example_test.go

@@ -11,14 +11,15 @@ func ExampleGoLog_basic() {
 	//Initialize logger with default configuration. This can be done in
 	//a var block to ensure that GoVector is initialized at boot time.
 	Logger := govec.InitGoVector("MyProcess", "LogFile", govec.GetDefaultConfig())
+	opts := govec.GetDefaultLogOptions()
 
 	//An example message
 	messagepayload := []byte("samplepayload")
 
 	//Prior to sending a message, call PrepareSend on the payload to
 	//encode the payload and append this processes vector clock to the
 	//payload
-	encodedVCpayload := Logger.PrepareSend("Sending Message", messagepayload)
+	encodedVCpayload := Logger.PrepareSend("Sending Message", messagepayload, opts)
 
 	//encodedVCpayload is ready to be written to the network
 	//ex) conn.Write(encodedVCpayload)
@@ -34,12 +35,12 @@ func ExampleGoLog_basic() {
 
 	//Call UnpackReceive on received messages to update local vector
 	//clock values, and decode the original message.
-	Logger.UnpackReceive("Received Message from server", encodedVCpayload, &incommingMessage)
+	Logger.UnpackReceive("Received Message from server", encodedVCpayload, &incommingMessage, opts)
 	fmt.Printf("Received Message: %s\n", incommingMessage)
 
 	//Important local events can be timestamped with vector clocks
 	//using LogLocalEvent, which also increments the local clock.
-	Logger.LogLocalEvent("Example Complete")
+	Logger.LogLocalEvent("Example Complete", opts)
 
 	// Output: Received Message: samplepayload
 }
@@ -55,12 +56,13 @@ func ExampleGoLog_priority() {
 	config.PrintOnScreen = true
 	//Initialize GoVector
 	Logger := govec.InitGoVector("MyProcess", "PrioritisedLogFile", config)
+	opts := govec.GetDefaultLogOptions()
 
-	Logger.LogLocalEventWithPriority("Debug Priority Event", govec.DEBUG)
-	Logger.LogLocalEventWithPriority("Info Priority Event", govec.INFO)
-	Logger.LogLocalEventWithPriority("Warning Priority Event", govec.WARNING)
-	Logger.LogLocalEventWithPriority("Error Priority Event", govec.ERROR)
-	Logger.LogLocalEventWithPriority("Fatal Priority Event", govec.FATAL)
+	Logger.LogLocalEvent("Debug Priority Event", opts.SetPriority(govec.DEBUG))
+	Logger.LogLocalEvent("Info Priority Event", opts.SetPriority(govec.INFO))
+	Logger.LogLocalEvent("Warning Priority Event", opts.SetPriority(govec.WARNING))
+	Logger.LogLocalEvent("Error Priority Event", opts.SetPriority(govec.ERROR))
+	Logger.LogLocalEvent("Fatal Priority Event", opts.SetPriority(govec.FATAL))
 
 	//BUG Output contains timestamps so it cant be tested with *******
 	//comments
@@ -79,20 +81,21 @@ func ExampleGoLog_tSVizCompatable() {
 	config.UseTimestamps = true
 	//Initalize GoVector
 	Logger := govec.InitGoVector("MyProcess", "LogFile", config)
+	opts := govec.GetDefaultLogOptions()
 
 	//In Sending Process
 
 	//Prepare a Message
 	messagepayload := []byte("samplepayload")
-	finalsend := Logger.PrepareSend("Sending Message", messagepayload)
+	finalsend := Logger.PrepareSend("Sending Message", messagepayload, opts)
 	//In Receiving Process
 
 	//receive message
 	var incommingMessage []byte
-	Logger.UnpackReceive("Received Message from server", finalsend, &incommingMessage)
+	Logger.UnpackReceive("Received Message from server", finalsend, &incommingMessage, opts)
 	fmt.Printf("Received Message: %s\n", incommingMessage)
 	//Can be called at any point
-	Logger.LogLocalEvent("Example Complete")
+	Logger.LogLocalEvent("Example Complete", opts)
 
 	// Output: Received Message: samplepayload
 }

govec/govec.go

@@ -89,6 +89,28 @@ func GetDefaultConfig() GoLogConfig {
 	return config
 }
 
+//GoLogOptions provides logging parameters for individual logging statements
+type GoLogOptions struct {
+	// The Log priority for this event
+	Priority LogPriority
+}
+
+//GetDefaultLogOptions returns the default GoLogOptions with default values
+//for the fields
+func GetDefaultLogOptions() GoLogOptions {
+	o := GoLogOptions{Priority: INFO}
+	return o
+}
+
+//SetPriority returns a new GoLogOptions object with its priority field
+//set to Priority. Follows the builder pattern.
+// Priority : (GoLogPriority) The Priority that the new GoLogOptions object must have
+func (o *GoLogOptions) SetPriority(Priority LogPriority) GoLogOptions {
+	opts := *o
+	opts.Priority = Priority
+	return opts
+}
+
 //VClockPayload is the data structure that is actually end on the wire
 type VClockPayload struct {
 	Pid     string
@@ -450,32 +472,26 @@ func (gv *GoLog) tickClock() {
 	gv.currentVC.Tick(gv.pid)
 }
 
-//LogLocalEvent Increments current vector timestamp and logs it into
-//Log File.  * LogMessage (string) : Message to be logged
-func (gv *GoLog) LogLocalEvent(Message string) (logSuccess bool) {
-	return gv.LogLocalEventWithPriority(Message, gv.priority)
-}
-
 //LogLocalEventWithPriority implements LogLocalEvent with priority
 //levels. If the priority of the logger is lower than or equal to the
 //priority of this event then the current vector timestamp is
 //incremented and the message is logged it into the Log File. A color
 //coded string is also printed on the console.
 //* LogMessage (string) : Message to be logged
 //* Priority (LogPriority) : Priority at which the message is to be logged
-func (gv *GoLog) LogLocalEventWithPriority(LogMessage string, Priority LogPriority) (logSuccess bool) {
+func (gv *GoLog) LogLocalEvent(LogMessage string, opts GoLogOptions) (logSuccess bool) {
 	logSuccess = true
 	gv.mutex.Lock()
-	if Priority >= gv.priority {
-		prefix := prefixLookup[Priority]
+	if opts.Priority >= gv.priority {
+		prefix := prefixLookup[opts.Priority]
 		gv.tickClock()
-		logSuccess = gv.logWriteWrapper(prefix+LogMessage, "Something went Wrong, Could not Log LocalEvent!", Priority)
+		logSuccess = gv.logWriteWrapper(prefix+LogMessage, "Something went Wrong, Could not Log LocalEvent!", opts.Priority)
 	}
 	gv.mutex.Unlock()
 	return
 }
 
-//PrepareSendWithPriority is meant to be used immediately before sending.
+//PrepareSend 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.
@@ -484,14 +500,14 @@ func (gv *GoLog) LogLocalEventWithPriority(LogMessage string, Priority LogPriori
 //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 (gv *GoLog) PrepareSendWithPriority(mesg string, buf interface{}, Priority LogPriority) (encodedBytes []byte) {
+func (gv *GoLog) PrepareSend(mesg string, buf interface{}, opts GoLogOptions) (encodedBytes []byte) {
 
 	//Converting Vector Clock from Bytes and Updating the gv clock
 	gv.mutex.Lock()
-	if Priority >= gv.priority {
+	if opts.Priority >= gv.priority {
 		gv.tickClock()
 
-		gv.logWriteWrapper(mesg, "Something went wrong, could not log prepare send", Priority)
+		gv.logWriteWrapper(mesg, "Something went wrong, could not log prepare send", opts.Priority)
 
 		d := VClockPayload{Pid: gv.pid, VcMap: gv.currentVC.GetMap(), Payload: buf}
 
@@ -508,19 +524,6 @@ func (gv *GoLog) PrepareSendWithPriority(mesg string, buf interface{}, Priority
 	return
 }
 
-//PrepareSend 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 (gv *GoLog) PrepareSend(mesg string, buf interface{}) []byte {
-	return gv.PrepareSendWithPriority(mesg, buf, gv.priority)
-}
-
 func (gv *GoLog) mergeIncomingClock(mesg string, e VClockPayload, Priority LogPriority) {
 
 	// First, tick the local clock
@@ -530,19 +533,19 @@ func (gv *GoLog) mergeIncomingClock(mesg string, e VClockPayload, Priority LogPr
 	gv.logWriteWrapper(mesg, "Something went Wrong, Could not Log!", Priority)
 }
 
-//UnpackReceiveWithPriority is used to unmarshall network data into local structures.
+//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 (gv *GoLog) UnpackReceiveWithPriority(mesg string, buf []byte, unpack interface{}, Priority LogPriority) {
+func (gv *GoLog) UnpackReceive(mesg string, buf []byte, unpack interface{}, opts GoLogOptions) {
 
 	gv.mutex.Lock()
 
-	if Priority >= gv.priority {
+	if opts.Priority >= gv.priority {
 		e := VClockPayload{}
 		e.Payload = unpack
 
@@ -553,22 +556,9 @@ func (gv *GoLog) UnpackReceiveWithPriority(mesg string, buf []byte, unpack inter
 		}
 
 		// Increment and merge the incoming clock
-		gv.mergeIncomingClock(mesg, e, Priority)
+		gv.mergeIncomingClock(mesg, e, opts.Priority)
 	}
 	gv.mutex.Unlock()
 
 }
 
-/*
-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 (gv *GoLog) UnpackReceive(mesg string, buf []byte, unpack interface{}) {
-	gv.UnpackReceiveWithPriority(mesg, buf, unpack, gv.priority)
-}

govec/govec_test.go

@@ -26,7 +26,8 @@ func TestBasicInit(t *testing.T) {
 func TestLogLocal(t *testing.T) {
 
 	gv := InitGoVector(TestPID, "TestLogFile", GetDefaultConfig())
-	gv.LogLocalEvent("TestMessage1")
+	opts := GetDefaultLogOptions()
+	gv.LogLocalEvent("TestMessage1", opts)
 
 	vc := gv.GetCurrentVC()
 	n, _ := vc.FindTicks(TestPID)
@@ -38,15 +39,16 @@ func TestLogLocal(t *testing.T) {
 func TestSendAndUnpackInt(t *testing.T) {
 
 	gv := InitGoVector(TestPID, "TestLogFile", GetDefaultConfig())
-	packed := gv.PrepareSend("TestMessage1", 1337)
+	opts := GetDefaultLogOptions()
+	packed := gv.PrepareSend("TestMessage1", 1337, opts)
 
 	vc := gv.GetCurrentVC()
 	n, _ := vc.FindTicks(TestPID)
 
 	AssertEquals(t, uint64(2), n, "PrepareSend: Clock value incremented")
 
 	var response int
-	gv.UnpackReceive("TestMessage2", packed, &response)
+	gv.UnpackReceive("TestMessage2", packed, &response, opts)
 
 	vc = gv.GetCurrentVC()
 	n, _ = vc.FindTicks(TestPID)
@@ -59,15 +61,16 @@ func TestSendAndUnpackInt(t *testing.T) {
 func TestSendAndUnpackStrings(t *testing.T) {
 
 	gv := InitGoVector(TestPID, "TestLogFile", GetDefaultConfig())
-	packed := gv.PrepareSend("TestMessage1", "DistClocks!")
+	opts := GetDefaultLogOptions()
+	packed := gv.PrepareSend("TestMessage1", "DistClocks!", opts)
 
 	vc := gv.GetCurrentVC()
 	n, _ := vc.FindTicks(TestPID)
 
 	AssertEquals(t, uint64(2), n, "PrepareSend: Clock value incremented. ")
 
 	var response string
-	gv.UnpackReceive("TestMessage2", packed, &response)
+	gv.UnpackReceive("TestMessage2", packed, &response, opts)
 
 	vc = gv.GetCurrentVC()
 	n, _ = vc.FindTicks(TestPID)
@@ -80,29 +83,31 @@ func TestSendAndUnpackStrings(t *testing.T) {
 func BenchmarkPrepare(b *testing.B) {
 
 	gv := InitGoVector(TestPID, "TestLogFile", GetDefaultConfig())
+	opts := GetDefaultLogOptions()
 
 	var packed []byte
 
 	for i := 0; i < b.N; i++ {
-		packed = gv.PrepareSend("TestMessage1", 1337)
+		packed = gv.PrepareSend("TestMessage1", 1337, opts)
 	}
 
 	var response int
-	gv.UnpackReceive("TestMessage2", packed, &response)
+	gv.UnpackReceive("TestMessage2", packed, &response, opts)
 
 }
 
 func BenchmarkUnpack(b *testing.B) {
 
 	gv := InitGoVector(TestPID, "TestLogFile", GetDefaultConfig())
+	opts := GetDefaultLogOptions()
 
 	var packed []byte
-	packed = gv.PrepareSend("TestMessage1", 1337)
+	packed = gv.PrepareSend("TestMessage1", 1337, opts)
 
 	var response int
 
 	for i := 0; i < b.N; i++ {
-		gv.UnpackReceive("TestMessage2", packed, &response)
+		gv.UnpackReceive("TestMessage2", packed, &response, opts)
 	}
 
 }

govec/vrpc/vrpc.go

@@ -78,7 +78,8 @@ func (c *RPCClientCodec) WriteRequest(req *rpc.Request, param interface{}) (err
 	if err = c.Enc.Encode(req); err != nil {
 		return
 	}
-	buf := c.Logger.PrepareSend("Making RPC call", param)
+	opts := govec.GetDefaultLogOptions()
+	buf := c.Logger.PrepareSend("Making RPC call", param, opts)
 	if err = c.Enc.Encode(buf); err != nil {
 		return
 	}
@@ -98,7 +99,8 @@ func (c *RPCClientCodec) ReadResponseBody(body interface{}) (err error) {
 	if err = c.Dec.Decode(&buf); err != nil {
 		return
 	}
-	c.Logger.UnpackReceive("Received RPC Call response from server", buf, body)
+	opts := govec.GetDefaultLogOptions()
+	c.Logger.UnpackReceive("Received RPC Call response from server", buf, body, opts)
 	return nil
 }
 
@@ -131,15 +133,17 @@ func (c *RPCServerCodec) ReadRequestBody(body interface{}) (err error) {
 	if err = c.Dec.Decode(&buf); err != nil {
 		return
 	}
-	c.Logger.UnpackReceive("Received RPC request", buf, body)
+	opts := govec.GetDefaultLogOptions()
+	c.Logger.UnpackReceive("Received RPC request", buf, body, opts)
 	return nil
 }
 
 //WriteResponse sends an rpc response, and it's associated result back
 //to the client
 func (c *RPCServerCodec) WriteResponse(r *rpc.Response, body interface{}) (err error) {
 	Encode(c, r)
-	buf := c.Logger.PrepareSend("Sending response to RPC request", body)
+	opts := govec.GetDefaultLogOptions()
+	buf := c.Logger.PrepareSend("Sending response to RPC request", body, opts)
 	Encode(c, buf)
 	return c.EncBuf.Flush()
 }