ZMQ\_TIMERS(3) 0MQ Manual ZMQ\_TIMERS(3)

# [NAME](#NAME)

zmq\_timers - helper functions for cross-platform timers callbacks

# [SYNOPSIS](#SYNOPSIS)

**typedef void(zmq\_timer\_fn) (int timer\_id, void \*arg);**

**void \*zmq\_timers\_new (void);**

**int zmq\_timers\_destroy (void \*timers\_p**);*

**int zmq\_timers\_add (void \*timers, size\_t interval, zmq\_timer\_fn handler, void \*arg);**

**int zmq\_timers\_cancel (void \*timers, int timer\_id);**

**int zmq\_timers\_set\_interval (void \*timers, int timer\_id, size\_t interval);**

**int zmq\_timers\_reset (void \*timers, int timer\_id);**

**long zmq\_timers\_timeout (void \*timers);**

**int zmq\_timers\_execute (void \*timers);**

# [DESCRIPTION](#DESCRIPTION)

The *zmq\_timers*\*_ functions provide cross-platform access to timers callbacks. Once a timer has been registered, it will repeat at the specified interval until it gets manually cancelled. To run the callbacks, *zmq\_timers\_execute* must be ran.

*zmq\_timers\_new* and *zmq\_timers\_destroy* manage the lifetime of a timer instance. *zmq\_timers\_new* creates and returns a new timer instance, while *zmq\_timers\_destroy* destroys it. A pointer to a valid timer must be passed as the *timers\_p* argument of *zmq\_timers\_destroy*. In particular, *zmq\_timers\_destroy* may not be called multiple times for the same timer instance. *zmq\_timers\_destroy* sets the passed pointer to NULL in case of a successful execution.

*zmq\_timers\_add* and *zmq\_timers\_cancel* manage the timers registered.

*zmq\_timers\_add* registers a new *timer* with a given instance. *timers* must point to a valid *timers* object. The *interval* parameter specifies the expiration of the timer in milliseconds. *handler* and *arg* specify the callback that will be invoked on expiration and the optional parameter that will be passed through. The callback must be a valid function implementing the *zmq\_timer\_fn* prototype. An ID will be returned that can be used to modify or cancel the timer.

*zmq\_timers\_cancel* will cancel the timer associated with *timer\_id* from the instance *timers*.

*zmq\_timers\_set\_interval* will set the expiration of the timer associated with *timer\_id* from the instance *timers* to *interval* milliseconds into the future.

*zmq\_timers\_reset* will restart the timer associated with *timer\_id* from the instance *timers*.

*zmq\_timers\_timeout* will return the time left in milliseconds until the next timer registered with *timers* expires.

*zmq\_timers\_execute* will run callbacks of all expired timers from the instance *timers*.

# [THREAD SAFETY](#THREAD_SAFETY)

Like most other 0MQ objects, timers are not thread-safe. All operations must be called from the same thread. Otherwise, behaviour is undefined.

# [RETURN VALUE](#RETURN_VALUE)

*zmq\_timers\_new* always returns a valid pointer to a poller.

All functions that return an int, return -1 in case of a failure. In that case, zmq\_errno() can be used to query the type of the error as described below.

*zmq\_timers\_timeout* returns the time left in milliseconds until the next timer registered with *timers* expires, or -1 if there are no timers left.

All other functions return 0 in case of a successful execution.

# [ERRORS](#ERRORS)

On *zmq\_timers\_destroy*, *zmq\_poller\_cancel*, *zmq\_timers\_set\_interval*, *zmq\_timers\_reset*, zmq\_timers\_timeout\_, and *zmq\_timers\_execute*: **EFAULT**:: *timers* did not point to a valid timer. Note that passing an invalid pointer (e.g. pointer to deallocated memory) may cause undefined behaviour (e.g. an access violation).

On *zmq\_timers\_add*: **EFAULT**:: *timers* did not point to a valid timer or *handler* did not point to a valid function.

On *zmq\_poller\_cancel*, *zmq\_timers\_set\_interval* and zmq\_timers\_timeout\_: **EINVAL**:: *timer\_id* did not exist or was already cancelled.

# [EXAMPLE](#EXAMPLE)

**Add one timer with a simple callback that changes a boolean.**.

```


    void handler (int timer_id_, void *arg_)


    {


        (void) timer_id_; //  Stop 'unused' compiler warnings


        *((bool *) arg_) = true;


    }


    ...


    void *timers = zmq_timers_new ();


    assert (timers);


    bool timer_invoked = false;


    const unsigned long full_timeout = 100;


    int timer_id =


      zmq_timers_add (timers, full_timeout, handler, &timer_invoked);


    assert (timer_id);


    //  Timer should not have been invoked yet


    int rc = zmq_timers_execute (timers);


    assert (rc == 0);


    //  Wait half the time and check again


    long timeout = zmq_timers_timeout (timers);


    assert (rc != -1);


    msleep (timeout / 2);


    rc = zmq_timers_execute (timers);


    assert (rc == 0);


    // Wait until the end


    rc = msleep (zmq_timers_timeout (timers));


    assert (rc == 0);


    assert (timer_invoked);


    rc = zmq_timers_destroy (&timers);


    assert (rc == 0);
```

# [SEE ALSO](#SEE_ALSO)

[**zmq**(7)](/man/os/zeromq/zmq.7)

# [AUTHORS](#AUTHORS)

This page was written by the 0MQ community. To make a change please read the 0MQ Contribution Policy at **http://www.zeromq.org/docs:contributing**.

10/26/2026 0MQ 4.3.5

---

Document: zmq_timers(3) from zeromq 4.3.5-r15 (Chainguard OS)
Source: https://github.com/zeromq/libzmq