Skip to main content
Version: 2.8.x(Latest)

Basic Usage​

package main

import (
    "context"
    "github.com/gogf/gf/v2/frame/g"
    "github.com/gogf/gf/v2/os/gcron"
    "github.com/gogf/gf/v2/os/gctx"
    "time"
)

func main() {
    var (
        err error
        ctx = gctx.New()
    )
    _, err = gcron.Add(ctx, "* * * * * *", func(ctx context.Context) {
        g.Log().Print(ctx, "Every second")
    }, "MySecondCronJob")
    if err != nil {
        panic(err)
    }

    _, err = gcron.Add(ctx, "0 30 * * * *", func(ctx context.Context) {
        g.Log().Print(ctx, "Every hour on the half hour")
    })
    if err != nil {
        panic(err)
    }

    _, err = gcron.Add(ctx, "@hourly", func(ctx context.Context) {
        g.Log().Print(ctx, "Every hour")
    })
    if err != nil {
        panic(err)
    }

    _, err = gcron.Add(ctx, "@every 1h30m", func(ctx context.Context) {
        g.Log().Print(ctx, "Every hour thirty")
    })
    if err != nil {
        panic(err)
    }

    g.Dump(gcron.Entries())

    time.Sleep(3 * time.Second)

    g.Log().Print(ctx, `stop cronjob "MySecondCronJob"`)
    gcron.Stop("MySecondCronJob")

    time.Sleep(3 * time.Second)

    g.Log().Print(ctx, `start cronjob "MySecondCronJob"`)
    gcron.Start("MySecondCronJob")

    time.Sleep(3 * time.Second)
}

After execution, the output is:

[
    {
        Name: "MySecondCronJob",
        Job:  0x14077e0,
        Time: "2021-11-14 12:13:53.445132 +0800 CST m=+0.006167069",
    },
    {
        Name: "cron-1",
        Job:  0x14078a0,
        Time: "2021-11-14 12:13:53.44515 +0800 CST m=+0.006185688",
    },
    {
        Name: "cron-2",
        Job:  0x1407960,
        Time: "2021-11-14 12:13:53.445161 +0800 CST m=+0.006196483",
    },
    {
        Name: "cron-3",
        Job:  0x1407a20,
        Time: "2021-11-14 12:13:53.445218 +0800 CST m=+0.006252937",
    },
]
2021-11-14 12:13:54.442 {189cwi9ngk0cfp7l8gcwciw100sr9cuu} Every second
2021-11-14 12:13:55.441 {189cwi9ngk0cfp7l8gcwciw100sr9cuu} Every second
2021-11-14 12:13:56.440 {189cwi9ngk0cfp7l8gcwciw100sr9cuu} Every second
2021-11-14 12:13:56.445 {189cwi9ngk0cfp7l8gcwciw100sr9cuu} stop cronjob "MySecondCronJob"
2021-11-14 12:13:59.445 {189cwi9ngk0cfp7l8gcwciw100sr9cuu} start cronjob "MySecondCronJob"
2021-11-14 12:14:00.443 {189cwi9ngk0cfp7l8gcwciw100sr9cuu} Every second
2021-11-14 12:14:01.442 {189cwi9ngk0cfp7l8gcwciw100sr9cuu} Every second
2021-11-14 12:14:02.443 {189cwi9ngk0cfp7l8gcwciw100sr9cuu} Every second

AddSingleton Add Singleton Cron Job​

A singleton cron job is one that only allows one instance of the job to run at any time. If a second instance of the job is triggered while the first is still running, it will exit without executing and wait for the next scheduled trigger. Use AddSingleton to add singleton cron jobs.

package main

import (
    "context"
    "github.com/gogf/gf/v2/frame/g"
    "github.com/gogf/gf/v2/os/gcron"
    "github.com/gogf/gf/v2/os/gctx"
    "time"
)

