UDP and Radio-dish documentation

doc/Makefile.am

@@ -21,7 +21,7 @@ MAN3 = zmq_bind.3 zmq_unbind.3 zmq_connect.3 zmq_disconnect.3 zmq_close.3 \
     zmq_atomic_counter_value.3 zmq_atomic_counter_destroy.3
 
 MAN7 = zmq.7 zmq_tcp.7 zmq_pgm.7 zmq_inproc.7 zmq_ipc.7 \
-    zmq_null.7 zmq_plain.7 zmq_curve.7 zmq_tipc.7 zmq_vmci.7
+    zmq_null.7 zmq_plain.7 zmq_curve.7 zmq_tipc.7 zmq_vmci.7 zmq_udp.7
 
 MAN_DOC =
 

doc/zmq.txt

@@ -165,6 +165,9 @@ Local in-process (inter-thread) communication transport::
 Virtual Machine Communications Interface (VMC) transport::
     linkzmq:zmq_vmci[7]
 
+Unreliable unicast and multicast using UDP::
+    linkzmq:zmq_udp[7]
+
 
 Proxies
 ~~~~~~~

doc/zmq_socket.txt

@@ -47,10 +47,19 @@ incoming connections *from multiple endpoints* bound to the socket using
 _zmq_bind()_, thus allowing many-to-many relationships.
 
 .Thread safety
-0MQ 'sockets' are _not_ thread safe. Applications MUST NOT use a socket
+0MQ has both thread safe socket type and _not_ thread safe socket types.
+Applications MUST NOT use a _not_ thread safe socket
 from multiple threads except after migrating a socket from one thread to
 another with a "full fence" memory barrier.
 
+Following are the thread safe sockets:
+* ZMQ_CLIENT
+* ZMQ_SERVER
+* ZMQ_DISH
+* ZMQ_RADIO
+* ZMQ_SCATTER
+* ZMQ_GATHER
+
 .Socket types
 The following sections present the socket types defined by 0MQ, grouped by the
 general _messaging pattern_ which is built from related socket types.
@@ -140,6 +149,70 @@ Incoming routing strategy:: Fair-queued
 Action in mute state:: Return EAGAIN
 
 
+Radio-dish pattern
+~~~~~~~~~~~~~~~~~~~~~~~~~
+The radio-dish pattern is used for one-to-many distribution of data from
+a single _publisher_ to multiple _subscribers_ in a fan out fashion.
+
+Radio-dish is using groups (vs Pub-sub topics), Dish sockets can join a group
+and each message sent by Radio sockets belong to a group.
+
+Groups are null terminated strings limited to 16 chars length (including null).
+The intention is to increase the length to 40 chars (including null).
+
+Groups are matched using exact matching (vs prefix matching of PubSub).
+
+NOTE: Radio-dish is still in draft phase.
+
+Note: this pattern is meant to eventually deprecate the use of 'ZMQ_PUB' and
+'ZMQ_SUB' to build pub-sub architectures.
+
+ZMQ_RADIO
+^^^^^^^
+A socket of type 'ZMQ_RADIO' is used by a _publisher_ to distribute data.
+Each message belong to a group, a group is specified with linkzmq_zmq_msg_set_group[3].
+Messages are distributed to all members of a group.
+The linkzmq:zmq_recv[3] function is not implemented for this socket type.
+
+When a 'ZMQ_RADIO' socket enters the 'mute' state due to having reached the
+high water mark for a _subscriber_, then any messages that would be sent to the
+_subscriber_ in question shall instead be dropped until the mute state
+ends. The _zmq_send()_ function shall never block for this socket type.
+
+NOTE: 'ZMQ_RADIO' sockets are threadsafe. They do not accept the ZMQ_SNDMORE
+option on sends. This limits them to single part data.
+
+[horizontal]
+.Summary of ZMQ_RADIO characteristics
+Compatible peer sockets:: 'ZMQ_DISH'
+Direction:: Unidirectional
+Send/receive pattern:: Send only
+Incoming routing strategy:: N/A
+Outgoing routing strategy:: Fan out
+Action in mute state:: Drop
+
+
+ZMQ_DISH
+^^^^^^^
+A socket of type 'ZMQ_DISH' is used by a _subscriber_ to subscribe to groups
+distributed by a _radio_. Initially a 'ZMQ_DISH' socket is not subscribed to
+any groups, use linkzmq:zmq_join[3] to
+join a group.
+To get the group the message belong to call linkzmq:zmq_msg_group[3].
+The _zmq_send()_ function is not implemented for this socket type.
+
+NOTE: 'ZMQ_DISH' sockets are threadsafe. They do not accept ZMQ_RCVMORE on receives.
+This limits them to single part data.
+
+[horizontal]
+.Summary of ZMQ_DISH characteristics
+Compatible peer sockets:: 'ZMQ_RADIO'
+Direction:: Unidirectional
+Send/receive pattern:: Receive only
+Incoming routing strategy:: Fair-queued
+Outgoing routing strategy:: N/A
+
+
 Publish-subscribe pattern
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 The publish-subscribe pattern is used for one-to-many distribution of data from

