From 41838b6776aa102639b382eadf45b9a6105c5ba2 Mon Sep 17 00:00:00 2001 From: Luca Boccassi Date: Fri, 27 Jul 2018 23:04:05 +0100 Subject: [PATCH] Problem: no documentation for zmq_timers_* Solution: add a manpage Fixes #3005 --- doc/Makefile.am | 1 + doc/zmq_timers.txt | 162 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 163 insertions(+) create mode 100644 doc/zmq_timers.txt diff --git a/doc/Makefile.am b/doc/Makefile.am index e6dd83c37c..9319ee6df0 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -16,6 +16,7 @@ MAN3 = zmq_bind.3 zmq_unbind.3 zmq_connect.3 zmq_disconnect.3 zmq_close.3 \ zmq_proxy.3 zmq_proxy_steerable.3 \ zmq_z85_encode.3 zmq_z85_decode.3 zmq_curve_keypair.3 zmq_curve_public.3 \ zmq_has.3 \ + zmq_timers.3 \ zmq_atomic_counter_new.3 zmq_atomic_counter_set.3 \ zmq_atomic_counter_inc.3 zmq_atomic_counter_dec.3 \ zmq_atomic_counter_value.3 zmq_atomic_counter_destroy.3 diff --git a/doc/zmq_timers.txt b/doc/zmq_timers.txt new file mode 100644 index 0000000000..b7541b1906 --- /dev/null +++ b/doc/zmq_timers.txt @@ -0,0 +1,162 @@ +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); + assert (timer_invoked); + + rc = zmq_timers_destroy (&timers); + assert (rc == 0); +---- + + +SEE ALSO +-------- +linkzmq:zmq[7] + + +AUTHORS +------- +This page was written by the 0MQ community. To make a change please +read the 0MQ Contribution Policy at .