Skip to content

counter: Lock-free counter for nginx-module-lua


If you haven't set up RPM repository subscription, sign up. Then you can proceed with the following steps.

CentOS/RHEL 7 or Amazon Linux 2

yum -y install
yum -y install lua-resty-counter

CentOS/RHEL 8+, Fedora Linux, Amazon Linux 2023

yum -y install
yum -y install lua5.1-resty-counter

To use this Lua library with NGINX, ensure that nginx-module-lua is installed.

This document describes lua-resty-counter v0.2.1 released on Apr 09 2020.

lua-resty-counter - Lock-free counter for OpenResty.

Build Status luarocks


When number of workers increase, the penalty of acquiring a lock becomes noticable. This library implements a lock-free counter that does incrementing operation in worker's Lua VM. Each worker then sync its local counter to a shared dict timely.




syntax: c, err =, sync_interval?)

Create a new counter instance. Take first argument as the shared dict name in string. And an optional second argument as interval to sync local state to shared dict in number. If second argument is omitted, local counter will not be synced automatically, user are responsible to call counter:sync on each worker.


syntax: ok = counter:sync()

Sync current worker's local counter to shared dict. Not needed if a counter is created with sync_interval not set to nil.


syntax: counter:incr(key, step?)

Increase counter of key k with a step of step. If step is omitted, it's default to 1.


syntax: newval, err, forcible? = counter:reset(key, number)

Reset the counter in shdict with a decrease of number. This function is a wrapper of ngx.shared.DICT:incr(key, -number, number), please refer to lua-nginx-module doc for return values.


syntax: value = counter:get(key)

Get the value of counter from shared dict.


syntax: keys = counter:get_keys(max_count?)

Get the keys of counters in shared dict. This function is a wrapper of ngx.shared.DICT:get_keys, please refer to lua-nginx-module doc for return values.

See Also


You may find additional configuration tips and documentation for this module in the GitHub repository for nginx-module-counter.