func main() {
    var (
        err error
        ctx = gctx.New()
    )
    _, err = gcron.AddSingleton(ctx, "* * * * * *", func(ctx context.Context) {
        g.Log().Print(ctx, "doing")
        time.Sleep(2 * time.Second)
    })
    if err != nil {
        panic(err)
    }
    select {}
}

After execution, the output is:

2021-11-14 12:16:54.073 {189cwi9nmm0cfp7niz319fc100zrw0ig} doing
2021-11-14 12:16:57.072 {189cwi9nmm0cfp7niz319fc100zrw0ig} doing
2021-11-14 12:17:00.072 {189cwi9nmm0cfp7niz319fc100zrw0ig} doing
2021-11-14 12:17:03.071 {189cwi9nmm0cfp7niz319fc100zrw0ig} doing
2021-11-14 12:17:06.072 {189cwi9nmm0cfp7niz319fc100zrw0ig} doing
2021-11-14 12:17:09.072 {189cwi9nmm0cfp7niz319fc100zrw0ig} doing
...

AddOnce Add One-Time Cron Job​

A one-time cron job is added using the AddOnce method, which runs just once and then automatically destroys itself. The Size method allows you to check its status. The related methods are:

package main

import (
    "context"
    "github.com/gogf/gf/v2/frame/g"
    "github.com/gogf/gf/v2/os/gcron"
    "github.com/gogf/gf/v2/os/gctx"
    "time"
)

func main()  {
    var (
        ctx = gctx.New()
    )
    cron := gcron.New()
    array := garray.New(true)
    cron.AddOnce(ctx, "@every 2s", func(ctx context.Context) {
        array.Append(1)
    })
    fmt.Println(cron.Size(),array.Len())
    time.Sleep(3000 * time.Millisecond)
    fmt.Println(cron.Size(),array.Len())

}

After execution, the output is:

1 0
0 1

AddTimes Add Specified Number of Cron Jobs​

The AddTimes method adds a cron job that runs a specified number of times. Once it completes the times count, the job auto-destructs. The Size method shows its status. Related methods:

package main

import (
    "context"
    "github.com/gogf/gf/v2/frame/g"
    "github.com/gogf/gf/v2/os/gcron"
    "github.com/gogf/gf/v2/os/gctx"
    "time"
)

func main() {
    var (
        ctx = gctx.New()
    )
    cron := gcron.New()
    array := garray.New(true)
    cron.AddTimes(ctx, "@every 2s", 2,func(ctx context.Context) {
        array.Append(1)
    })
     fmt.Println(cron.Size(), array.Len())
    time.Sleep(3000 * time.Millisecond)
    fmt.Println(cron.Size(), array.Len())
    time.Sleep(3000 * time.Millisecond)
    fmt.Println(cron.Size(), array.Len())
}

After execution, the output is:

1 0
1 1
0 2

Entries Get Registered Cron Job List​

The Entries method fetches information on all registered cron jobs and returns them as a slice (sorted by registration time asc). Related methods:

package main

import (
    "context"
    "github.com/gogf/gf/v2/frame/g"
    "github.com/gogf/gf/v2/os/gcron"
    "github.com/gogf/gf/v2/os/gctx"
    "time"
)

func main() {
    var (
        ctx = gctx.New()
    )
    cron := gcron.New()
    array := garray.New(true)
    cron.AddTimes(ctx, "@every 1s", 2,func(ctx context.Context) {
        array.Append(1)
    },"cron1")
    cron.AddOnce(ctx, "@every 1s",func(ctx context.Context) {
        array.Append(1)
    },"cron2")
    entries := cron.Entries()
    for  k, v := range entries{
        fmt.Println(k,v.Name,v.Time)

    }
    time.Sleep(3000 * time.Millisecond)
    fmt.Println(array.Len())

}

After execution, the output is:

