0
0
mirror of https://github.com/zeromq/libzmq.git synced 2024-12-25 22:30:51 +08:00
libzmq/doc/zmq_timers.adoc
2024-11-22 10:28:16 +00:00

157 lines
4.9 KiB
Plaintext

= zmq_timers(3)
== 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);
// The handler will be executed
rc = zmq_timers_execute (timers);
assert (rc == 0);
assert (timer_invoked);
rc = zmq_timers_destroy (&timers);
assert (rc == 0);
----
== SEE ALSO
* xref:zmq.adoc[zmq]
== AUTHORS
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <https://zeromq.org/how-to-contribute/>.