Skip to content

Commit fa3d5c9

Browse files
burakkokenburakkoken
authored
Update README.md
1 parent d4258d4 commit fa3d5c9

File tree

1 file changed

+90
-19
lines changed

1 file changed

+90
-19
lines changed

‎README.md

Lines changed: 90 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -4,54 +4,89 @@
44
[![Build Status](https://travis-ci.com/procyon-projects/chrono.svg?branch=main)](https://travis-ci.com/procyon-projects/chrono)
55
[![codecov](https://codecov.io/gh/procyon-projects/chrono/branch/main/graph/badge.svg?token=OREV0YI8VU)](https://codecov.io/gh/procyon-projects/chrono)
66

7-
Chrono is a scheduler library which lets you run your task and code periodically
7+
Chrono is a scheduler library that lets you run your tasks and code periodically. It provides different scheduling functionalities to make it easier to create a scheduling task.
88

9-
## Schedule Task With Fixed Delay
10-
Scheduling a task at a Fixed Delay can be done with the help of the **ScheduleWithFixedDelay** method.
9+
## Scheduling a One-Shot Task
10+
The Schedule method helps us schedule the task to run once at the specified time. In the following example, the task will first be executed 1 second after the current time. 
11+
**WithStartTime** option is used to specify the execution time.
1112

12-
## Schedule Task at a Fixed Rate
13-
Scheduling a task at a Fixed Rate can be done with the help of the **ScheduleAtFixedRate** method.
13+
```go
14+
taskScheduler := chrono.NewDefaultTaskScheduler()
1415

15-
### Scheduling the Task at a Fixed Rate
16+
task, err := scheduler.Schedule(func(ctx context.Context) {
17+
log.Print("One-Shot Task")
18+
}, WithStartTime(now.Year(), now.Month(), now.Day(), now.Hour(), now.Minute(), now.Second()+1))
1619

17-
Let's schedule a task to run at a fixed rate of seconds.
20+
if err == nil {
21+
log.Print("Task has been scheduled successfully.")
22+
}
23+
```
24+
25+
## Scheduling a Task with Fixed Delay
26+
Let's schedule a task to run with a fixed delay between the finish time of the last execution of the task and the start time of the next execution of the task.
27+
The fixed delay counts the delay after the completion of the last execution.
1828

1929
```go
2030
taskScheduler := chrono.NewDefaultTaskScheduler()
2131

22-
task, err := taskScheduler.ScheduleAtFixedRate(func(ctx context.Context) {
23-
log.Print("Fixed Rate of 5 seconds")
32+
task, err := scheduler.ScheduleWithFixedDelay(func(ctx context.Context) {
33+
log.Print("Fixed Delay Task")
34+
time.Sleep(3 * time.Second)
2435
}, 5 * time.Second)
2536

2637
if err == nil {
27-
log.Print("Task has been scheduled")
38+
log.Print("Task has been scheduled successfully.")
2839
}
2940
```
3041

31-
The next task will run always after 5 seconds no matter the status of previous task, which may be still running. So even if the previous task isn't done, the next task will run.
42+
Since the task itself takes 3 seconds to complete and we have specified a delay of 5 seconds between the finish time of the last execution of the task and the start time of the next execution of the task, there will be a delay of 8 seconds between each execution.
3243

44+
**WithStartTime** and **WithLocation** options can be combined with this.
3345

34-
### Scheduling the Task at a Fixed Rate From a Given Date
35-
Let's schedule a task to run at a fixed rate from a given date.
46+
## Schedule Task at a Fixed Rate
47+
Let's schedule a task to run at a fixed rate of seconds.
3648

3749
```go
3850
taskScheduler := chrono.NewDefaultTaskScheduler()
3951

52+
task, err := taskScheduler.ScheduleAtFixedRate(func(ctx context.Context) {
53+
log.Print("Fixed Rate of 5 seconds")
54+
}, 5 * time.Second)
55+
56+
if err == nil {
57+
log.Print("Task has been scheduled successfully.")
58+
}
59+
```
60+
61+
The next task will run always after 5 seconds no matter the status of the previous task, which may be still running. So even if the previous task isn't done, the next task will run.
62+
We can also use the **WithStartTime** option to specify the desired first execution time of the task.
63+
64+
```go
4065
now := time.Now()
4166

4267
task, err := taskScheduler.ScheduleAtFixedRate(func(ctx context.Context) {
4368
log.Print("Fixed Rate of 5 seconds")
4469
}, 5 * time.Second, WithStartTime(now.Year(), now.Month(), now.Day(), now.Hour(), now.Minute(), now.Second() + 2))
70+
```
4571

46-
if err == nil {
47-
log.Print("Task has been scheduled")
48-
}
72+
When we use this option, the task will run at the specified execution time and subsequently with the given period. In the above example, the task will first be executed 2 seconds after the current time.
73+
74+
We can also combine this option with **WithLocation** based on our requirements.
75+
76+
```go
77+
now := time.Now()
78+
79+
task, err := taskScheduler.ScheduleAtFixedRate(func(ctx context.Context) {
80+
log.Print("Fixed Rate of 5 seconds")
81+
}, 5 * time.Second, WithStartTime(now.Year(), now.Month(), now.Day(), 18, 45, 0),
82+
WithLocation("America/New_York"))
4983
```
5084

51-
The task will be executed the first time 2 seconds after the current time, and it will continue to be executed according to the given fixed rate.
85+
In the above example, the task will first be executed at 18:45 of the current date in America/New York time.
86+
**If the start time is in the past, the task will be executed immediately.**
5287

53-
## Schedule Task With Cron Expression
54-
Sometimes Fixed Delay and Fixed Rate are not enough, and we need the flexibility of a cron expression to schedule our tasks. With the help of the provided **ScheduleWithCron** method, we can schedule a task based on a cron expression.
88+
## Scheduling a Task using Cron Expression
89+
Sometimes Fixed Rate and Fixed Delay can not fulfill your needs, and we need the flexibility of cron expressions to schedule the execution of your tasks. With the help of the provided **ScheduleWithCron method**, we can schedule a task based on a cron expression.
5590

5691
```go
5792
taskScheduler := chrono.NewDefaultTaskScheduler()
@@ -76,3 +111,39 @@ task, err := taskScheduler.ScheduleWithCron(func(ctx context.Context) {
76111
```
77112

78113
In the above example, Task will be scheduled to be executed at 18:45 on the 10th day of every month in America/New York time.
114+
115+
**WithStartTimeoption** cannot be used with **ScheduleWithCron**.
116+
117+
## Canceling a Scheduled Task
118+
Schedule methods return an instance of type ScheduledTask, which allows us to cancel a task or to check if the task is canceled. The Cancel method cancels the scheduled task but running tasks won't be interrupted.
119+
120+
121+
```go
122+
taskScheduler := chrono.NewDefaultTaskScheduler()
123+
124+
task, err := taskScheduler.ScheduleAtFixedRate(func(ctx context.Context) {
125+
log.Print("Fixed Rate of 5 seconds")
126+
}, 5 * time.Second)
127+
128+
/* ... */
129+
130+
task.Cancel()
131+
```
132+
133+
## Shutting Down a Scheduler
134+
The **Shutdown()** method doesn't cause immediate shut down of the Scheduler and returns a channel. It will make the Scheduler stop accepting new tasks and shut down after all running tasks finish their current work.
135+
136+
137+
```go
138+
taskScheduler := chrono.NewDefaultTaskScheduler()
139+
140+
/* ... */
141+
142+
shutdownChannel := taskScheduler.Shutdown()
143+
<- shutdownChannel
144+
145+
/* after all running task finished their works */
146+
```
147+
148+
# License
149+
Chrono is released under MIT License.

0 commit comments

Comments
 (0)