gtimer

Documentation

Overview

Package gtimer implements timer for interval/delayed jobs running and management.

This package is designed for management for millions of timing jobs. The differences between gtimer and gcron are as follows:

1. package gcron is implemented based on package gtimer.
2. gtimer is designed for high performance and for millions of timing jobs.
3. gcron supports configuration pattern grammar like linux crontab, which is more manually readable.
4. gtimer's benchmark OP is measured in nanoseconds, and gcron's benchmark OP is measured in microseconds.

ALSO VERY NOTE the common delay of the timer: https://github.com/golang/go/issues/14410

Index

• Constants
• func DelayAdd(ctx context.Context, delay time.Duration, interval time.Duration, job JobFunc)
• func DelayAddEntry(ctx context.Context, delay time.Duration, interval time.Duration, job JobFunc, ...)
• func DelayAddOnce(ctx context.Context, delay time.Duration, interval time.Duration, job JobFunc)
• func DelayAddSingleton(ctx context.Context, delay time.Duration, interval time.Duration, job JobFunc)
• func DelayAddTimes(ctx context.Context, delay time.Duration, interval time.Duration, times int, ...)
• func Exit()
• func SetInterval(ctx context.Context, interval time.Duration, job JobFunc)
• func SetTimeout(ctx context.Context, delay time.Duration, job JobFunc)
• type Entry
  • func Add(ctx context.Context, interval time.Duration, job JobFunc) *Entry
  • func AddEntry(ctx context.Context, interval time.Duration, job JobFunc, isSingleton bool, ...) *Entry
  • func AddOnce(ctx context.Context, interval time.Duration, job JobFunc) *Entry
  • func AddSingleton(ctx context.Context, interval time.Duration, job JobFunc) *Entry
  • func AddTimes(ctx context.Context, interval time.Duration, times int, job JobFunc) *Entry
  • func (entry *Entry) Close()
  • func (entry *Entry) Ctx() context.Context
  • func (entry *Entry) IsSingleton() bool
  • func (entry *Entry) Job() JobFunc
  • func (entry *Entry) Reset()
  • func (entry *Entry) Run()
  • func (entry *Entry) SetSingleton(enabled bool)
  • func (entry *Entry) SetStatus(status int) int
  • func (entry *Entry) SetTimes(times int)
  • func (entry *Entry) Start()
  • func (entry *Entry) Status() int
  • func (entry *Entry) Stop()
• type JobFunc
• type Timer
  • func New(options ...TimerOptions) *Timer
  • func (t *Timer) Add(ctx context.Context, interval time.Duration, job JobFunc) *Entry
  • func (t *Timer) AddEntry(ctx context.Context, interval time.Duration, job JobFunc, isSingleton bool, ...) *Entry
  • func (t *Timer) AddOnce(ctx context.Context, interval time.Duration, job JobFunc) *Entry
  • func (t *Timer) AddSingleton(ctx context.Context, interval time.Duration, job JobFunc) *Entry
  • func (t *Timer) AddTimes(ctx context.Context, interval time.Duration, times int, job JobFunc) *Entry
  • func (t *Timer) Close()
  • func (t *Timer) DelayAdd(ctx context.Context, delay time.Duration, interval time.Duration, job JobFunc)
  • func (t *Timer) DelayAddEntry(ctx context.Context, delay time.Duration, interval time.Duration, job JobFunc, ...)
  • func (t *Timer) DelayAddOnce(ctx context.Context, delay time.Duration, interval time.Duration, job JobFunc)
  • func (t *Timer) DelayAddSingleton(ctx context.Context, delay time.Duration, interval time.Duration, job JobFunc)
  • func (t *Timer) DelayAddTimes(ctx context.Context, delay time.Duration, interval time.Duration, times int, ...)
  • func (t *Timer) Start()
  • func (t *Timer) Stop()
• type TimerOptions
  • func DefaultOptions() TimerOptions

Examples

• Add

Constants

const (
	StatusReady   = 0  // Job or Timer is ready for running.
	StatusRunning = 1  // Job or Timer is already running.
	StatusStopped = 2  // Job or Timer is stopped.
	StatusClosed  = -1 // Job or Timer is closed and waiting to be deleted.

)

Functions

func DelayAdd