doc/zmq_udp.txt

@@ -0,0 +1,99 @@
+zmq_udp(7)
+==========
+
+
+NAME
+----
+zmq_udp - 0MQ UDP multicast and unicast transport
+
+
+SYNOPSIS
+--------
+UDP is unreliable protocol transport of data over IP networks.
+UDP support both unicast and multicast communication.
+
+
+DESCRIPTION
+-----------
+UDP transport can only be used with the 'ZMQ_RADIO' and
+'ZMQ_DISH' socket types.
+
+ADDRESSING
+----------
+A 0MQ endpoint is a string consisting of a 'transport'`://` followed by an
+'address'. The 'transport' specifies the underlying protocol to use. The
+'address' specifies the transport-specific address to connect to.
+
+For the UDP transport, the transport is `udp`.
+The meaning of the 'address' part is defined below.
+
+Binding a socket
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+With 'udp' we can only bind the 'ZMQ_DISH' socket type.
+When binding a socket using _zmq_bind()_ with the 'udp'
+transport the 'endpoint' shall be interpreted as an 'interface' followed by a
+colon and the UDP port number to use.
+
+An 'interface' may be specified by either of the following:
+
+* The wild-card `*`, meaning all available interfaces.
+* The primary IPv4 address assigned to the interface, in its numeric
+  representation.
+* Multicast address in its numeric representation the socket should join.
+
+The UDP port number may be specified a numeric value, usually above 1024 on POSIX systems.
+
+Connecting a socket
+~~~~~~~~~~~~~~~~~~~
+With 'udp' we can only connect the 'ZMQ_RADIO' socket type.
+When connecting a socket to a peer address using _zmq_connect()_ with the 'udp'
+transport, the 'endpoint' shall be interpreted as a 'peer address' followed by
+a colon and the UDP port number to use.
+
+A 'peer address' may be specified by either of the following:
+
+* The IPv4 or IPv6 address of the peer, in its numeric representation.
+* Multicast address in its numeric representation.
+
+EXAMPLES
+--------
+.Binding a socket
+----
+//  Unicast - UDP port 5555 on all available interfaces
+rc = zmq_bind(dish, "udp://*:5555");
+assert (rc == 0);
+//  Unicast - UDP port 5555 on the local loop-back interface
+rc = zmq_bind(dish, "udp://127.0.0.1:5555");
+assert (rc == 0);
+//  Multicast - UDP port 5555 on a Multicast address
+rc = zmq_bind(dish, "udp://239.0.0.1:5555");
+assert (rc == 0);
+----
+
+
+.Connecting a socket
+----
+//  Connecting using an Unicast IP address
+rc = zmq_connect(radio, "udp://192.168.1.1:5555");
+assert (rc == 0);
+//  Connecting using a Multicast address"
+rc = zmq_connect(socket, "udp://239.0.0.1:5555);
+assert (rc == 0);
+----
+
+
+SEE ALSO
+--------
+linkzmq:zmq_connect[3]
+linkzmq:zmq_setsockopt[3]
+linkzmq:zmq_tcp[7]
+linkzmq:zmq_ipc[7]
+linkzmq:zmq_inproc[7]
+linkzmq:zmq_vmci[7]
+linkzmq: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>.