Packaging of ZMQ_PROBE

- Cleaned up man page a little
- Wrote test case tests/test_router_probe.cpp

.gitignore

@@ -48,6 +48,7 @@ tests/test_disconnect_inproc
 tests/test_ctx_options
 tests/test_iov
 tests/test_security
+tests/test_router_probe
 src/platform.hpp*
 src/stamp-h1
 perf/local_lat

doc/zmq_setsockopt.txt

@@ -13,8 +13,8 @@ SYNOPSIS
 *int zmq_setsockopt (void '*socket', int 'option_name', const void '*option_value', size_t 'option_len');*
 
 Caution: All options, with the exception of ZMQ_SUBSCRIBE, ZMQ_UNSUBSCRIBE,
-ZMQ_LINGER, ZMQ_ROUTER_MANDATORY and ZMQ_XPUB_VERBOSE only take effect for 
-subsequent socket bind/connects.
+ZMQ_LINGER, ZMQ_ROUTER_MANDATORY, ZMQ_PROBE, and ZMQ_XPUB_VERBOSE only take 
+effect for subsequent socket bind/connects.
 
 DESCRIPTION
 -----------
@@ -392,7 +392,7 @@ Applicable socket types:: all, only for connection-oriented transports.
 ZMQ_ROUTER_MANDATORY: accept only routable messages on ROUTER sockets
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Sets the 'ROUTER' socket behavior when an unroutable message is encountered. A 
+Sets the ROUTER socket behavior when an unroutable message is encountered. A 
 value of `0` is the default and discards the message silently when it cannot be 
 routed.  A value of `1` returns an 'EHOSTUNREACH' error code if the message
 cannot be routed.
@@ -407,7 +407,7 @@ Applicable socket types:: ZMQ_ROUTER
 ZMQ_ROUTER_RAW: switch ROUTER socket to raw mode
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Sets the raw mode on the 'ROUTER', when set to 1. When the ROUTER socket is in
+Sets the raw mode on the ROUTER, when set to 1. When the ROUTER socket is in
 raw mode, and when using the tcp:// transport, it will read and write TCP data
 without 0MQ framing. This lets 0MQ applications talk to non-0MQ applications.
 When using raw mode, you cannot set explicit identities, and the ZMQ_MSGMORE
@@ -421,15 +421,17 @@ Default value:: 0
 Applicable socket types:: ZMQ_ROUTER
 
 
-ZMQ_PROBE: automatically send empty packet to every established connection
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ZMQ_PROBE: bootstrap connections to ROUTER sockets
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Sets the compatible sockets behavior to automatically send an empty packet
-to any new connection made (or accepted) by socket. It could help sockets to
-auto discovery them-self. It especially important in 'ROUTER' <-> 'ROUTER' connections
-where it solves 'who will write first' problems.
-NOTE: Don't set this options for sockets working with ZMQ_REP, ZMQ_REQ sockets.
-It will interfere with their strict synchronous logic and framing.
+When set to 1, the socket will automatically send an empty message when a 
+new connection is made or accepted. You may set this on REQ, DEALER, or 
+ROUTER sockets connected to a ROUTER socket. The application must filter
+such empty messages. The ZMQ_PROBE option in effect provides the ROUTER
+application with an event signaling the arrival of a new peer.
+
+NOTE: do not set this option on a socket that talks to any other socket
+types: the results are undefined.
 
 [horizontal]
 Option value type:: int

tests/Makefile.am

@@ -18,6 +18,7 @@ noinst_PROGRAMS = test_pair_inproc \
                   test_term_endpoint \
                   test_monitor \
                   test_router_mandatory \
+                  test_router_probe \
                   test_raw_sock \
                   test_disconnect_inproc \
                   test_ctx_options \
@@ -46,6 +47,7 @@ test_last_endpoint_SOURCES = test_last_endpoint.cpp
 test_term_endpoint_SOURCES = test_term_endpoint.cpp
 test_monitor_SOURCES = test_monitor.cpp
 test_router_mandatory_SOURCES = test_router_mandatory.cpp
+test_router_probe_SOURCES = test_router_probe.cpp
 test_raw_sock_SOURCES = test_raw_sock.cpp
 test_disconnect_inproc_SOURCES = test_disconnect_inproc.cpp
 test_ctx_options_SOURCES = test_ctx_options.cpp

tests/test_router_probe.cpp

@@ -0,0 +1,75 @@
+/*
+    Copyright (c) 2007-2013 Contributors as noted in the AUTHORS file
+
+    This file is part of 0MQ.
+
+    0MQ is free software; you can redistribute it and/or modify it under
+    the terms of the GNU Lesser General Public License as published by
+    the Free Software Foundation; either version 3 of the License, or
+    (at your option) any later version.
+
+    0MQ is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU Lesser General Public License for more details.
+
+    You should have received a copy of the GNU Lesser General Public License
+    along with this program.  If not, see <http://www.gnu.org/licenses/>.
+*/
+
+#include "../include/zmq.h"
+#include <stdio.h>
+#include <string.h>
+#undef NDEBUG
+#include <assert.h>
+
+int main (void)
+{
+    void *ctx = zmq_ctx_new ();
+    assert (ctx);
+    
+    //  Create server and bind to endpoint
+    void *server = zmq_socket (ctx, ZMQ_ROUTER);
+    assert (server);
+    int rc = zmq_bind (server, "tcp://*:5560");
+    assert (rc == 0);
+
+    //  Create client and connect to server, doing a probe
+    void *client = zmq_socket (ctx, ZMQ_DEALER);
+    assert (client);
+    rc = zmq_setsockopt (client, ZMQ_IDENTITY, "X", 1);
+    assert (rc == 0);
+    int probe = 1;
+    rc = zmq_setsockopt (client, ZMQ_PROBE, &probe, sizeof (probe));
+    assert (rc == 0);
+    rc = zmq_connect (client, "tcp://localhost:5560");
+    assert (rc == 0);
+
+    //  We expect an identity=X + empty message from client
+    unsigned char buffer [255];
+    rc = zmq_recv (server, buffer, 255, 0);
+    assert (rc == 1);
+    assert (buffer [0] ==  'X');
+    rc = zmq_recv (server, buffer, 255, 0);
+    assert (rc == 0);
+
+    //  Send a message to client now
+    rc = zmq_send (server, "X", 1, ZMQ_SNDMORE);
+    assert (rc == 1);
+    rc = zmq_send (server, "Hello", 5, 0);
+    assert (rc == 5);
+    
+    rc = zmq_recv (client, buffer, 255, 0);
+    assert (rc == 5);
+    
+    rc = zmq_close (server);
+    assert (rc == 0);
+
+    rc = zmq_close (client);
+    assert (rc == 0);
+
+    rc = zmq_ctx_term (ctx);
+    assert (rc == 0);
+
+    return 0 ;
+}