docs: add example

gochore · Mar 11, 2020 · 264293a · 264293a
1 parent bb35d6f
commit 264293a
Show file tree

Hide file tree

Showing 4 changed files with 241 additions and 1 deletion.
diff --git a/README.md b/README.md
@@ -6,4 +6,119 @@
 [![GitHub go.mod Go version](https://img.shields.io/github/go-mod/go-version/gochore/dcron)](https://github.com/gochore/dcron/blob/master/go.mod)
 [![GitHub tag (latest by date)](https://img.shields.io/github/v/tag/gochore/dcron)](https://github.com/gochore/dcron/releases)
 
-\[WIP\] A distributed cron framework.
+A distributed cron framework.
+
+## Example
+
+First of all, you should implement a distributed atomic operation:
+
+```go
+type Atomic interface {
+	SetIfNotExists(key, value string) bool
+}
+```
+
+You can implement it any way you like, for example, via Redis `SetNX`:
+
+```go
+type RedisAtomic struct {
+	client *redis.Client
+}
+
+func (m *RedisAtomic) SetIfNotExists(key, value string) bool {
+	ret := m.client.SetNX(key, value, time.Hour)
+	return ret.Err() == nil && ret.Val()
+}
+```
+
+Now we can create a cron with that:
+
+```go
+	ra := &RedisAtomic{
+		// init redis client
+	}
+	cron := dcron.NewCron(dcron.WithKey("TestCron"), dcron.WithAtomic(ra))
+```
+
+There are many ways to create jobs:
+- use `dcron.NewJob`;
+- use `dcron.NewJobWithAutoKey`;
+- implement interface `dcron.Job`.
+
+```go
+
+func main {
+	job1 := dcron.NewJob("Job1", "*/15 * * * * *", func(ctx context.Context) error {
+		if task, ok := dcron.TaskFromContext(ctx); ok {
+			log.Println("run:", task.Job.Spec(), task.Key)
+		}
+		// do something
+		return nil
+	})
+	job2 := dcron.NewJobWithAutoKey("*/20 * * * * *", Job2)
+	job3 := Job3{}
+}
+
+func Job2(ctx context.Context) error {
+	if task, ok := dcron.TaskFromContext(ctx); ok {
+		log.Println("run:", task.Job.Spec(), task.Key)
+	}
+	// do something
+	return nil
+}
+
+type Job3 struct {
+}
+
+func (j Job3) Key() string {
+	return "Job3"
+}
+
+func (j Job3) Spec() string {
+	return "*/30 * * * * *"
+}
+
+func (j Job3) Run(ctx context.Context) error {
+	if task, ok := dcron.TaskFromContext(ctx); ok {
+		log.Println("run:", task.Job.Spec(), task.Key)
+	}
+	// do something
+	return nil
+}
+
+func (j Job3) Options() []dcron.JobOption {
+	return nil
+}
+```
+
+Finally, add the jobs to the cron, and start it:
+
+```go
+	if err := cron.AddJobs(job1, job2, job3); err != nil {
+		panic(err)
+	}
+
+	cron.Start()
+	log.Println("cron started")
+	time.Sleep(time.Minute)
+	<-cron.Stop().Done()
+	log.Println("cron stopped")
+```
+
+You will see logging:
+
+```text
+2020/03/11 15:28:04 cron started
+2020/03/11 15:28:15 run: */15 * * * * * dcron:TestCron.Job1@1583911695
+2020/03/11 15:28:20 run: */20 * * * * * dcron:TestCron.Job2@1583911700
+2020/03/11 15:28:30 run: */30 * * * * * dcron:TestCron.Job3@1583911710
+2020/03/11 15:28:30 run: */15 * * * * * dcron:TestCron.Job1@1583911710
+2020/03/11 15:28:40 run: */20 * * * * * dcron:TestCron.Job2@1583911720
+2020/03/11 15:28:45 run: */15 * * * * * dcron:TestCron.Job1@1583911725
+2020/03/11 15:29:00 run: */30 * * * * * dcron:TestCron.Job3@1583911740
+2020/03/11 15:29:00 run: */15 * * * * * dcron:TestCron.Job1@1583911740
+2020/03/11 15:29:00 run: */20 * * * * * dcron:TestCron.Job2@1583911740
+2020/03/11 15:29:04 cron stopped
+```
+
+There is the complete example: [_example/main.go](https://github.com/gochore/dcron/tree/_example/main.go).
diff --git a/_example/go.mod b/_example/go.mod
@@ -0,0 +1,8 @@
+module example
+
+go 1.13
+
+require (
+	github.com/go-redis/redis/v7 v7.2.0
+	github.com/gochore/dcron v0.5.0
+)
diff --git a/_example/go.sum b/_example/go.sum
@@ -0,0 +1,40 @@
+github.com/fsnotify/fsnotify v1.4.7/go.mod h1:jwhsz4b93w/PPRr/qN1Yymfu8t87LnFCMoQvtojpjFo=
+github.com/go-redis/redis v6.15.7+incompatible h1:3skhDh95XQMpnqeqNftPkQD9jL9e5e36z/1SUm6dy1U=
+github.com/go-redis/redis/v7 v7.2.0 h1:CrCexy/jYWZjW0AyVoHlcJUeZN19VWlbepTh1Vq6dJs=
+github.com/go-redis/redis/v7 v7.2.0/go.mod h1:JDNMw23GTyLNC4GZu9njt15ctBQVn7xjRfnwdHj/Dcg=
+github.com/gochore/dcron v0.5.0 h1:IbBVp0R6SRSFDL71+AMOaX185oM9XuAEbxdisW4NQ8I=
+github.com/gochore/dcron v0.5.0/go.mod h1:zAQ90N7x0Xtc97/EhCJV+gAHOpMji5jLMJl/tLa/FRU=
+github.com/golang/mock v1.4.1/go.mod h1:UOMv5ysSaYNkG+OFQykRIcU/QvvxJf3p21QfJ2Bt3cw=
+github.com/golang/protobuf v1.2.0/go.mod h1:6lQm79b+lXiMfvg/cZm0SGofjICqVBUtrP5yJMmIC1U=
+github.com/golang/protobuf v1.3.2/go.mod h1:6lQm79b+lXiMfvg/cZm0SGofjICqVBUtrP5yJMmIC1U=
+github.com/hpcloud/tail v1.0.0/go.mod h1:ab1qPbhIpdTxEkNHXyeSf5vhxWSCs/tWer42PpOxQnU=
+github.com/kr/pretty v0.1.0/go.mod h1:dAy3ld7l9f0ibDNOQOHHMYYIIbhfbHSm3C4ZsoJORNo=
+github.com/kr/pty v1.1.1/go.mod h1:pFQYn66WHrOpPYNljwOMqo10TkYh1fy3cYio2l3bCsQ=
+github.com/kr/text v0.1.0/go.mod h1:4Jbv+DJW3UT/LiOwJeYQe1efqtUx/iVham/4vfdArNI=
+github.com/onsi/ginkgo v1.6.0/go.mod h1:lLunBs/Ym6LB5Z9jYTR76FiuTmxDTDusOGeTQH+WWjE=
+github.com/onsi/ginkgo v1.10.1/go.mod h1:lLunBs/Ym6LB5Z9jYTR76FiuTmxDTDusOGeTQH+WWjE=
+github.com/onsi/gomega v1.7.0/go.mod h1:ex+gbHU/CVuBBDIJjb2X0qEXbFg53c61hWP/1CpauHY=
+github.com/robfig/cron/v3 v3.0.1 h1:WdRxkvbJztn8LMz/QEvLN5sBU+xKpSqwwUO1Pjr4qDs=
+github.com/robfig/cron/v3 v3.0.1/go.mod h1:eQICP3HwyT7UooqI/z+Ov+PtYAWygg1TEWWzGIFLtro=
+golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w=
+golang.org/x/net v0.0.0-20180906233101-161cd47e91fd/go.mod h1:mL1N/T3taQHkDXs73rZJwtUhF3w3ftmwwsq0BUmARs4=
+golang.org/x/net v0.0.0-20190311183353-d8887717615a/go.mod h1:t9HGtf8HONx5eT2rtn7q6eTqICYqUVnKs3thJo3Qplg=
+golang.org/x/net v0.0.0-20190923162816-aa69164e4478/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s=
+golang.org/x/sync v0.0.0-20180314180146-1d60e4601c6f/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
+golang.org/x/sync v0.0.0-20190423024810-112230192c58/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
+golang.org/x/sys v0.0.0-20180909124046-d0be0721c37e/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
+golang.org/x/sys v0.0.0-20190215142949-d0b11bdaac8a/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
+golang.org/x/sys v0.0.0-20191010194322-b09406accb47/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/text v0.0.0-20170915032832-14c0d48ead0c/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
+golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
+golang.org/x/text v0.3.2/go.mod h1:bEr9sfX3Q8Zfm5fL9x+3itogRgK3+ptLWKqgva+5dAk=
+golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ=
+golang.org/x/tools v0.0.0-20190425150028-36563e24a262/go.mod h1:RgjU9mgBXZiqYHBnxXauZ1Gv1EHHAz9KjViQ78xBX0Q=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/check.v1 v1.0.0-20190902080502-41f04d3bba15/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/fsnotify.v1 v1.4.7/go.mod h1:Tz8NjZHkW78fSQdbUxIjBTcgA1z1m8ZHf0WmKUhAMys=
+gopkg.in/tomb.v1 v1.0.0-20141024135613-dd632973f1e7/go.mod h1:dt/ZhP58zS4L8KSrWDmTeBkI65Dw0HsyUHuEVlX15mw=
+gopkg.in/yaml.v2 v2.2.1/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
+gopkg.in/yaml.v2 v2.2.4/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
+rsc.io/quote/v3 v3.1.0/go.mod h1:yEA65RcK8LyAZtP9Kv3t0HmxON59tX3rD+tICJqUlj0=
+rsc.io/sampler v1.3.0/go.mod h1:T1hPZKmBbMNahiBKFy5HrXp6adAjACjK9JXDnKaTXpA=
diff --git a/_example/main.go b/_example/main.go
@@ -0,0 +1,77 @@
+package main
+
+import (
+	"context"
+	"log"
+	"time"
+
+	"github.com/go-redis/redis/v7"
+	"github.com/gochore/dcron"
+)
+
+type RedisAtomic struct {
+	client *redis.Client
+}
+
+func (m *RedisAtomic) SetIfNotExists(key, value string) bool {
+	ret := m.client.SetNX(key, value, time.Hour)
+	return ret.Err() == nil && ret.Val()
+}
+
+func main() {
+	ra := &RedisAtomic{
+		// init redis client
+	}
+	cron := dcron.NewCron(dcron.WithKey("TestCron"), dcron.WithAtomic(ra))
+
+	job1 := dcron.NewJob("Job1", "*/15 * * * * *", func(ctx context.Context) error {
+		if task, ok := dcron.TaskFromContext(ctx); ok {
+			log.Println("run:", task.Job.Spec(), task.Key)
+		}
+		// do something
+		return nil
+	})
+	job2 := dcron.NewJobWithAutoKey("*/20 * * * * *", Job2)
+	job3 := Job3{}
+
+	if err := cron.AddJobs(job1, job2, job3); err != nil {
+		panic(err)
+	}
+
+	cron.Start()
+	log.Println("cron started")
+	time.Sleep(time.Minute)
+	<-cron.Stop().Done()
+	log.Println("cron stopped")
+}
+
+func Job2(ctx context.Context) error {
+	if task, ok := dcron.TaskFromContext(ctx); ok {
+		log.Println("run:", task.Job.Spec(), task.Key)
+	}
+	// do something
+	return nil
+}
+
+type Job3 struct {
+}
+
+func (j Job3) Key() string {
+	return "Job3"
+}
+
+func (j Job3) Spec() string {
+	return "*/30 * * * * *"
+}
+
+func (j Job3) Run(ctx context.Context) error {
+	if task, ok := dcron.TaskFromContext(ctx); ok {
+		log.Println("run:", task.Job.Spec(), task.Key)
+	}
+	// do something
+	return nil
+}
+
+func (j Job3) Options() []dcron.JobOption {
+	return nil
+}