add examples for all funcs, license tweak, func name clarifications (#…

…121) * add examples for all funcs, license tweak, func name clarifications * add faq - canceling tasks. fix example test * check if job is in scheduler before scheduling
go-co-op · Feb 9, 2021 · 507947a · 507947a
1 parent fc07510
commit 507947a
Show file tree

Hide file tree

Showing 7 changed files with 526 additions and 249 deletions.
diff --git a/LICENSE b/LICENSE
@@ -1,24 +1,21 @@
-Copyright (c) 2014, 辣椒面
-All rights reserved.
-
-Redistribution and use in source and binary forms, with or without
-modification, are permitted provided that the following conditions are met:
+MIT License
 
-* Redistributions of source code must retain the above copyright notice, this
-  list of conditions and the following disclaimer.
+Copyright (c) 2014, 辣椒面
 
-* Redistributions in binary form must reproduce the above copyright notice,
-  this list of conditions and the following disclaimer in the documentation
-  and/or other materials provided with the distribution.
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
 
-THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
-AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
-IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
-DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
-FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
-DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
-SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
-CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
-OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
-OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
 
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/README.md b/README.md
@@ -1,10 +1,10 @@
-# goCron: A Golang Job Scheduling Package.
+# gocron: A Golang Job Scheduling Package.
 