func DelayAdd(ctx context.Context, delay time.Duration, interval time.Duration, job JobFunc)

DelayAdd adds a timing job after delay of `interval` duration. Also see Add.

func DelayAddEntry

func DelayAddEntry(ctx context.Context, delay time.Duration, interval time.Duration, job JobFunc, isSingleton bool, times int, status int)

DelayAddEntry adds a timing job after delay of `interval` duration. Also see AddEntry.

func DelayAddOnce

func DelayAddOnce(ctx context.Context, delay time.Duration, interval time.Duration, job JobFunc)

DelayAddOnce adds a timing job after delay of `interval` duration. Also see AddOnce.

func DelayAddSingleton

func DelayAddSingleton(ctx context.Context, delay time.Duration, interval time.Duration, job JobFunc)

DelayAddSingleton adds a timing job after delay of `interval` duration. Also see AddSingleton.

func DelayAddTimes

func DelayAddTimes(ctx context.Context, delay time.Duration, interval time.Duration, times int, job JobFunc)

DelayAddTimes adds a timing job after delay of `interval` duration. Also see AddTimes.

func Exit

func Exit()

Exit is used in timing job internally, which exits and marks it closed from timer. The timing job will be automatically removed from timer later. It uses "panic-recover" mechanism internally implementing this feature, which is designed for simplification and convenience.

func SetInterval

func SetInterval(ctx context.Context, interval time.Duration, job JobFunc)

SetInterval runs the job every duration of `delay`. It is like the one in javascript.

func SetTimeout

func SetTimeout(ctx context.Context, delay time.Duration, job JobFunc)

SetTimeout runs the job once after duration of `delay`. It is like the one in javascript.

Types

type Entry

type Entry struct {
	// contains filtered or unexported fields
}

Entry is the timing job.

func Add

func Add(ctx context.Context, interval time.Duration, job JobFunc) *Entry

Add adds a timing job to the default timer, which runs in interval of `interval`.

Example

package main

import (
	"context"
	"fmt"
	"time"

	"github.com/joy12825/gf/v2/os/gtimer"
)

func main() {
	var (
		ctx      = context.Background()
		now      = time.Now()
		interval = 1400 * time.Millisecond
	)
	gtimer.Add(ctx, interval, func(ctx context.Context) {
		fmt.Println(time.Now(), time.Duration(time.Now().UnixNano()-now.UnixNano()))
		now = time.Now()
	})

	select {}
}

func AddEntry

func AddEntry(ctx context.Context, interval time.Duration, job JobFunc, isSingleton bool, times int, status int) *Entry

AddEntry adds a timing job to the default timer with detailed parameters.

The parameter `interval` specifies the running interval of the job.

The parameter `singleton` specifies whether the job running in singleton mode. There's only one of the same job is allowed running when its a singleton mode job.

The parameter `times` specifies limit for the job running times, which means the job exits if its run times exceeds the `times`.

The parameter `status` specifies the job status when it's firstly added to the timer.

func AddOnce

func AddOnce(ctx context.Context, interval time.Duration, job JobFunc) *Entry

AddOnce is a convenience function for adding a job which only runs once and then exits.

func AddSingleton

func AddSingleton(ctx context.Context, interval time.Duration, job JobFunc) *Entry

AddSingleton is a convenience function for add singleton mode job.

func AddTimes

func AddTimes(ctx context.Context, interval time.Duration, times int, job JobFunc) *Entry

AddTimes is a convenience function for adding a job which is limited running times.

func (*Entry) Close

func (entry *Entry) Close()

Close closes the job, and then it will be removed from the timer.

func (*Entry) Ctx

func (entry *Entry) Ctx() context.Context

Ctx returns the initialized context of this job.

func (*Entry) IsSingleton

func (entry *Entry) IsSingleton() bool

IsSingleton checks and returns whether the job in singleton mode.

func (*Entry) Job

func (entry *Entry) Job() JobFunc

Job returns the job function of this job.

func (*Entry) Reset

func (entry *Entry) Reset()

Reset resets the job, which resets its ticks for next running.

func (*Entry) Run

func (entry *Entry) Run()

Run runs the timer job asynchronously.

func (*Entry) SetSingleton

