diff --git a/doc/Makefile.am b/doc/Makefile.am index 5c32954e..ac155d69 100644 --- a/doc/Makefile.am +++ b/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 = diff --git a/doc/zmq.txt b/doc/zmq.txt index 9b5b4ce1..e3106e05 100644 --- a/doc/zmq.txt +++ b/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 ~~~~~~~ diff --git a/doc/zmq_socket.txt b/doc/zmq_socket.txt index abdf7387..0b2d57ab 100644 --- a/doc/zmq_socket.txt +++ b/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 diff --git a/doc/zmq_udp.txt b/doc/zmq_udp.txt new file mode 100644 index 00000000..49bfd8a3 --- /dev/null +++ b/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 .