-[![CI State](https://github.com/go-co-op/gocron/workflows/Go%20Test/badge.svg)](https://github.com/go-co-op/gocron/actions?query=workflow%3A"Go+Test") ![Go Report Card](https://goreportcard.com/badge/github.com/go-co-op/gocron) [![Go Doc](https://godoc.org/github.com/go-co-op/gocron?status.svg)](https://godoc.org/github.com/go-co-op/gocron)
+[![CI State](https://github.com/go-co-op/gocron/workflows/Go%20Test/badge.svg)](https://github.com/go-co-op/gocron/actions?query=workflow%3A"Go+Test") ![Go Report Card](https://goreportcard.com/badge/github.com/go-co-op/gocron) [![Go Doc](https://godoc.org/github.com/go-co-op/gocron?status.svg)](https://pkg.go.dev/github.com/go-co-op/gocron)
 
-goCron is a Golang job scheduling package which lets you run Go functions periodically at pre-determined interval using a simple, human-friendly syntax.
+gocron is a Golang job scheduling package which lets you run Go functions periodically at pre-determined interval using a simple, human-friendly syntax.
 
-goCron is a Golang implementation of Ruby module [clockwork](https://github.com/tomykaira/clockwork) and Python job scheduling package [schedule](https://github.com/dbader/schedule).
+gocron is a Golang implementation of the Ruby module [clockwork](https://github.com/tomykaira/clockwork) and the Python job scheduling package [schedule](https://github.com/dbader/schedule).
 
 See also these two great articles:
 
@@ -13,114 +13,14 @@ See also these two great articles:
 
 If you want to chat, you can find us at Slack! [<img src="https://img.shields.io/badge/gophers-gocron-brightgreen?logo=slack">](https://gophers.slack.com/archives/CQ7T0T1FW)
 
-## Examples:
+## FAQ
 
-```go
-package main
+* Q: I'm running multiple pods on a distributed environment. How can I make a job not run once per pod causing duplication? 
+* A: We recommend using your own lock solution within the jobs themselves (you could use [Redis](https://redis.io/topics/distlock), for example)
 
-import (
-	"fmt"
-	"time"
-
-	"github.com/go-co-op/gocron"
-)
-
-func task() {
-    fmt.Println("I am running task.")
-}
-
-func taskWithParams(a int, b string) {
-    fmt.Println(a, b)
-}
-
-func main() {
-    // defines a new scheduler that schedules and runs jobs
-    s1 := gocron.NewScheduler(time.UTC)
-
-    s1.Every(3).Seconds().Do(task)
-
-    // scheduler starts running jobs and current thread continues to execute
-    s1.StartAsync()
-
-    // Do jobs without params
-    s2 := gocron.NewScheduler(time.UTC)
-    s2.Every(1).Second().Do(task)
-    s2.Every(2).Seconds().Do(task)
-    s2.Every(1).Minute().Do(task)
-    s2.Every(2).Minutes().Do(task)
-    s2.Every(1).Hour().Do(task)
-    s2.Every(2).Hours().Do(task)
-    s2.Every(1).Day().Do(task)
-    s2.Every(2).Days().Do(task)
-    s2.Every(1).Week().Do(task)
-    s2.Every(2).Weeks().Do(task)
-    s2.Every(1).Month(time.Now().Day()).Do(task)
-    s2.Every(2).Months(15).Do(task)
-
-    // check for errors
-    _, err := s2.Every(1).Day().At("bad-time").Do(task)
-    if err != nil {
-        log.Fatalf("error creating job: %v", err)
-    }
-
-    // Do jobs with params
-    s2.Every(1).Second().Do(taskWithParams, 1, "hello")
-
-    // Do Jobs with tags
-    // initialize tag
-    tag1 := []string{"tag1"}
-    tag2 := []string{"tag2"}
-
-    s2.Every(1).Week().SetTag(tag1).Do(task)
-    s2.Every(1).Week().SetTag(tag2).Do(task)
-
-    // Removing Job Based on Tag
-    s2.RemoveJobByTag("tag1")
-
-    // Remove a Job after its last execution
-    j, _ := s2.Every(1).StartAt(time.Now().Add(30*time.Second)).Do(task)
-    j.LimitRunsTo(1)
-    j.RemoveAfterLastRun()
-
-    // Do jobs on specific weekday
-    s2.Every(1).Monday().Do(task)
-    s2.Every(1).Thursday().Do(task)
-
-    // Do a job at a specific time - 'hour:min:sec' - seconds optional
-    s2.Every(1).Day().At("10:30").Do(task)
-    s2.Every(1).Monday().At("18:30").Do(task)
-    s2.Every(1).Tuesday().At("18:30:59").Do(task)
-    s2.Every(1).Wednesday().At("1:01").Do(task)
-
-    // Begin job at a specific date/time. 
-    t := time.Date(2019, time.November, 10, 15, 0, 0, 0, time.UTC)
-    s2.Every(1).Hour().StartAt(t).Do(task)
-
-    // Delay start of job
-    s2.Every(1).Hour().StartAt(time.Now().Add(time.Duration(1 * time.Hour)).Do(task)
-
-    // NextRun gets the next running time
-    _, time := s2.NextRun()
-    fmt.Println(time)
-
-    // Remove a specific job
-    s2.Remove(task)
-
-    // Clear all scheduled jobs
-    s2.Clear()
-
-    // stop our first scheduler (it still exists but doesn't run anymore)
-    s1.Stop() 
-
-    // executes the scheduler and blocks current thread
-    s2.StartBlocking()
-
-    // this line is never reached
-}
-```
-### FAQ
- * Q: I'm running multiple pods on a distributed environment. How can I make a job not run once per pod causing duplication? 
- * A: We recommend using your own lock solution within the jobs themselves (you could use [Redis](https://redis.io/topics/distlock), for example)
+* Q: I've removed my job from the scheduler, but how can I stop a long-running job that has already been triggered?
+* A: We recommend using a means of canceling your job, e.g. a `context.WithCancel()`.
+
 --- 
 Looking to contribute? Try to follow these guidelines:
  * Use issues for everything
@@ -132,4 +32,5 @@ Looking to contribute? Try to follow these guidelines:
     * Suggesting new features or enhancements
     * Improving/fixing documentation
 ---
+
 [Jetbrains](https://www.jetbrains.com/?from=gocron) supports this project with GoLand licenses. We appreciate their support for free and open source software!