Merge pull request #5 from dl1998/improve-documentation

Improve documentation

README.md

@@ -4,6 +4,58 @@
 
 Minimalistic scheduler library for GoLang.
 
+
+## Installation
+
+```bash
+go get github.com/dl1998/go-scheduler
+```
+
+or
+
+```bash
+go install github.com/dl1998/[email protected]
+```
+
 ## Usage
 
-Check examples provided in the [examples](./examples).
+Check examples provided in the [examples](./examples).
+
+For scheduling a new task:
+
+```go
+taskName := "Task Name"
+taskStartTime := nil // To schedule immediately.
+taskDuration := 10 * time.Second // How long it will be active (10 seconds).
+taskInterval := time.Second // Periodicity with which function will be executed (every second).
+taskFunction := function(task *Task, name: string) {
+	fmt.Printf("Hello, %s!\n", name)
+}
+
+newScheduler := scheduler.New()
+
+newTask := newScheduler.ScheduleTask(taskName, taskStartTime, taskDuration, taskInterval, taskFunction, "world")
+```
+
+By default program will be interrupted if there is no other code to be performed. In order to wait until task will be completed use:
+
+```go
+newTask.Wait()
+```
+
+It will block program execution and wait until task will be completed. Alternatively you could use sleep:
+
+```go
+time.Sleep(taskDuration)
+```
+
+However, if you want to interrupt task before it has been finished, you could do it manually using:
+
+```go
+
+newScheduler.StopTask(newTask)
+```
+
+## Class Diagram
+
+![Class Diagram](./docs/architecture/diagrams/svg/class_diagram.svg)

docs/architecture/diagrams/plantuml/class_diagram.plantuml

@@ -0,0 +1,42 @@
+@startuml
+top to bottom direction
+
+package pkg.scheduler {
+    class "<<module>>" {
+        + New() : *Scheduler
+        + NewTask(id : string, start : *time.Time, duration : *time.Duration, interval : time.Duration, stopSignal : chan bool, context : map[string]interface{}) : *Task
+        + NewSimpleTask(name : string, interval : time.Duration) : *Task
+        - callFunction(function : interface{}, parameters : ...interface{})
+    }
+
+    struct Scheduler {
+        + Tasks : []*Tasks
+        + FindTaskIndex(scheduledTask : *Task) : int
+        + FindTaskByName(name : string) : *Task
+        + FindTaskByID(id : string) : *Task
+        + ScheduleTask(name : string, startTime : *time.Time, duration : *time.Duration, interval : time.Duration, function : interface{}, parameters : ...interface{}) : *Task
+        + StopTask(task : *Task) : error
+        - removeTask(task : *Task) : error
+    }
+
+    struct Task {
+        + ID : string
+        + Name : string
+        + Start : *time.Time
+        + Duration : *time.Time
+        + Interval : time.Duration
+        - stopSignal : chan bool
+        - context : map[string]interface{}
+        + String() : string
+        + GetFromContext(name : string) : interface{}
+        + SetToContext(name : string, value : interface{})
+        + RemoveFromContext(name : string)
+        + Wait()
+    }
+}
+
+"pkg.scheduler.<<module>>" ..> pkg.scheduler.Scheduler : uses
+"pkg.scheduler.<<module>>" ..> pkg.scheduler.Task : uses
+pkg.scheduler.Scheduler *-- "0..*" pkg.scheduler.Task : contains
+
+@enduml

examples/README.md

@@ -0,0 +1,24 @@
+# Examples
+
+This package contains examples how to use Scheduler.
+
+## basic
+
+Demonstrates how to schedule the simplest task possible. 
+It schedules task that prints "Hello, World!" during 10 second with interval of 1 second.
+
+## interrupt
+
+Demonstrates how to schedule task that prints counter value, where each execution it increases its value by 1. 
+After scheduling it waits 5 seconds and interrupts task execution.
+
+## taskcontext
+
+Demonstrates how to schedule a task with data that are shared between executions in the Task.context.
+It schedules a task that performs function which reads counter from Task.context,
+if counter is not found in the task context it set counter as 0.
+After printing "[${counter}] Hello, World!", it increases counter and save it to Task.context.
+
+## withparameters
+
+Demonstrates how to pass argument(s) to the function that will be scheduled.

examples/basic/main.go

