Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
ZMQ_POLLER(3)			  0MQ Manual			 ZMQ_POLLER(3)

NAME
       zmq_poller - input/output multiplexing

SYNOPSIS
       void *zmq_poller_new (void); int	zmq_poller_destroy (void *poller_p);*

       int zmq_poller_add (void	*poller, void *socket, void *user_data,	short
       events);	*int zmq_poller_modify (void *poller, void *socket, short
       events);	int zmq_poller_remove (void *poller, void *socket);

       int zmq_poller_add_fd (void *poller, int	fd, void *user_data, short
       events);	int zmq_poller_modify_fd (void *poller,	int fd,	short events);
       int zmq_poller_remove_fd	(void *poller, int fd);

       int zmq_poller_wait_all (void *poller, zmq_poller_event_t *events, int
       n_events, long timeout);

DESCRIPTION
       The zmq_poller*_	functions provide a mechanism for applications to
       multiplex input/output events in	a level-triggered fashion over a set
       of sockets.

       zmq_poller_new and zmq_poller_destroy manage the	lifetime of a poller
       instance. zmq_poller_new	creates	and returns a new poller instance,
       while zmq_poller_destroy	destroys it. A pointer to a valid poller must
       be passed as the	poller_p argument of zmq_poller_destroy. In
       particular, zmq_poller_destroy may not be called	multiple times for the
       same poller instance. zmq_poller_destroy	sets the passed	pointer	to
       NULL in case of a successful execution. zmq_poller_destroy implicitly
       unregisters all registered sockets and file descriptors.

       zmq_poller_add, zmq_poller_modify and zmq_poller_remove manage the 0MQ
       sockets registered with a poller.

       zmq_poller_add registers	a new socket with a given poller. Both poller
       and socket must point to	valid 0MQ objects. The events parameter
       specifies which event types the client wants to subscribe to. It	is
       legal to	specify	no events (i.e.	0), and	activate them later with
       zmq_poller_modify. In addition, user_data may be	specified, which is
       not used	by the poller, but passed back to the caller when an event was
       signalled in a call to zmq_poller_wait or zmq_poller_wait_all.
       user_data may be	NULL. If it is not NULL, it must be a valid pointer.
       Otherwise, behaviour is undefined. zmq_poller_add may not be called
       multiple	times for the same socket (unless zmq_poller_remove has	been
       called for that socket).

       zmq_poller_modify modifies the subscribed events	for a socket. It is
       legal to	specify	no events (i.e.	0) to disable events temporarily, and
       reactivate them later with another call to zmq_poller_modify.

       zmq_poller_remove removes a socket registration completely.
       zmq_poller_remove must be called	before a socket	is closed with
       zmq_close.

       Note that it is not necessary to	call zmq_poller_remove for any socket
       before calling zmq_poller_destroy.

       Also note that calling zmq_poller_remove	is not equivalent to calling
       zmq_poller_modify with no events. zmq_poller_modify does	not free
       resources associated with the socket registration, and requires that
       the socket remains valid.

       zmq_poller_add_fd, zmq_poller_modify_fd and zmq_poller_remove_fd	are
       analogous to the	previous functions but manage regular file
       descriptiors registered with a poller. On Windows, these	functions can
       only be used with WinSock sockets.

       In the following, 0MQ sockets added with	zmq_poller_add and file
       descriptors added with zmq_poller_add_fd	are referred to	as registered
       objects.

       The zmq_poller_event_t structure	is defined as follows:

	   typedef struct
	   {
	       void *socket;
	   #if defined _WIN32
	       SOCKET fd;
	   #else
	       int fd;
	   #endif
	       void *user_data;
	       short events;
	   } zmq_poller_event_t;

       For each	registered object, zmq_poller_wait_all() shall examine the
       registered objects for the event(s) currently registered.

       If none of the registered events	have occurred, zmq_poller_wait_all
       shall wait timeout milliseconds for an event to occur on	any of the
       registered objects. If the value	of timeout is 0, zmq_poller_wait_all
       shall return immediately. If the	value of timeout is -1,
       zmq_poller_wait_all shall block indefinitely until one event has
       occurred	on any of the registered objects.

       The events argument zmq_poller_wait_all must be a pointer to an array
       of at least n_events elements. Behaviour	is undefined if	events does
       not point to an array of	at least n_events elements.

       zmq_poller_wait_all returns at most n_events events. If more than
       n_events	events were signalled, only an unspecified subset of the
       signalled events	is returned through events.

       A caller	is advised to ensure that n_events is equal to the number of
       registered objects. Otherwise, a	livelock situation may result: If more
       than n_events registered	objects	have an	active event on	each call to
       zmq_poller_wait_all, it might happen that the same subset of registered
       objects is always returned, and the caller never	notices	the events on
       the others.

       zmq_poller_wait_all returns the number of valid elements. The valid
       elements	are placed in positions	0 to n_events -	1 in the events	array.
       All members of a	valid element are set to valid values by
       zmq_poller_wait_all. The	client does therefore not need to initialize
       the contents of the events array	before a call to zmq_poller_wait_all.
       It is unspecified whether the the remaining elements of events are
       written to by zmq_poller_wait_all.

