fixed and improved examples for GoLog

Author: wantonsolutions

govec/example_test.go

@@ -6,53 +6,54 @@ import (
 	"github.com/DistributedClocks/GoVector/govec"
 )
 
-func ExampleGoLog() {
+//Basic example of GoVectors key functions
+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())
 
-	//In Sending Process
-
-	//Prepare a Message
+	//An example message
 	messagepayload := []byte("samplepayload")
-	finalsend := Logger.PrepareSend("Sending Message", messagepayload)
 
-	//In Receiving Process
+	//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)
 
-	//receive message
-	var incommingMessage []byte
-	Logger.UnpackReceive("Received Message from server", finalsend, &incommingMessage)
-	fmt.Printf("Received Message: %s\n", incommingMessage)
-	//Can be called at any point
-	Logger.LogLocalEvent("Example Complete")
+	//encodedVCpayload is ready to be written to the network
+	//ex) conn.Write(encodedVCpayload)
 
-	// Output: Received Message: samplepayload
-}
-
-func ExampleGoTSLog() {
-	config := govec.GetDefaultConfig()
-	config.UseTimestamps = true
-	Logger := govec.InitGoVector("MyProcess", "LogFile", config)
-
-	//In Sending Process
+	//Receiving Example
+	//First allocate a buffer to receive a message into. This must be
+	//the same type as the encoded message. Here incommingMessage and
+	//messagepayload are the same type []byte.
+	var incommingMessage []byte
 
-	//Prepare a Message
-	messagepayload := []byte("samplepayload")
-	finalsend := Logger.PrepareSend("Sending Message", messagepayload)
-	//In Receiving Process
+	//Prior to unpacking call a message must be received
+	//ex) conn.Read(encodedVCPayload)
 
-	//receive message
-	var incommingMessage []byte
-	Logger.UnpackReceive("Received Message from server", finalsend, &incommingMessage)
+	//Call UnpackReceive on received messages to update local vector
+	//clock values, and decode the original message.
+	Logger.UnpackReceive("Received Message from server", encodedVCpayload, &incommingMessage)
 	fmt.Printf("Received Message: %s\n", incommingMessage)
-	//Can be called at any point
+
+	//Important local events can be timestamped with vector clocks
+	//using LogLocalEvent, which also increments the local clock.
 	Logger.LogLocalEvent("Example Complete")
 
 	// Output: Received Message: samplepayload
 }
 
-func ExampleGoPriorityLog() {
+//Logging with priority trims all events which are lower from the
+//specified priority from the log. This functionality is useful for
+//isolating behaviour such as recovery protocols, from common
+//behaviour like heartbeats.
+func ExampleGoLog_priority() {
+	//Access GoVectors default configureation, and set priority
 	config := govec.GetDefaultConfig()
 	config.Priority = govec.DEBUG
 	config.PrintOnScreen = true
+	//Initialize GoVector
 	Logger := govec.InitGoVector("MyProcess", "PrioritisedLogFile", config)
 
 	Logger.LogLocalEventWithPriority("Debug Priority Event", govec.DEBUG)
@@ -69,3 +70,29 @@ func ExampleGoPriorityLog() {
 	//Error Priority Event
 	//Fatal Priority Event
 }
+
+//GoVector logs can be used to associate real time events for
+//visualization with TSViz
+func ExampleGoLog_tSVizCompatable() {
+	//Access config and set timestamps (realtime) to true
+	config := govec.GetDefaultConfig()
+	config.UseTimestamps = true
+	//Initalize GoVector
+	Logger := govec.InitGoVector("MyProcess", "LogFile", config)
+
+	//In Sending Process
+
+	//Prepare a Message
+	messagepayload := []byte("samplepayload")
+	finalsend := Logger.PrepareSend("Sending Message", messagepayload)
+	//In Receiving Process
+
+	//receive message
+	var incommingMessage []byte
+	Logger.UnpackReceive("Received Message from server", finalsend, &incommingMessage)
+	fmt.Printf("Received Message: %s\n", incommingMessage)
+	//Can be called at any point
+	Logger.LogLocalEvent("Example Complete")
+
+	// Output: Received Message: samplepayload
+}