@@ -1,3 +1,4 @@
+// Example that shows how to schedule simple task.
 package main
 
 import (
@@ -6,28 +7,22 @@ import (
 	"time"
 )
 
-func DemoFunction(task *scheduler.Task, message string) {
-	contextCounterName := "counter"
-	if task.GetFromContext(contextCounterName) == nil {
-		task.SetToContext(contextCounterName, 0)
-	}
-	counter := task.GetFromContext(contextCounterName).(int)
-	fmt.Printf("[%d] %s\n", counter, message)
-	task.SetToContext(contextCounterName, counter+1)
+func DemoFunction(task *scheduler.Task) {
+	fmt.Println("Hello, World!")
 }
 
-func ScheduleDemoTask(scheduler scheduler.Scheduler) *scheduler.Task {
+func ScheduleDemoTask(scheduler *scheduler.Scheduler) *scheduler.Task {
 	name := "Demo Task"
 	duration := 10 * time.Second
 	interval := time.Second
 
-	return scheduler.ScheduleTask(name, nil, &duration, interval, DemoFunction, "Hello, World!")
+	return scheduler.ScheduleTask(name, nil, &duration, interval, DemoFunction)
 }
 
 func main() {
 	newScheduler := scheduler.New()
 
-	task := ScheduleDemoTask(*newScheduler)
+	task := ScheduleDemoTask(newScheduler)
 
 	task.Wait()
 

examples/interrupt/main.go

@@ -0,0 +1,41 @@
+// Example that shows how to interrupt task that is currently scheduled.
+package main
+
+import (
+	"fmt"
+	"github.com/dl1998/go-scheduler/pkg/scheduler"
+	"time"
+)
+
+func DemoFunction(task *scheduler.Task) {
+	contextCounterName := "counter"
+	if task.GetFromContext(contextCounterName) == nil {
+		task.SetToContext(contextCounterName, 0)
+	}
+	counter := task.GetFromContext(contextCounterName).(int)
+	fmt.Println(counter)
+	task.SetToContext(contextCounterName, counter+1)
+}
+
+func ScheduleDemoTask(scheduler *scheduler.Scheduler) *scheduler.Task {
+	name := "Demo Task"
+	duration := 10 * time.Second
+	interval := time.Second
+
+	return scheduler.ScheduleTask(name, nil, &duration, interval, DemoFunction)
+}
+
+func main() {
+	newScheduler := scheduler.New()
+
+	task := ScheduleDemoTask(newScheduler)
+
+	time.Sleep(5 * time.Second)
+
+	if err := newScheduler.StopTask(task); err != nil {
+		panic(err)
+	}
+
+	fmt.Println()
+	fmt.Println(task)
+}

examples/taskcontext/main.go

@@ -0,0 +1,37 @@
+// Example that shows how to use Task context.
+package main
+
+import (
+	"fmt"
+	"github.com/dl1998/go-scheduler/pkg/scheduler"
+	"time"
+)
+
+func DemoFunction(task *scheduler.Task) {
+	contextCounterName := "counter"
+	if task.GetFromContext(contextCounterName) == nil {
+		task.SetToContext(contextCounterName, 0)
+	}
+	counter := task.GetFromContext(contextCounterName).(int)
+	fmt.Printf("[%d] Hello, World!\n", counter)
+	task.SetToContext(contextCounterName, counter+1)
+}
+
+func ScheduleDemoTask(scheduler *scheduler.Scheduler) *scheduler.Task {
+	name := "Demo Task"
+	duration := 10 * time.Second
+	interval := time.Second
+
+	return scheduler.ScheduleTask(name, nil, &duration, interval, DemoFunction)
+}
+
+func main() {
+	newScheduler := scheduler.New()
+
+	task := ScheduleDemoTask(newScheduler)
+
+	task.Wait()
+
+	fmt.Println()
+	fmt.Println(task)
+}

examples/withparameters/main.go

@@ -0,0 +1,33 @@
+// Example that shows how to schedule task and provide parameters to the
+// scheduled function.
+package main
+
+import (
+	"fmt"
+	"github.com/dl1998/go-scheduler/pkg/scheduler"
+	"os"
+	"time"
+)
+
+func DemoFunction(task *scheduler.Task, name string) {
+	fmt.Printf("Hello, %s!\n", name)
+}
+
+func ScheduleDemoTask(scheduler *scheduler.Scheduler) *scheduler.Task {
+	name := "Demo Task"
+	duration := 10 * time.Second
+	interval := time.Second
+
+	return scheduler.ScheduleTask(name, nil, &duration, interval, DemoFunction, os.Getenv("USER"))
+}
+
+func main() {
+	newScheduler := scheduler.New()
+
+	task := ScheduleDemoTask(newScheduler)
+
+	task.Wait()
+
+	fmt.Println()
+	fmt.Println(task)
+}