mirror of
https://github.com/zeromq/libzmq.git
synced 2024-12-25 22:30:51 +08:00
157 lines
4.9 KiB
Plaintext
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/>.
|