{"id":20840619,"url":"https://github.com/kong/lua-resty-timer","last_synced_at":"2025-05-08T22:03:07.489Z","repository":{"id":47866373,"uuid":"110901882","full_name":"Kong/lua-resty-timer","owner":"Kong","description":"Extended timers for OpenResty","archived":false,"fork":false,"pushed_at":"2021-09-15T14:37:46.000Z","size":68,"stargazers_count":23,"open_issues_count":2,"forks_count":11,"subscribers_count":35,"default_branch":"master","last_synced_at":"2025-05-08T22:02:13.508Z","etag":null,"topics":["kong","openresty","openresty-module"],"latest_commit_sha":null,"homepage":"https://kong.github.io/lua-resty-timer/index.html","language":"Perl","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Kong.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-11-16T00:17:04.000Z","updated_at":"2024-07-31T07:18:46.000Z","dependencies_parsed_at":"2022-09-14T10:01:41.901Z","dependency_job_id":null,"html_url":"https://github.com/Kong/lua-resty-timer","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kong%2Flua-resty-timer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kong%2Flua-resty-timer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kong%2Flua-resty-timer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kong%2Flua-resty-timer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Kong","download_url":"https://codeload.github.com/Kong/lua-resty-timer/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253154972,"owners_count":21862622,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["kong","openresty","openresty-module"],"created_at":"2024-11-18T01:17:05.631Z","updated_at":"2025-05-08T22:03:07.440Z","avatar_url":"https://github.com/Kong.png","language":"Perl","funding_links":[],"categories":[],"sub_categories":[],"readme":"# lua-resty-timer\n\n[![Build Status][badge-travis-image]][badge-travis-url]\n\nExtended timers for OpenResty. Provided recurring, cancellable, node-wide timers,\nbeyond what the basic OpenResty timers do.\n\n## Status\n\nThis library is production ready.\n\n## Synopsis\n\n```nginx\nhttp {\n    lua_shared_dict timer_shm 1m;\n    init_worker_by_lua_block {\n        local timer = require(\"resty.timer\")\n\n        local options = {\n            interval = 0.1,           -- expiry interval in seconds\n            recurring = true,         -- recurring or single timer\n            immediate = true,         -- initial interval will be 0\n            detached = false,         -- run detached, or be garbagecollectible\n            jitter = 0.1,             -- add a random interval\n            expire = object.handler,  -- callback on timer expiry\n            cancel = function(reason, self, param1)\n                -- will be called when the timer gets cancelled\n            end,\n            shm_name = \"timer_shm\",   -- shm to use for node-wide timers\n            key_name = \"my_key\",      -- key-name to use for node-wide timers\n            sub_interval = 0.1,       -- max cross worker extra delay\n        }\n\n        local object\n        object = {                            -- create some object with a timer\n            count = 0,\n            handler = function(self, param1)  -- the timer callback as a method\n                -- do something here\n                print(param1)                 --\u003e \"Param 1\"\n            end,\n\n            -- create and add to object, but also pass it as 'self' to the handler\n            timer = timer(options, object, \"Param 1\"),\n        }\n\n        -- anchor the object and timer\n        _M.global_object = object     -- will be collected if not anchored\n\n        -- cancel the timer\n        object.timer:cancel()\n    }\n}\n```\n\n## Description\n\nThe OpenResty timer is fairly limited, this timer adds a number of common\noptions as parameters without having to recode (and retest) them in each\nproject.\n\n* recurring timers (supported by OR as well through `ngx.timer.every`)\n\n* immediate first run for recurring timers\n\n* cancellable timers\n\n* cancel callback, called when the timer is cancelled\n\n* garbage collectible timers, enabling timers to (optionally) be attached to\n  objects and automatically stop when garbage collected.\n\n* node-wide timers: the same timer started in each worker will still only\n  run once across the system. If the worker running it is removed the\n  timer will automatically be executed on another worker.\n\nSee the [online LDoc documentation](https://kong.github.io/lua-resty-timer/topics/README.md.html)\nfor the complete API.\n\n## History\n\nVersioning is strictly based on [Semantic Versioning](https://semver.org/)\n\n### Releasing new versions:\n\n* update changelog below (PR's should be merged including a changelog entry)\n* based on changelog determine new SemVer version\n* create a new rockspec\n* render the docs using `ldoc` (don't do this within PR's)\n* commit as \"release x.x.x\" (do not include rockspec revision)\n* tag the commit with \"x.x.x\" (do not include rockspec revision)\n* push commit and tag\n* upload rock to luarocks: `luarocks upload rockspecs/[name] --api-key=abc`\n\n### unreleased\n\n  * Feat: provide a stacktrace upon errors in the timer callback\n\n### 1.1.0 (6-Nov-2020)\n\n  * Feat: add a `jitter` option. This adds a random interval to distribute the\n  timers (in case of scheduling many timers at once).\n\n### 1.0.0 (21-Sep-2020)\n\n  * Change [BREAKING]: the recurring timers are now implemented as a sleeping\n  thread which is more efficient. Side effect is that the timer only gets\n  rescheduled AFTER executing the handler. So if the handler is long running,\n  then individual runs will be further apart.\n\n### 0.3 (28-May-2018)\n\n  * Feat: added cancellation callback invocation on timer being GC'ed. This\n  changes the first argument of the `cancel` callback, and hence is\n  breaking.\n\n### 0.2 (12-Feb-2018) Bug fix\n\n  * Fix: bugfix in `unpack` function not honoring table length parameter\n  * Docs: small fixes and typo's\n\n### 0.1 (22-Nov-2017) Initial release\n\n  * Added `sub_interval` option to reduce delays\n  * Initial upload\n\n## Copyright and License\n\n```\nCopyright 2017 - 2018 Kong Inc.\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n   http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n```\n\n[badge-travis-url]: https://travis-ci.com/Kong/lua-resty-timer/branches\n[badge-travis-image]: https://travis-ci.com/Kong/lua-resty-timer.svg?branch=master\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkong%2Flua-resty-timer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkong%2Flua-resty-timer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkong%2Flua-resty-timer/lists"}