func (entry *Entry) SetSingleton(enabled bool)

SetSingleton sets the job singleton mode.

func (*Entry) SetStatus

func (entry *Entry) SetStatus(status int) int

SetStatus custom sets the status for the job.

func (*Entry) SetTimes

func (entry *Entry) SetTimes(times int)

SetTimes sets the limit running times for the job.

func (*Entry) Start

func (entry *Entry) Start()

Start starts the job.

func (*Entry) Status

func (entry *Entry) Status() int

Status returns the status of the job.

func (*Entry) Stop

func (entry *Entry) Stop()

Stop stops the job.

type JobFunc

type JobFunc = func(ctx context.Context)

JobFunc is the timing called job function in timer.

type Timer

type Timer struct {
	// contains filtered or unexported fields
}

Timer is the timer manager, which uses ticks to calculate the timing interval.

func New

func New(options ...TimerOptions) *Timer

New creates and returns a Timer.

func (*Timer) Add

func (t *Timer) Add(ctx context.Context, interval time.Duration, job JobFunc) *Entry

Add adds a timing job to the timer, which runs in interval of `interval`.

func (*Timer) AddEntry

func (t *Timer) AddEntry(ctx context.Context, interval time.Duration, job JobFunc, isSingleton bool, times int, status int) *Entry

AddEntry adds a timing job to the timer with detailed parameters.

The parameter `interval` specifies the running interval of the job.

The parameter `singleton` specifies whether the job running in singleton mode. There's only one of the same job is allowed running when it's a singleton mode job.

The parameter `times` specifies limit for the job running times, which means the job exits if its run times exceeds the `times`.

The parameter `status` specifies the job status when it's firstly added to the timer.

func (*Timer) AddOnce

func (t *Timer) AddOnce(ctx context.Context, interval time.Duration, job JobFunc) *Entry

AddOnce is a convenience function for adding a job which only runs once and then exits.

func (*Timer) AddSingleton

func (t *Timer) AddSingleton(ctx context.Context, interval time.Duration, job JobFunc) *Entry

AddSingleton is a convenience function for add singleton mode job.

func (*Timer) AddTimes

func (t *Timer) AddTimes(ctx context.Context, interval time.Duration, times int, job JobFunc) *Entry

AddTimes is a convenience function for adding a job which is limited running times.

func (*Timer) Close

func (t *Timer) Close()

Close closes the timer.

func (*Timer) DelayAdd

func (t *Timer) DelayAdd(ctx context.Context, delay time.Duration, interval time.Duration, job JobFunc)

DelayAdd adds a timing job after delay of `delay` duration. Also see Add.

func (*Timer) DelayAddEntry

func (t *Timer) DelayAddEntry(ctx context.Context, delay time.Duration, interval time.Duration, job JobFunc, isSingleton bool, times int, status int)

DelayAddEntry adds a timing job after delay of `delay` duration. Also see AddEntry.

func (*Timer) DelayAddOnce

func (t *Timer) DelayAddOnce(ctx context.Context, delay time.Duration, interval time.Duration, job JobFunc)

DelayAddOnce adds a timing job after delay of `delay` duration. Also see AddOnce.

func (*Timer) DelayAddSingleton

func (t *Timer) DelayAddSingleton(ctx context.Context, delay time.Duration, interval time.Duration, job JobFunc)

DelayAddSingleton adds a timing job after delay of `delay` duration. Also see AddSingleton.

func (*Timer) DelayAddTimes

func (t *Timer) DelayAddTimes(ctx context.Context, delay time.Duration, interval time.Duration, times int, job JobFunc)

DelayAddTimes adds a timing job after delay of `delay` duration. Also see AddTimes.

func (*Timer) Start

func (t *Timer) Start()

Start starts the timer.

func (*Timer) Stop

func (t *Timer) Stop()

Stop stops the timer.

type TimerOptions

type TimerOptions struct {
	Interval time.Duration // (optional) Interval is the underlying rolling interval tick of the timer.
	Quick    bool          // Quick is used for quick timer, which means the timer will not wait for the first interval to be elapsed.
}

TimerOptions is the configuration object for Timer.

func DefaultOptions

func DefaultOptions() TimerOptions

DefaultOptions creates and returns a default options object for Timer creation.