lua-resty-timer

Contents

• Functions

Modules

• resty.timer

Topics

• README

Module resty.timer

Extended timer.

Provides recurring, cancellable, node-wide timers, beyond what the basic OpenResty timers do.

Info:

• Copyright: 2017 - 2020 Kong Inc.
• License: Apache 2.0
• Author: Thijs Schreijer

Functions

cancel ()	Cancel the timer.
new (opts, ...)	Create a new timer.

Functions

cancel ()

Cancel the timer. Will run the 'cancel'-callback if provided. Will only cancel the timer in the current worker.

Returns:

results of the 'cancel' callback, or true if no callback was provided or nil + "already cancelled" if called repeatedly

Usage:

local t, err = resty_timer(options)  -- create a timer
if t then
  t:cancel()  -- immediately cancel the timer again
end

new (opts, ...)

Create a new timer. The opts table is not stored nor altered, and can hence be safely reused to create multiple timers. It supports the following parameters:

• interval : (number) interval in seconds after which the timer expires

• recurring : (boolean) set to true to make it a recurring timer

• jitter : (optional, number) variable interval to add to the first interval, default 0. If set to 1 second then the first interval will be set between interval and interval + 1. This makes sure if large numbers of timers are used, their execution gets randomly distributed.

• immediate : (boolean) will do the first run immediately (the initial interval will be set to 0 seconds). This option requires the recurring option. The first run will not include the jitter interval, it will be added to second run.

• detached : (boolean) if set to true the timer will keep running detached, if set to false the timer will be garbage collected unless anchored by the user.

• expire : (function) callback called as function(...) with the arguments passed as extra beyond the opts table to this new function.

• cancel : (optional, function) callback called as function(reason, ...). Where reason indicates why it was cancelled. The additional arguments will be the arguments as passed to this new function, beyond the opts table. See the usage example below for possible values for reason.

• shm_name : (optional, string) name of the shm to use to synchronize with the other workers if key_name is set.

• key_name : (optional, string) key name to use in shm shm_name. If this key is given the timer will only be executed in a single worker. All timers (across all workers) with the same key will share this. The key will always be prefixed with this module's name to prevent name collisions in the shm. This option requires the shm_name option.

• sub_interval : (optional, number) interval in seconds to check whether the timer needs to run. Only used for cross-worker timers. This setting reduces the maximum delay when a worker that currently runs the timer exits. In this case the maximum delay could be interval * 2 before another worker picks it up. With this option set, the maximum delay will be interval + sub_interval. This option requires the immediate and key_name options.

Parameters:

• opts table with options
• ... arguments to pass to the callbacks expire and cancel.

Returns:

timer object or nil + err

Usage:

local object = {
  name = "myName",
}

function object:timer_callback(...)
  -- Note: here we use colon-":" syntax
  print("starting ", self.name, ": ", ...)   --> "starting myName: 1 two 3"
end

function object.cancel_callback(reason, self, ...)
  -- Note: here we cannot use colon-":" syntax, due to the 'reason' parameter
  print("stopping ", self.name, ": ", ...)   --> "stopping myName: 1 two 3"
  if reason == resty_timer.CANCEL_USER then
    -- user called timer:cancel
  elseif reason == resty_timer.CANCEL_GC then
    -- the timer was garbage-collected
  elseif reason == resty_timer.CANCEL_SYSTEM then
    -- prematurely cancelled by the system (worker is exiting)
  else
    -- should not happen
  end
end

function object:start()
  if self.timer then return end
  self.timer = resty_timer({
    interval = 1,
    expire = self.timer_callback,
    cancel = self.cancel_callback,
  }, self, 1, " two ", 3)  -- 'self' + 3 parameters to pass to the callbacks

function object:stop()
  if self.timer then
    self.timer:cancel()
    self.timer = nil
  end
end