---
name: "zmq_timers"
section: "3"
platform: "linux"
package: "zeromq"
version: "4.3.5-3"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/zmq_timers"
---

# zmq\_timers(3)

helper functions for cross-platform timers callbacks

## NAME

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

## 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

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

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

*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

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

**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

[**zmq**(7)](/zmq/7.md)

## 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**.