0 cron2 2022-02-09 10:11:47.2421345 +0800 CST m=+0.159116501
1 cron1 2022-02-09 10:11:47.2421345 +0800 CST m=+0.159116501
3

Search Search for a Cron Job​

The Search function returns a scheduled task with a specified "name" (returning a *Entry pointer). If not found, it returns nil. Related methods:

func main() {
    var (
        ctx = gctx.New()
    )
    cron := gcron.New()
    array := garray.New(true)
    cron.AddTimes(ctx, "@every 1s", 2,func(ctx context.Context) {
        array.Append(1)
    },"cron1")
    cron.AddOnce(ctx, "@every 1s",func(ctx context.Context) {
        array.Append(1)
    },"cron2")
    search := cron.Search("cron2")

    g.Log().Print(ctx, search)

    time.Sleep(3000 * time.Millisecond)
    fmt.Println(array.Len())

    // Output:
    // 3
}

After execution, the output is:

2022-02-09 10:52:30.011 {18a909957cfed11680c1b145da1ef096} {"Name":"cron2","Time":"2022-02-09T10:52:29.9972842+08:00"}

Stop Pause a Cron Job​

The Stop method stops a cron job (Stop will pause but not delete). You can specify the task name with the name parameter. If name is not specified, it will stop the entire cron. Related methods:

func main() {
    var (
        ctx = gctx.New()
    )
    cron := gcron.New()
    array := garray.New(true)
    cron.AddTimes(ctx, "@every 2s", 1,func(ctx context.Context) {
        array.Append(1)
    },"cron1")
    cron.AddOnce(ctx, "@every 2s",func(ctx context.Context) {
        array.Append(1)
    },"cron2")
    fmt.Println(array.Len(),cron.Size())
    cron.Stop("cron2")
    fmt.Println(array.Len(),cron.Size())
    time.Sleep(3000 * time.Millisecond)
    fmt.Println(array.Len(),cron.Size())

    // Output:
    // 1
    // 1
}

After execution, the output is:

0 2
0 2
1 1
info

The Stop method marks a cron job as paused and returns immediately without waiting for the current execution to end. In some scenarios, you might need to wait for the current execution to finish before exiting. Starting from version v2.8, the StopGracefully method has been introduced to gracefully pause cron jobs. This method blocks until the current execution completes before returning.

Remove Stop and Delete a Job​

The Remove method deletes a cron job based on name name (stopping and deleting it). Related methods:

func main() {
    var (
        ctx = gctx.New()
    )
    cron := gcron.New()
    array := garray.New(true)
    cron.AddTimes(ctx, "@every 2s", 1,func(ctx context.Context) {
        array.Append(1)
    },"cron1")
    cron.AddOnce(ctx, "@every 2s",func(ctx context.Context) {
        array.Append(1)
    },"cron2")
    fmt.Println(array.Len(),cron.Size())
    cron.Remove("cron2")
    fmt.Println(array.Len(),cron.Size())
    time.Sleep(3000 * time.Millisecond)
    fmt.Println(array.Len(),cron.Size())
    // Output:
    // 0 2
    // 0 1
    // 1 0
}

After execution, the output is:

0 2
0 1
1 0

Start Start a Cron Job​

The Start method initiates a cron job (automatically initiated after Add). You can specify the task name with the name parameter. If name is not specified, it will start the entire cron. Related methods:

func main() {
    var (
        ctx = gctx.New()
    )
    cron := gcron.New()
    array := garray.New(true)
    cron.AddOnce(ctx, "@every 2s",func(ctx context.Context) {
        array.Append(1)
    },"cron2")
    cron.Stop("cron2")
    time.Sleep(3000 * time.Millisecond)
    fmt.Println(array.Len(),cron.Size())
    cron.Start("cron2")
    time.Sleep(3000 * time.Millisecond)
    fmt.Println(array.Len(),cron.Size())

    // Output:
    // 0 1
    // 1 0
}

After execution, the output is:

0 1
1 0