You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
217 lines
7.5 KiB
217 lines
7.5 KiB
5 years ago
|
'\" t
|
||
|
|
.\" Title: zpoller
|
||
|
|
.\" Author: [see the "AUTHORS" section]
|
||
|
|
.\" Generator: DocBook XSL Stylesheets v1.76.1 <http://docbook.sf.net/>
|
||
|
|
.\" Date: 12/31/2016
|
||
|
|
.\" Manual: CZMQ Manual
|
||
|
|
.\" Source: CZMQ 4.0.2
|
||
|
|
.\" Language: English
|
||
|
|
.\"
|
||
|
|
.TH "ZPOLLER" "3" "12/31/2016" "CZMQ 4\&.0\&.2" "CZMQ Manual"
|
||
|
|
.\" -----------------------------------------------------------------
|
||
|
|
.\" * Define some portability stuff
|
||
|
|
.\" -----------------------------------------------------------------
|
||
|
|
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
|
.\" http://bugs.debian.org/507673
|
||
|
|
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
|
||
|
|
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
|
.ie \n(.g .ds Aq \(aq
|
||
|
|
.el .ds Aq '
|
||
|
|
.\" -----------------------------------------------------------------
|
||
|
|
.\" * set default formatting
|
||
|
|
.\" -----------------------------------------------------------------
|
||
|
|
.\" disable hyphenation
|
||
|
|
.nh
|
||
|
|
.\" disable justification (adjust text to left margin only)
|
||
|
|
.ad l
|
||
|
|
.\" -----------------------------------------------------------------
|
||
|
|
.\" * MAIN CONTENT STARTS HERE *
|
||
|
|
.\" -----------------------------------------------------------------
|
||
|
|
.SH "NAME"
|
||
|
|
zpoller \- trivial socket poller class
|
||
|
|
.SH "SYNOPSIS"
|
||
|
|
.sp
|
||
|
|
.nf
|
||
|
|
// This is a stable class, and may not change except for emergencies\&. It
|
||
|
|
// is provided in stable builds\&.
|
||
|
|
// Create new poller, specifying zero or more readers\&. The list of
|
||
|
|
// readers ends in a NULL\&. Each reader can be a zsock_t instance, a
|
||
|
|
// zactor_t instance, a libzmq socket (void *), or a file handle\&.
|
||
|
|
CZMQ_EXPORT zpoller_t *
|
||
|
|
zpoller_new (void *reader, \&.\&.\&.);
|
||
|
|
|
||
|
|
// Destroy a poller
|
||
|
|
CZMQ_EXPORT void
|
||
|
|
zpoller_destroy (zpoller_t **self_p);
|
||
|
|
|
||
|
|
// Add a reader to be polled\&. Returns 0 if OK, \-1 on failure\&. The reader may
|
||
|
|
// be a libzmq void * socket, a zsock_t instance, or a zactor_t instance\&.
|
||
|
|
CZMQ_EXPORT int
|
||
|
|
zpoller_add (zpoller_t *self, void *reader);
|
||
|
|
|
||
|
|
// Remove a reader from the poller; returns 0 if OK, \-1 on failure\&. The reader
|
||
|
|
// must have been passed during construction, or in an zpoller_add () call\&.
|
||
|
|
CZMQ_EXPORT int
|
||
|
|
zpoller_remove (zpoller_t *self, void *reader);
|
||
|
|
|
||
|
|
// By default the poller stops if the process receives a SIGINT or SIGTERM
|
||
|
|
// signal\&. This makes it impossible to shut\-down message based architectures
|
||
|
|
// like zactors\&. This method lets you switch off break handling\&. The default
|
||
|
|
// nonstop setting is off (false)\&.
|
||
|
|
CZMQ_EXPORT void
|
||
|
|
zpoller_set_nonstop (zpoller_t *self, bool nonstop);
|
||
|
|
|
||
|
|
// Poll the registered readers for I/O, return first reader that has input\&.
|
||
|
|
// The reader will be a libzmq void * socket, or a zsock_t or zactor_t
|
||
|
|
// instance as specified in zpoller_new/zpoller_add\&. The timeout should be
|
||
|
|
// zero or greater, or \-1 to wait indefinitely\&. Socket priority is defined
|
||
|
|
// by their order in the poll list\&. If you need a balanced poll, use the low
|
||
|
|
// level zmq_poll method directly\&. If the poll call was interrupted (SIGINT),
|
||
|
|
// or the ZMQ context was destroyed, or the timeout expired, returns NULL\&.
|
||
|
|
// You can test the actual exit condition by calling zpoller_expired () and
|
||
|
|
// zpoller_terminated ()\&. The timeout is in msec\&.
|
||
|
|
CZMQ_EXPORT void *
|
||
|
|
zpoller_wait (zpoller_t *self, int timeout);
|
||
|
|
|
||
|
|
// Return true if the last zpoller_wait () call ended because the timeout
|
||
|
|
// expired, without any error\&.
|
||
|
|
CZMQ_EXPORT bool
|
||
|
|
zpoller_expired (zpoller_t *self);
|
||
|
|
|
||
|
|
// Return true if the last zpoller_wait () call ended because the process
|
||
|
|
// was interrupted, or the parent context was destroyed\&.
|
||
|
|
CZMQ_EXPORT bool
|
||
|
|
zpoller_terminated (zpoller_t *self);
|
||
|
|
|
||
|
|
// Self test of this class\&.
|
||
|
|
CZMQ_EXPORT void
|
||
|
|
zpoller_test (bool verbose);
|
||
|
|
|
||
|
|
Please add \*(Aq@interface\*(Aq section in \*(Aq\&./\&.\&./src/zpoller\&.c\*(Aq\&.
|
||
|
|
.fi
|
||
|
|
.SH "DESCRIPTION"
|
||
|
|
.sp
|
||
|
|
The zpoller class provides a minimalist interface to ZeroMQ\(cqs zmq_poll API, for the very common case of reading from a number of sockets\&. It does not provide polling for output, nor polling on file handles\&. If you need either of these, use the zmq_poll API directly\&.
|
||
|
|
.sp
|
||
|
|
The class implements the poller using the zmq_poller API if that exists, else does the work itself\&.
|
||
|
|
.SH "EXAMPLE"
|
||
|
|
.PP
|
||
|
|
\fBFrom zpoller_test method\fR.
|
||
|
|
.sp
|
||
|
|
.if n \{\
|
||
|
|
.RS 4
|
||
|
|
.\}
|
||
|
|
.nf
|
||
|
|
// Create a few sockets
|
||
|
|
zsock_t *vent = zsock_new (ZMQ_PUSH);
|
||
|
|
assert (vent);
|
||
|
|
int port_nbr = zsock_bind (vent, "tcp://127\&.0\&.0\&.1:*");
|
||
|
|
assert (port_nbr != \-1);
|
||
|
|
zsock_t *sink = zsock_new (ZMQ_PULL);
|
||
|
|
assert (sink);
|
||
|
|
int rc = zsock_connect (sink, "tcp://127\&.0\&.0\&.1:%d", port_nbr);
|
||
|
|
assert (rc != \-1);
|
||
|
|
zsock_t *bowl = zsock_new (ZMQ_PULL);
|
||
|
|
assert (bowl);
|
||
|
|
zsock_t *dish = zsock_new (ZMQ_PULL);
|
||
|
|
assert (dish);
|
||
|
|
|
||
|
|
// Set up poller
|
||
|
|
zpoller_t *poller = zpoller_new (bowl, dish, NULL);
|
||
|
|
assert (poller);
|
||
|
|
|
||
|
|
// Add a reader to the existing poller
|
||
|
|
rc = zpoller_add (poller, sink);
|
||
|
|
assert (rc == 0);
|
||
|
|
|
||
|
|
zstr_send (vent, "Hello, World");
|
||
|
|
|
||
|
|
// We expect a message only on the sink
|
||
|
|
zsock_t *which = (zsock_t *) zpoller_wait (poller, \-1);
|
||
|
|
assert (which == sink);
|
||
|
|
assert (zpoller_expired (poller) == false);
|
||
|
|
assert (zpoller_terminated (poller) == false);
|
||
|
|
char *message = zstr_recv (which);
|
||
|
|
assert (streq (message, "Hello, World"));
|
||
|
|
zstr_free (&message);
|
||
|
|
|
||
|
|
// Stop polling reader
|
||
|
|
rc = zpoller_remove (poller, sink);
|
||
|
|
assert (rc == 0);
|
||
|
|
|
||
|
|
// Check we can poll an FD
|
||
|
|
rc = zsock_connect (bowl, "tcp://127\&.0\&.0\&.1:%d", port_nbr);
|
||
|
|
assert (rc != \-1);
|
||
|
|
SOCKET fd = zsock_fd (bowl);
|
||
|
|
rc = zpoller_add (poller, (void *) &fd);
|
||
|
|
assert (rc != \-1);
|
||
|
|
zstr_send (vent, "Hello again, world");
|
||
|
|
assert (zpoller_wait (poller, 500) == &fd);
|
||
|
|
|
||
|
|
// Check zpoller_set_nonstop ()
|
||
|
|
zsys_interrupted = 1;
|
||
|
|
zpoller_wait (poller, 0);
|
||
|
|
assert (zpoller_terminated (poller));
|
||
|
|
zpoller_set_nonstop (poller, true);
|
||
|
|
zpoller_wait (poller, 0);
|
||
|
|
assert (!zpoller_terminated (poller));
|
||
|
|
zsys_interrupted = 0;
|
||
|
|
|
||
|
|
zpoller_destroy (&poller);
|
||
|
|
zsock_destroy (&vent);
|
||
|
|
zsock_destroy (&sink);
|
||
|
|
zsock_destroy (&bowl);
|
||
|
|
zsock_destroy (&dish);
|
||
|
|
|
||
|
|
#ifdef ZMQ_SERVER
|
||
|
|
// Check thread safe sockets
|
||
|
|
zpoller_destroy (&poller);
|
||
|
|
zsock_t *client = zsock_new (ZMQ_CLIENT);
|
||
|
|
assert (client);
|
||
|
|
zsock_t *server = zsock_new (ZMQ_SERVER);
|
||
|
|
assert (server);
|
||
|
|
poller = zpoller_new (client, server, NULL);
|
||
|
|
assert (poller);
|
||
|
|
port_nbr = zsock_bind (server, "tcp://127\&.0\&.0\&.1:*");
|
||
|
|
assert (port_nbr != \-1);
|
||
|
|
rc = zsock_connect (client, "tcp://127\&.0\&.0\&.1:%d", port_nbr);
|
||
|
|
assert (rc != \-1);
|
||
|
|
|
||
|
|
zstr_send (client, "Hello, World");
|
||
|
|
|
||
|
|
// We expect a message only on the server
|
||
|
|
which = (zsock_t *) zpoller_wait (poller, \-1);
|
||
|
|
assert (which == server);
|
||
|
|
assert (zpoller_expired (poller) == false);
|
||
|
|
assert (zpoller_terminated (poller) == false);
|
||
|
|
message = zstr_recv (which);
|
||
|
|
assert (streq (message, "Hello, World"));
|
||
|
|
zstr_free (&message);
|
||
|
|
|
||
|
|
zpoller_destroy (&poller);
|
||
|
|
zsock_destroy (&client);
|
||
|
|
zsock_destroy (&server);
|
||
|
|
#endif
|
||
|
|
.fi
|
||
|
|
.if n \{\
|
||
|
|
.RE
|
||
|
|
.\}
|
||
|
|
.sp
|
||
|
|
.SH "AUTHORS"
|
||
|
|
.sp
|
||
|
|
The czmq manual was written by the authors in the AUTHORS file\&.
|
||
|
|
.SH "RESOURCES"
|
||
|
|
.sp
|
||
|
|
Main web site: \m[blue]\fB\%\fR\m[]
|
||
|
|
.sp
|
||
|
|
Report bugs to the email <\m[blue]\fBzeromq\-dev@lists\&.zeromq\&.org\fR\m[]\&\s-2\u[1]\d\s+2>
|
||
|
|
.SH "COPYRIGHT"
|
||
|
|
.sp
|
||
|
|
Copyright (c) the Contributors as noted in the AUTHORS file\&. This file is part of CZMQ, the high\-level C binding for 0MQ: http://czmq\&.zeromq\&.org\&. This Source Code Form is subject to the terms of the Mozilla Public License, v\&. 2\&.0\&. If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla\&.org/MPL/2\&.0/\&. LICENSE included with the czmq distribution\&.
|
||
|
|
.SH "NOTES"
|
||
|
|
.IP " 1." 4
|
||
|
|
zeromq-dev@lists.zeromq.org
|
||
|
|
.RS 4
|
||
|
|
\%mailto:zeromq-dev@lists.zeromq.org
|
||
|
|
.RE
|