diff --git a/doc/Makefile.am b/doc/Makefile.am index e6dd83c3..f2eba812 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_poller.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 00000000..b7541b19 --- /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 . diff --git a/include/zmq.h b/include/zmq.h index 8449fc5d..c0094bad 100644 --- a/include/zmq.h +++ b/include/zmq.h @@ -543,6 +543,25 @@ ZMQ_EXPORT int zmq_atomic_counter_dec (void *counter_); ZMQ_EXPORT int zmq_atomic_counter_value (void *counter_); ZMQ_EXPORT void zmq_atomic_counter_destroy (void **counter_p_); +/******************************************************************************/ +/* Scheduling timers */ +/******************************************************************************/ + +#define ZMQ_HAVE_TIMERS + +typedef void(zmq_timer_fn) (int timer_id, void *arg); + +ZMQ_EXPORT void *zmq_timers_new (void); +ZMQ_EXPORT int zmq_timers_destroy (void **timers_p); +ZMQ_EXPORT int +zmq_timers_add (void *timers, size_t interval, zmq_timer_fn handler, void *arg); +ZMQ_EXPORT int zmq_timers_cancel (void *timers, int timer_id); +ZMQ_EXPORT int +zmq_timers_set_interval (void *timers, int timer_id, size_t interval); +ZMQ_EXPORT int zmq_timers_reset (void *timers, int timer_id); +ZMQ_EXPORT long zmq_timers_timeout (void *timers); +ZMQ_EXPORT int zmq_timers_execute (void *timers); + /******************************************************************************/ /* These functions are not documented by man pages -- use at your own risk. */ @@ -706,25 +725,6 @@ ZMQ_EXPORT int zmq_socket_get_peer_state (void *socket, const void *routing_id, size_t routing_id_size); -/******************************************************************************/ -/* Scheduling timers */ -/******************************************************************************/ - -#define ZMQ_HAVE_TIMERS - -typedef void(zmq_timer_fn) (int timer_id, void *arg); - -ZMQ_EXPORT void *zmq_timers_new (void); -ZMQ_EXPORT int zmq_timers_destroy (void **timers_p); -ZMQ_EXPORT int -zmq_timers_add (void *timers, size_t interval, zmq_timer_fn handler, void *arg); -ZMQ_EXPORT int zmq_timers_cancel (void *timers, int timer_id); -ZMQ_EXPORT int -zmq_timers_set_interval (void *timers, int timer_id, size_t interval); -ZMQ_EXPORT int zmq_timers_reset (void *timers, int timer_id); -ZMQ_EXPORT long zmq_timers_timeout (void *timers); -ZMQ_EXPORT int zmq_timers_execute (void *timers); - #endif // ZMQ_BUILD_DRAFT_API diff --git a/src/zmq_draft.h b/src/zmq_draft.h index 5ce06829..36cd54f4 100644 --- a/src/zmq_draft.h +++ b/src/zmq_draft.h @@ -162,24 +162,6 @@ int zmq_socket_get_peer_state (void *socket_, const void *routing_id_, size_t routing_id_size_); -/******************************************************************************/ -/* Scheduling timers */ -/******************************************************************************/ - -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_); - #endif // ZMQ_BUILD_DRAFT_API #endif //ifndef __ZMQ_DRAFT_H_INCLUDED__