zmq_timers(3)

1ZMQ_TIMERS(3)                     0MQ Manual                     ZMQ_TIMERS(3)
2
3
4

NAME

6       zmq_timers - helper functions for cross-platform timers callbacks
7

SYNOPSIS

9       typedef void(zmq_timer_fn) (int timer_id, void *arg);
10
11       void *zmq_timers_new (void);
12
13       int zmq_timers_destroy (void *timers_p);*
14
15       int zmq_timers_add (void *timers, size_t interval, zmq_timer_fn
16       handler, void *arg);
17
18       int zmq_timers_cancel (void *timers, int timer_id);
19
20       int zmq_timers_set_interval (void *timers, int timer_id, size_t
21       interval);
22
23       int zmq_timers_reset (void *timers, int timer_id);
24
25       long zmq_timers_timeout (void *timers);
26
27       int zmq_timers_execute (void *timers);
28

DESCRIPTION

30       The zmq_timers*_ functions provide cross-platform access to timers
31       callbacks. Once a timer has been registered, it will repeat at the
32       specified interval until it gets manually cancelled. To run the
33       callbacks, zmq_timers_execute must be ran.
34
35       zmq_timers_new and zmq_timers_destroy manage the lifetime of a timer
36       instance. zmq_timers_new creates and returns a new timer instance,
37       while zmq_timers_destroy destroys it. A pointer to a valid timer must
38       be passed as the timers_p argument of zmq_timers_destroy. In
39       particular, zmq_timers_destroy may not be called multiple times for the
40       same timer instance. zmq_timers_destroy sets the passed pointer to NULL
41       in case of a successful execution.
42
43       zmq_timers_add and zmq_timers_cancel manage the timers registered.
44
45       zmq_timers_add registers a new timer with a given instance. timers must
46       point to a valid timers object. The interval parameter specifies the
47       expiration of the timer in milliseconds. handler and arg specify the
48       callback that will be invoked on expiration and the optional parameter
49       that will be passed through. The callback must be a valid function
50       implementing the zmq_timer_fn prototype. An ID will be returned that
51       can be used to modify or cancel the timer.
52
53       zmq_timers_cancel will cancel the timer associated with timer_id from
54       the instance timers.
55
56       zmq_timers_set_interval will set the expiration of the timer associated
57       with timer_id from the instance timers to interval milliseconds into
58       the future.
59
60       zmq_timers_reset will restart the timer associated with timer_id from
61       the instance timers.
62
63       zmq_timers_timeout will return the time left in milliseconds until the
64       next timer registered with timers expires.
65
66       zmq_timers_execute will run callbacks of all expired timers from the
67       instance timers.
68

THREAD SAFETY

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

RETURN VALUE

74       zmq_timers_new always returns a valid pointer to a poller.
75
76       All functions that return an int, return -1 in case of a failure. In
77       that case, zmq_errno() can be used to query the type of the error as
78       described below.
79
80       zmq_timers_timeout returns the time left in milliseconds until the next
81       timer registered with timers expires, or -1 if there are no timers
82       left.
83
84       All other functions return 0 in case of a successful execution.
85

ERRORS

87       On zmq_timers_destroy, zmq_poller_cancel, zmq_timers_set_interval,
88       zmq_timers_reset, zmq_timers_timeout_, and zmq_timers_execute: EFAULT::
89       timers did not point to a valid timer. Note that passing an invalid
90       pointer (e.g. pointer to deallocated memory) may cause undefined
91       behaviour (e.g. an access violation).
92
93       On zmq_timers_add: EFAULT:: timers did not point to a valid timer or
94       handler did not point to a valid function.
95
96       On zmq_poller_cancel, zmq_timers_set_interval and zmq_timers_timeout_:
97       EINVAL:: timer_id did not exist or was already cancelled.
98

EXAMPLE

100       Add one timer with a simple callback that changes a boolean..
101
102               void handler (int timer_id_, void *arg_)
103               {
104                   (void) timer_id_; //  Stop 'unused' compiler warnings
105                   *((bool *) arg_) = true;
106               }
107
108               ...
109
110               void *timers = zmq_timers_new ();
111               assert (timers);
112
113               bool timer_invoked = false;
114
115               const unsigned long full_timeout = 100;
116
117               int timer_id =
118                 zmq_timers_add (timers, full_timeout, handler, &timer_invoked);
119               assert (timer_id);
120
121               //  Timer should not have been invoked yet
122               int rc = zmq_timers_execute (timers);
123               assert (rc == 0);
124
125               //  Wait half the time and check again
126               long timeout = zmq_timers_timeout (timers);
127               assert (rc != -1);
128               msleep (timeout / 2);
129               rc = zmq_timers_execute (timers);
130               assert (rc == 0);
131
132               // Wait until the end
133               rc = msleep (zmq_timers_timeout (timers));
134               assert (rc == 0);
135               assert (timer_invoked);
136
137               rc = zmq_timers_destroy (&timers);
138               assert (rc == 0);
139
140

AUTHORS

145       This page was written by the 0MQ community. To make a change please
146       read the 0MQ Contribution Policy at
147       http://www.zeromq.org/docs:contributing.
148
149
150
1510MQ 4.3.4                         07/23/2021                     ZMQ_TIMERS(3)