From dcc1725a90f324e3877e67f1455ef9f53f1c241d Mon Sep 17 00:00:00 2001 From: Pieter Hintjens Date: Wed, 15 Feb 2012 18:41:09 -0600 Subject: [PATCH] Renamed zmq_getmsgopt to zmq_msg_peek * Added zmq_msg_poke for orthogonality * Added zmq_msg_more for simplicity * Fixed up man pages and test program --- doc/Makefile.am | 2 +- doc/zmq.txt | 12 ++-- doc/zmq_msg_more.txt | 63 +++++++++++++++++++++ doc/{zmq_getmsgopt.txt => zmq_msg_peek.txt} | 34 ++++++----- doc/zmq_msg_poke.txt | 47 +++++++++++++++ include/zmq.h | 10 +++- src/zmq.cpp | 53 ++++++++++++----- tests/test_msg_flags.cpp | 8 ++- 8 files changed, 185 insertions(+), 44 deletions(-) create mode 100644 doc/zmq_msg_more.txt rename doc/{zmq_getmsgopt.txt => zmq_msg_peek.txt} (66%) create mode 100644 doc/zmq_msg_poke.txt diff --git a/doc/Makefile.am b/doc/Makefile.am index 103652fa..741e4f96 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -3,7 +3,7 @@ MAN3 = zmq_bind.3 zmq_close.3 zmq_connect.3 zmq_init.3 \ zmq_msg_init_data.3 zmq_msg_init_size.3 zmq_msg_move.3 zmq_msg_size.3 \ zmq_poll.3 zmq_recv.3 zmq_send.3 zmq_setsockopt.3 zmq_socket.3 \ zmq_strerror.3 zmq_term.3 zmq_version.3 zmq_getsockopt.3 zmq_errno.3 \ - zmq_sendmsg.3 zmq_recvmsg.3 zmq_getmsgopt.3 + zmq_sendmsg.3 zmq_recvmsg.3 zmq_msg_peek.3 zmq_msg_poke.3 zmq_msg_more.3 MAN7 = zmq.7 zmq_tcp.7 zmq_pgm.7 zmq_epgm.7 zmq_inproc.7 zmq_ipc.7 MAN_DOC = $(MAN1) $(MAN3) $(MAN7) diff --git a/doc/zmq.txt b/doc/zmq.txt index 5a252ea1..277b68f6 100644 --- a/doc/zmq.txt +++ b/doc/zmq.txt @@ -83,9 +83,11 @@ Release a message:: Access message content:: linkzmq:zmq_msg_data[3] linkzmq:zmq_msg_size[3] + linkzmq:zmq_msg_more[3] -Get message properties:: - linkzmq:zmq_getmsgopt[3] +Work with message properties:: + linkzmq:zmq_msg_peek[3] + linkzmq:zmq_msg_poke[3] Message manipulation:: linkzmq:zmq_msg_copy[3] @@ -180,14 +182,14 @@ by C programmers. The intent is that programmers using 0MQ from other languages shall refer to this documentation alongside any documentation provided by the vendor of their language binding. -Language bindings (Python, Ruby, Java and more) are provided by members +Language bindings (Python, PHP, Ruby, Java and more) are provided by members of the 0MQ community and pointers can be found on the 0MQ website. AUTHORS ------- -The 0MQ documentation was written by Martin Sustrik and -Martin Lucina . +This 0MQ manual page was written by Martin Sustrik , +Martin Lucina , and Pieter Hintjens . RESOURCES diff --git a/doc/zmq_msg_more.txt b/doc/zmq_msg_more.txt new file mode 100644 index 00000000..ff52b1a9 --- /dev/null +++ b/doc/zmq_msg_more.txt @@ -0,0 +1,63 @@ +zmq_msg_more(3) +=============== + + +NAME +---- +zmq_msg_more - indicate if there are more message parts to receive + + +SYNOPSIS +-------- +*int zmq_msg_more (zmq_msg_t '*message');* + + +DESCRIPTION +----------- +The _zmq_msg_more()_ function indicates whether this is part of a multi-part +message, and there are further parts to receive. + + +RETURN VALUE +------------ +The _zmq_msg_more()_ function shall return zero if this is the final part of +a multi-part message, or the only part of a single-part message. It shall +return 1 if there are further parts to receive. + + +EXAMPLE +------- +.Receiving a multi-part message +---- +zmq_msg_t part; +while (true) { + // Create an empty 0MQ message to hold the message part + int rc = zmq_msg_init (&part); + assert (rc == 0); + // Block until a message is available to be received from socket + rc = zmq_recvmsg (socket, &part, 0); + assert (rc != -1); + if (zmq_msg_more (&part)) + fprintf (stderr, "more\n"); + else { + fprintf (stderr, "end\n"); + break; + } + zmq_msg_close (part); +} +---- + + +SEE ALSO +-------- +linkzmq:zmq_msg_peek[3] +linkzmq:zmq_msg_poke[3] +linkzmq:zmq_msg_init[3] +linkzmq:zmq_msg_close[3] +linkzmq:zmq[7] + + +AUTHORS +------- +This 0MQ manual page was written by Chuck Remes and Pieter +Hintjens . diff --git a/doc/zmq_getmsgopt.txt b/doc/zmq_msg_peek.txt similarity index 66% rename from doc/zmq_getmsgopt.txt rename to doc/zmq_msg_peek.txt index 8eda3eb2..2cdaafe3 100644 --- a/doc/zmq_getmsgopt.txt +++ b/doc/zmq_msg_peek.txt @@ -1,20 +1,20 @@ -zmq_getmsgopt(3) -================ +zmq_msg_peek(3) +=============== NAME ---- -zmq_getmsgopt - retrieve message option +zmq_msg_peek - get message options SYNOPSIS -------- -*int zmq_getmsgopt (zmq_msg_t '*message', int 'option_name', void '*option_value', size_t '*option_len');* +*int zmq_msg_peek (zmq_msg_t '*message', int 'option_name', void '*option_value', size_t '*option_len');* DESCRIPTION ----------- -The _zmq_getmsgopt()_ function shall retrieve the value for the option +The _zmq_msg_peek()_ function shall retrieve the value for the option specified by the 'option_name' argument for the message pointed to by the 'message' argument, and store it in the buffer pointed to by the 'option_value' argument. The 'option_len' argument is the size in bytes of the buffer pointed @@ -22,14 +22,14 @@ to by 'option_value'; upon successful completion _zmq_getsockopt()_ shall modify the 'option_len' argument to indicate the actual size of the option value stored in the buffer. -The following options can be retrieved with the _zmq_getmsgopt()_ function: +The following options can be retrieved with the _zmq_msg_peek()_ function: *ZMQ_MORE*:: Indicates that there are more message parts to follow after the 'message'. RETURN VALUE ------------ -The _zmq_getmsgopt()_ function shall return zero if successful. Otherwise it +The _zmq_msg_peek()_ function shall return zero if successful. Otherwise it shall return `-1` and set 'errno' to one of the values defined below. @@ -50,20 +50,19 @@ zmq_msg_t part; int more; size_t more_size = sizeof (more); while (true) { - /* Create an empty 0MQ message to hold the message part */ + // Create an empty 0MQ message to hold the message part int rc = zmq_msg_init (&part); assert (rc == 0); - /* Block until a message is available to be received from socket */ + // Block until a message is available to be received from socket rc = zmq_recvmsg (socket, &part, 0); assert (rc != -1); rc = getmsgopt (&part, ZMQ_MORE, &more, &more_size); assert (rc == 0); - if (more) { - fprintf (stderr, "more\n"); - } + if (more) + fprintf (stderr, "more\n"); else { - fprintf (stderr, "end\n"); - break; + fprintf (stderr, "end\n"); + break; } zmq_msg_close (part); } @@ -72,14 +71,13 @@ while (true) { SEE ALSO -------- -linkzmq:zmq_msg_data[3] +linkzmq:zmq_msg_poke[3] linkzmq:zmq_msg_init[3] -linkzmq:zmq_msg_init_size[3] -linkzmq:zmq_msg_init_data[3] linkzmq:zmq_msg_close[3] linkzmq:zmq[7] AUTHORS ------- -This 0MQ manual page was written by Chuck Remes . +This 0MQ manual page was written by Chuck Remes and Pieter +Hintjens . diff --git a/doc/zmq_msg_poke.txt b/doc/zmq_msg_poke.txt new file mode 100644 index 00000000..b6bb86f3 --- /dev/null +++ b/doc/zmq_msg_poke.txt @@ -0,0 +1,47 @@ +zmq_msg_poke(3) +=============== + + +NAME +---- + +zmq_msg_poke - set message options + + +SYNOPSIS +-------- +*int zmq_msg_peek (zmq_msg_t '*message', int 'option_name', const void '*option_value', size_t '*option_len');* + + +DESCRIPTION +----------- +The _zmq_msg_poke()_ function shall set the option specified by the +'option_name' argument to the value pointed to by the 'option_value' argument +for the 0MQ socket pointed to by the 'socket' argument. The 'option_len' +argument is the size of the option value in bytes. + +Currently the _zmq_msg_poke()_ function does not support any option names. + + +RETURN VALUE +------------ +The _zmq_msg_poke()_ function shall return zero if successful. Otherwise it +shall return `-1` and set 'errno' to one of the values defined below. + + +ERRORS +------ +*EINVAL*:: +The requested option _option_name_ is unknown, or the requested _option_len_ or +_option_value_ is invalid. + + +SEE ALSO +-------- +linkzmq:zmq_msg_peek[3] +linkzmq:zmq[7] + + +AUTHORS +------- +This 0MQ manual page was written by Pieter Hintjens . diff --git a/include/zmq.h b/include/zmq.h index 23c6bee0..cd798fe4 100644 --- a/include/zmq.h +++ b/include/zmq.h @@ -1,5 +1,5 @@ /* - Copyright (c) 2007-2010 iMatix Corporation + Copyright (c) 2007-2012 iMatix Corporation Copyright (c) 2009-2011 250bpm s.r.o. Copyright (c) 2011 VMware, Inc. Copyright (c) 2007-2011 Other contributors as noted in the AUTHORS file @@ -166,8 +166,12 @@ ZMQ_EXPORT int zmq_msg_move (zmq_msg_t *dest, zmq_msg_t *src); ZMQ_EXPORT int zmq_msg_copy (zmq_msg_t *dest, zmq_msg_t *src); ZMQ_EXPORT void *zmq_msg_data (zmq_msg_t *msg); ZMQ_EXPORT size_t zmq_msg_size (zmq_msg_t *msg); -ZMQ_EXPORT int zmq_getmsgopt (zmq_msg_t *msg, int option, void *optval, - size_t *optvallen); +ZMQ_EXPORT int zmq_msg_more (zmq_msg_t *msg); +ZMQ_EXPORT int zmq_msg_peek (zmq_msg_t *msg, int option, void *optval, + size_t *optvallen); +ZMQ_EXPORT int zmq_msg_poke (zmq_msg_t *msg, int option, const void *optval, + size_t *optvallen); + /******************************************************************************/ /* 0MQ infrastructure (a.k.a. context) initialisation & termination. */ diff --git a/src/zmq.cpp b/src/zmq.cpp index 6dba8ac3..00497182 100644 --- a/src/zmq.cpp +++ b/src/zmq.cpp @@ -1,6 +1,6 @@ /* + Copyright (c) 2007-2012 iMatix Corporation Copyright (c) 2009-2011 250bpm s.r.o. - Copyright (c) 2007-2011 iMatix Corporation Copyright (c) 2007-2011 Other contributors as noted in the AUTHORS file This file is part of 0MQ. @@ -541,23 +541,48 @@ size_t zmq_msg_size (zmq_msg_t *msg_) return ((zmq::msg_t*) msg_)->size (); } -int zmq_getmsgopt (zmq_msg_t *msg_, int option_, void *optval_, +int zmq_msg_more (zmq_msg_t *msg_) +{ + int more; + size_t more_size = sizeof (more); + int rc = zmq_msg_peek (msg_, ZMQ_MORE, &more, &more_size); + assert (rc == 0); + return more; +} + +int zmq_msg_peek (zmq_msg_t *msg_, int option_, void *optval_, size_t *optvallen_) { - switch (option_) { - case ZMQ_MORE: - if (*optvallen_ < sizeof (int)) { - errno = EINVAL; - return -1; - } - *((int*) optval_) = - (((zmq::msg_t*) msg_)->flags () & zmq::msg_t::more) ? 1 : 0; - *optvallen_ = sizeof (int); - return 0; - default: - errno = EINVAL; + if (!msg_) { + errno = EFAULT; return -1; } + switch (option_) { + case ZMQ_MORE: + if (*optvallen_ < sizeof (int)) { + errno = EINVAL; + return -1; + } + *((int*) optval_) = + (((zmq::msg_t*) msg_)->flags () & zmq::msg_t::more)? 1 : 0; + *optvallen_ = sizeof (int); + return 0; + default: + errno = EINVAL; + return -1; + } +} + +int zmq_msg_poke (zmq_msg_t *msg_, int option_, const void *optval_, + size_t *optvallen_) +{ + if (!msg_) { + errno = EFAULT; + return -1; + } + // No options supported at present + errno = EINVAL; + return -1; } // Polling. diff --git a/tests/test_msg_flags.cpp b/tests/test_msg_flags.cpp index 10fd5268..c14a86c6 100644 --- a/tests/test_msg_flags.cpp +++ b/tests/test_msg_flags.cpp @@ -1,5 +1,7 @@ /* + Copyright (c) 2007-2012 iMatix Corporation Copyright (c) 2011 250bpm s.r.o. + Copyright (c) 2007-2011 Other contributors as noted in the AUTHORS file This file is part of 0MQ. @@ -50,7 +52,7 @@ int main (int argc, char *argv []) assert (rc >= 0); int more; size_t more_size = sizeof (more); - rc = zmq_getmsgopt (&msg, ZMQ_MORE, &more, &more_size); + rc = zmq_msg_peek (&msg, ZMQ_MORE, &more, &more_size); assert (rc == 0); assert (more == 1); @@ -58,7 +60,7 @@ int main (int argc, char *argv []) rc = zmq_recvmsg (sb, &msg, 0); assert (rc == 1); more_size = sizeof (more); - rc = zmq_getmsgopt (&msg, ZMQ_MORE, &more, &more_size); + rc = zmq_msg_peek (&msg, ZMQ_MORE, &more, &more_size); assert (rc == 0); assert (more == 1); @@ -66,7 +68,7 @@ int main (int argc, char *argv []) rc = zmq_recvmsg (sb, &msg, 0); assert (rc == 1); more_size = sizeof (more); - rc = zmq_getmsgopt (&msg, ZMQ_MORE, &more, &more_size); + rc = zmq_msg_peek (&msg, ZMQ_MORE, &more, &more_size); assert (rc == 0); assert (more == 0);