README
¶
dcron
A distributed cron framework.
Install
go get github.com/nkonev/dcron
Quick Start
First, implement a distributed lock operation that only requires support for two methods: Lock and Unlock.
You can implement it in any way you prefer, such as using Redis SetNX.
import "github.com/redis/go-redis/v9"
type RedisLock struct {
client *redis.Client
}
func (m *RedisLock) Lock(ctx context.Context, key, value string) bool {
ret := m.client.SetNX(ctx, key, value, time.Hour)
return ret.Err() == nil && ret.Val()
}
func (m *RedisLock) Unlock(ctx context.Context, key, value string) {
m.client.Del(ctx, key)
}
Now you can create a cron with that:
func main() {
lock := &RedisLock{
client: redis.NewClient(&redis.Options{
Addr: "localhost:6379",
}),
}
cron := dcron.NewCron(dcron.WithLock(lock))
}
Then, create a job and add it to the cron.
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
})
if err := cron.AddJobs(job1); err != nil {
log.Fatal(err)
}
Finally, start the cron:
cron.Start()
log.Println("cron started")
time.Sleep(time.Minute)
<-cron.Stop().Done()
If you start the program multiple times, you will notice that the cron will run the job once every 15 seconds on only one of the processes.
| process 1 | process 2 | process 3 |
|---|---|---|
| 2023/10/13 11:39:45 cron started | 2023/10/13 11:39:47 cron started | 2023/10/13 11:39:48 cron started |
| 2023/10/13 11:40:00 run: */15 * * * * * Job1 | ||
| 2023/10/13 11:40:15 run: */15 * * * * * Job1 | ||
| 2023/10/13 11:40:30 run: */15 * * * * * Job1 | ||
| 2023/10/13 11:40:45 run: */15 * * * * * Job1 |
One more thing, since dcron.WithLock(lock) is optional, it's also a good idea to use it as a local cron.
cron := dcron.NewCron()
job2 := dcron.NewJob("A local job", "*/15 * * * * *", func(ctx context.Context) error {
// do something
return nil
})
if err := cron.AddJobs(job2); err != nil {
log.Fatal(err)
}
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type AfterFunc ¶
type AfterFunc func(task Task)
AfterFunc represents the function could be called after Run.
type BeforeFunc ¶
BeforeFunc represents the function could be called before Run.
type Cron ¶
type Cron struct {
// contains filtered or unexported fields
}
Cron keeps track of any number of jobs, invoking the associated func as specified.
func NewCron ¶
func NewCron(options ...CronOption) *Cron
NewCron returns a cron with specified options.
func (*Cron) Start ¶
func (c *Cron) Start()
Start the cron scheduler in its own goroutine, or no-op if already started.
func (*Cron) Statistics ¶
func (c *Cron) Statistics() Statistics
Statistics implements CronMeta.Statistics
type CronMeta ¶
type CronMeta interface {
// Hostname returns current hostname.
Hostname() string
// Statistics returns statistics info of the cron's all jobs.
Statistics() Statistics
// Jobs returns the cron's all jobs as JobMeta.
Jobs() []JobMeta
}
CronMeta is a read only wrapper for Cron.
type CronOption ¶
type CronOption func(c *Cron)
CronOption represents a modification to the default behavior of a Cron.
func WithContext ¶
func WithContext(ctx context.Context) CronOption
WithContext sets the root context of the cron instance. It will be used as the parent context of all tasks, and when the context is done, the cron will be stopped.
func WithHostname ¶
func WithHostname(hostname string) CronOption
WithHostname overrides the hostname of the cron instance.
func WithLocation ¶
func WithLocation(loc *time.Location) CronOption
WithLocation overrides the timezone of the cron instance.
func WithLock ¶ added in v1.7.0
func WithLock(lock Lock) CronOption
WithLock uses the provided Lock.
type Job ¶
type Job interface {
// Key returns the unique key of the job.
Key() string
// Spec returns spec of the job, like "* * * * * *".
Spec() string
// Run is what the job do.
Run(ctx context.Context) error
// Options returns options of the job.
Options() []JobOption
}
Job describes a type which could be added to a cron.
func NewJobWithAutoKey ¶
NewJobWithAutoKey returns a new Job with the "run" function's name as key. Be careful, the "run" should be a non-anonymous function, or returned Job will have an emtpy key, and can not be added to a Cron.
type JobMeta ¶
type JobMeta interface {
// Key returns the unique key of the job.
Key() string
// Spec returns the spec of the job.
Spec() string
// Statistics returns statistics info of the job.
Statistics() Statistics
}
JobMeta is a read only wrapper for innerJob.
type JobOption ¶
type JobOption func(job *innerJob)
JobOption represents a modification to the default behavior of a Job.
func WithAfterFunc ¶
WithAfterFunc specifies what to do after Run.
func WithBeforeFunc ¶
func WithBeforeFunc(before BeforeFunc) JobOption
WithBeforeFunc specifies what to do before Run.
func WithNoLock ¶ added in v1.7.2
func WithNoLock() JobOption
WithNoLock means the job will run at multiple cron instances, even though the cron has Lock.
func WithRetryInterval ¶
func WithRetryInterval(retryInterval RetryInterval) JobOption
WithRetryInterval indicates how long should delay before retrying when run failed `triedTimes` times.
func WithRetryTimes ¶
WithRetryTimes specifies max times to retry, retryTimes will be set as 1 if it is less than 1.
type Lock ¶ added in v1.7.0
type Lock interface {
// Lock stores the key/value and return true if the key is not existed,
// or does nothing and return false.
// Note that the key/value should be kept for at least one minute.
// For example, `SetNX(key, value, time.Minute)` via redis.
Lock(ctx context.Context, key, value string) bool
// Unlock removes the key/value,
// or does nothing.
Unlock(ctx context.Context, key, value string)
}
Lock provides distributed lock operation for dcron, it can be implemented easily via Redis/SQL and so on.
type RetryInterval ¶
RetryInterval indicates how long should delay before retrying when run failed `triedTimes` times.
type Statistics ¶
type Statistics struct {
TotalTask int64 // Total count of tasks processed
PassedTask int64 // Number of tasks successfully executed
FailedTask int64 // Number of tasks that failed during execution due to errors
SkippedTask int64 // Number of tasks skipped due to BeforeFunc returning true
MissedTask int64 // Number of tasks executed by other instances
TotalRun int64 // Total count of execution runs
PassedRun int64 // Number of successfully executed runs
FailedRun int64 // Number of runs that have failed due to errors
RetriedRun int64 // Number of runs that encountered errors and were subsequently retried
}
Statistics records statistics info for a cron or a job.
func (Statistics) Add ¶
func (s Statistics) Add(delta Statistics) Statistics
Add return a new Statistics with two added.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package mock_dcron is a generated GoMock package.
|
Package mock_dcron is a generated GoMock package. |