EVENT TYPES
       The events parameter of zmq_poller_add and zmq_poller_modify, and the
       events member of	the zmq_poller_event_t structure are bit masks
       constructed by OR'ing a combination of the following event flags:

       ZMQ_POLLIN
	   For 0MQ sockets, at least one message may be	received from the
	   socket without blocking. For	standard sockets this is equivalent to
	   the POLLIN flag of the poll() system	call and generally means that
	   at least one	byte of	data may be read from fd without blocking.

       ZMQ_POLLOUT
	   For 0MQ sockets, at least one message may be	sent to	the socket
	   without blocking. For standard sockets this is equivalent to	the
	   POLLOUT flag	of the poll() system call and generally	means that at
	   least one byte of data may be written to fd without blocking.

       ZMQ_POLLERR
	   For 0MQ sockets this	flag has no effect on the zmq_poller_add and
	   zmq_poller_modify functions,	and is never set in the	events member
	   of the zmq_poller_event_t structure.	For standard sockets, this
	   flag	is passed through zmq_poller_wait_all to the underlying	poll()
	   system call and generally means that	some sort of error condition
	   is present on the socket specified by fd.

       ZMQ_POLLPRI
	   For 0MQ sockets this	flag has no effect on the zmq_poller_add and
	   zmq_poller_modify functions,	and is never set in the	events member
	   of the zmq_poller_event_t structure.	For standard sockets this
	   means there is urgent data to read. Refer to	the POLLPRI flag for
	   more	informations. For a file descriptor, refer to your OS
	   documentation: as an	example, GPIO interrupts are signaled through
	   a POLLPRI event. This flag has no effect on Windows.

	   Note
	   The zmq_poller*_ functions may be implemented or emulated using
	   operating system interfaces other than poll(), and as such may be
	   subject to the limits of those interfaces in	ways not defined in
	   this	documentation.

THREAD SAFETY
       Like most other 0MQ objects, a poller is	not thread-safe. All
       operations must be called from the same thread. Otherwise, behaviour is
       undefined.

RETURN VALUE
       zmq_poller_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_poller_wait_all returns the number of events	signalled and returned
       in the events array. It never returns 0.

       All other functions return 0 in case of a successful execution.

ERRORS
       On zmq_poller_new: ENOMEM:: A new poller	could not be allocated
       successfully.

       On zmq_poller_destroy: EFAULT:: poller_p	did not	point to a valid
       poller. Note that passing an invalid pointer (e.g. pointer to
       deallocated memory) may cause undefined behaviour (e.g. an access
       violation).

       On zmq_poller_add, zmq_poller_modify and	zmq_poller_remove: EFAULT::
       poller did not point to a valid poller. Note that passing an invalid
       pointer (e.g. pointer to	deallocated memory) may	cause undefined
       behaviour (e.g. an access violation). ENOTSOCK::	socket did not point
       to a valid socket. Note that passing an invalid pointer (e.g. pointer
       to deallocated memory) may cause	undefined behaviour (e.g. an access
       violation).

       On zmq_poller_add: EMFILE:: TODO

       On zmq_poller_add or zmq_poller_add_fd: ENOMEM::	Necessary resources
       could not be allocated. EINVAL::	socket resp. fd	was already registered
       with the	poller.

       On zmq_poller_modify, zmq_poller_modify_fd, zmq_poller_remove or
       zmq_poller_remove_fd: EINVAL:: socket resp. fd was not registered with
       the poller.

       On zmq_poller_add_fd, zmq_poller_modify_fd and zmq_poller_remove_fd:
       EBADF*: The fd specified	was the	retired	fd.

       On zmq_poller_wait and zmq_poller_wait_all: ETERM:: At least one	of the
       registered objects is a socket whose associated 0MQ context was
       terminated. EFAULT:: The	provided events	was NULL, or poller did	not
       point to	a valid	poller,	or there are no	registered objects and timeout
       was negative. EINTR:: The operation was interrupted by delivery of a
       signal before any events	were available.	EAGAIN:: No registered event
       was signalled before the	timeout	was reached.

EXAMPLE
       Polling indefinitely for	input events on	both a 0MQ socket and a
       standard	socket..

	   void	*poller	= zmq_poller_new ();

	   zmq_poller_event_t events [2];
	   /* First item refers	to 0MQ socket 'socket' */
	   zmq_poller_add (poller, socket, ZMQ_POLLIN, NULL);
	   /* Second item refers to standard socket 'fd' */
	   zmq_poller_add_fd (poller, fd, ZMQ_POLLIN, NULL);
	   /* Poll for events indefinitely */
	   int rc = zmq_poller_wait_all	(items,	events,	2, -1);
	   assert (rc >= 0);
	   /* Returned events will be stored in	'events' */
	   zmq_poller_destroy (&poller);

SEE ALSO
       zmq_socket(3) zmq_send(3) zmq_recv(3) zmq(7)

AUTHORS
       This page was written by	the 0MQ	community. To make a change please
       read the	0MQ Contribution Policy	at
       http://www.zeromq.org/docs:contributing.

0MQ 4.3.1			  01/12/2019			 ZMQ_POLLER(3)

NAME | SYNOPSIS | DESCRIPTION | EVENT TYPES | THREAD SAFETY | RETURN VALUE | ERRORS | EXAMPLE | SEE ALSO | AUTHORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=zmq_poller&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help