Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
ZMQ_SOCKET(3)			  0MQ Manual			 ZMQ_SOCKET(3)

NAME
       zmq_socket - create 0MQ socket

SYNOPSIS
       void *zmq_socket	(void *context,	int type);

DESCRIPTION
       The zmq_socket()	function shall create a	0MQ socket within the
       specified context and return an opaque handle to	the newly created
       socket. The type	argument specifies the socket type, which determines
       the semantics of	communication over the socket.

       The newly created socket	is initially unbound, and not associated with
       any endpoints. In order to establish a message flow a socket must first
       be connected to at least	one endpoint with zmq_connect(3), or at	least
       one endpoint must be created for	accepting incoming connections with
       zmq_bind(3).

       Key differences to conventional sockets.	Generally speaking,
       conventional sockets present a synchronous interface to either
       connection-oriented reliable byte streams (SOCK_STREAM),	or
       connection-less unreliable datagrams (SOCK_DGRAM). In comparison, 0MQ
       sockets present an abstraction of an asynchronous message queue,	with
       the exact queueing semantics depending on the socket type in use. Where
       conventional sockets transfer streams of	bytes or discrete datagrams,
       0MQ sockets transfer discrete messages.

       0MQ sockets being asynchronous means that the timings of	the physical
       connection setup	and tear down, reconnect and effective delivery	are
       transparent to the user and organized by	0MQ itself. Further, messages
       may be queued in	the event that a peer is unavailable to	receive	them.

       Conventional sockets allow only strict one-to-one (two peers),
       many-to-one (many clients, one server), or in some cases	one-to-many
       (multicast) relationships. With the exception of	ZMQ_PAIR, 0MQ sockets
       may be connected	to multiple endpoints using zmq_connect(), while
       simultaneously accepting	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 from multiple threads except after migrating a socket from
       one thread to another with a "full fence" memory	barrier.

       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.

   Request-reply pattern
       The request-reply pattern is used for sending requests from a ZMQ_REQ
       client to one or	more ZMQ_REP services, and receiving subsequent
       replies to each request sent.

       The request-reply pattern is formally defined by
       http://rfc.zeromq.org/spec:28.

       ZMQ_REQ
	   A socket of type ZMQ_REQ is used by a client	to send	requests to
	   and receive replies from a service. This socket type	allows only an
	   alternating sequence	of zmq_send(request) and subsequent
	   zmq_recv(reply) calls. Each request sent is round-robined among all
	   services, and each reply received is	matched	with the last issued
	   request.

	   If no services are available, then any send operation on the	socket
	   shall block until at	least one service becomes available. The REQ
	   socket shall	not discard messages.

	   Table 1. Summary of ZMQ_REQ characteristics
	   Compatible peer sockets     ZMQ_REP,	ZMQ_ROUTER

	   Direction		       Bidirectional

	   Send/receive	pattern	       Send, Receive, Send,
				       Receive,	...

	   Outgoing routing strategy   Round-robin

	   Incoming routing strategy   Last peer

	   Action in mute state	       Block

       ZMQ_REP
	   A socket of type ZMQ_REP is used by a service to receive requests
	   from	and send replies to a client. This socket type allows only an
	   alternating sequence	of zmq_recv(request) and subsequent
	   zmq_send(reply) calls. Each request received	is fair-queued from
	   among all clients, and each reply sent is routed to the client that
	   issued the last request. If the original requester does not exist
	   any more the	reply is silently discarded.

	   Table 2. Summary of ZMQ_REP characteristics
	   Compatible peer sockets     ZMQ_REQ,	ZMQ_DEALER

	   Direction		       Bidirectional

	   Send/receive	pattern	       Receive,	Send, Receive,
				       Send, ...

	   Incoming routing strategy   Fair-queued

	   Outgoing routing strategy   Last peer

       ZMQ_DEALER
	   A socket of type ZMQ_DEALER is an advanced pattern used for
	   extending request/reply sockets. Each message sent is round-robined
	   among all connected peers, and each message received	is fair-queued
	   from	all connected peers.

	   When	a ZMQ_DEALER socket enters the mute state due to having
	   reached the high water mark for all peers, or if there are no peers
	   at all, then	any zmq_send(3)	operations on the socket shall block
	   until the mute state	ends or	at least one peer becomes available
	   for sending;	messages are not discarded.

	   When	a ZMQ_DEALER socket is connected to a ZMQ_REP socket each
	   message sent	must consist of	an empty message part, the delimiter,
	   followed by one or more body	parts.

	   Table 3. Summary of ZMQ_DEALER characteristics
	   Compatible peer sockets     ZMQ_ROUTER, ZMQ_REP,
				       ZMQ_DEALER

	   Direction		       Bidirectional

	   Send/receive	pattern	       Unrestricted

	   Outgoing routing strategy   Round-robin

	   Incoming routing strategy   Fair-queued

	   Action in mute state	       Block

       ZMQ_ROUTER
	   A socket of type ZMQ_ROUTER is an advanced socket type used for
	   extending request/reply sockets. When receiving messages a
	   ZMQ_ROUTER socket shall prepend a message part containing the
	   identity of the originating peer to the message before passing it
	   to the application. Messages	received are fair-queued from among
	   all connected peers.	When sending messages a	ZMQ_ROUTER socket
	   shall remove	the first part of the message and use it to determine
	   the identity	of the peer the	message	shall be routed	to. If the
	   peer	does not exist anymore the message shall be silently discarded
	   by default, unless ZMQ_ROUTER_MANDATORY socket option is set	to 1.

	   When	a ZMQ_ROUTER socket enters the mute state due to having
	   reached the high water mark for all peers, then any messages	sent
	   to the socket shall be dropped until	the mute state ends. Likewise,
	   any messages	routed to a peer for which the individual high water
	   mark	has been reached shall also be dropped.

	   When	a ZMQ_REQ socket is connected to a ZMQ_ROUTER socket, in
	   addition to the identity of the originating peer each message
	   received shall contain an empty delimiter message part. Hence, the
	   entire structure of each received message as	seen by	the
	   application becomes:	one or more identity parts, delimiter part,
	   one or more body parts. When	sending	replies	to a ZMQ_REQ socket
	   the application must	include	the delimiter part.

	   Table 4. Summary of ZMQ_ROUTER characteristics
	   Compatible peer sockets     ZMQ_DEALER, ZMQ_REQ,
				       ZMQ_ROUTER

	   Direction		       Bidirectional

	   Send/receive	pattern	       Unrestricted

	   Outgoing routing strategy   See text

	   Incoming routing strategy   Fair-queued

	   Action in mute state	       Drop

   Publish-subscribe pattern
       The publish-subscribe pattern is	used for one-to-many distribution of
       data from a single publisher to multiple	subscribers in a fan out
       fashion.

       The publish-subscribe pattern is	formally defined by
       http://rfc.zeromq.org/spec:29.

       ZMQ_PUB
	   A socket of type ZMQ_PUB is used by a publisher to distribute data.
	   Messages sent are distributed in a fan out fashion to all connected
	   peers. The zmq_recv(3) function is not implemented for this socket
	   type.

	   When	a ZMQ_PUB 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.

	   Table 5. Summary of ZMQ_PUB characteristics
	   Compatible peer sockets     ZMQ_SUB,	ZMQ_XSUB

	   Direction		       Unidirectional

	   Send/receive	pattern	       Send only

	   Incoming routing strategy   N/A

	   Outgoing routing strategy   Fan out

	   Action in mute state	       Drop

       ZMQ_SUB
	   A socket of type ZMQ_SUB is used by a subscriber to subscribe to
	   data	distributed by a publisher. Initially a	ZMQ_SUB	socket is not
	   subscribed to any messages, use the ZMQ_SUBSCRIBE option of
	   zmq_setsockopt(3) to	specify	which messages to subscribe to.	The
	   zmq_send() function is not implemented for this socket type.

	   Table 6. Summary of ZMQ_SUB characteristics
	   Compatible peer sockets     ZMQ_PUB,	ZMQ_XPUB

	   Direction		       Unidirectional

	   Send/receive	pattern	       Receive only

	   Incoming routing strategy   Fair-queued

	   Outgoing routing strategy   N/A

       ZMQ_XPUB
	   Same	as ZMQ_PUB except that you can receive subscriptions from the
	   peers in form of incoming messages. Subscription message is a byte
	   1 (for subscriptions) or byte 0 (for	unsubscriptions) followed by
	   the subscription body. Messages without a sub/unsub prefix are also
	   received, but have no effect	on subscription	status.

	   Table 7. Summary of ZMQ_XPUB	characteristics
	   Compatible peer sockets     ZMQ_SUB,	ZMQ_XSUB

	   Direction		       Unidirectional

	   Send/receive	pattern	       Send messages, receive
				       subscriptions

	   Incoming routing strategy   N/A

	   Outgoing routing strategy   Fan out

	   Action in mute state	       Drop

       ZMQ_XSUB
	   Same	as ZMQ_SUB except that you subscribe by	sending	subscription
	   messages to the socket. Subscription	message	is a byte 1 (for
	   subscriptions) or byte 0 (for unsubscriptions) followed by the
	   subscription	body. Messages without a sub/unsub prefix may also be
	   sent, but have no effect on subscription status.

	   Table 8. Summary of ZMQ_XSUB	characteristics
	   Compatible peer sockets     ZMQ_PUB,	ZMQ_XPUB

	   Direction		       Unidirectional

	   Send/receive	pattern	       Receive messages, send
				       subscriptions

	   Incoming routing strategy   Fair-queued

	   Outgoing routing strategy   N/A

	   Action in mute state	       Drop

   Pipeline pattern
       The pipeline pattern is used for	distributing data to nodes arranged in
       a pipeline. Data	always flows down the pipeline,	and each stage of the
       pipeline	is connected to	at least one node. When	a pipeline stage is
       connected to multiple nodes data	is round-robined among all connected
       nodes.

       The pipeline pattern is formally	defined	by
       http://rfc.zeromq.org/spec:30.

       ZMQ_PUSH
	   A socket of type ZMQ_PUSH is	used by	a pipeline node	to send
	   messages to downstream pipeline nodes. Messages are round-robined
	   to all connected downstream nodes. The zmq_recv() function is not
	   implemented for this	socket type.

	   When	a ZMQ_PUSH socket enters the mute state	due to having reached
	   the high water mark for all downstream nodes, or if there are no
	   downstream nodes at all, then any zmq_send(3) operations on the
	   socket shall	block until the	mute state ends	or at least one
	   downstream node becomes available for sending; messages are not
	   discarded.

	   Table 9. Summary of ZMQ_PUSH	characteristics
	   Compatible peer sockets     ZMQ_PULL

	   Direction		       Unidirectional

	   Send/receive	pattern	       Send only

	   Incoming routing strategy   N/A

	   Outgoing routing strategy   Round-robin

	   Action in mute state	       Block

       ZMQ_PULL
	   A socket of type ZMQ_PULL is	used by	a pipeline node	to receive
	   messages from upstream pipeline nodes. Messages are fair-queued
	   from	among all connected upstream nodes. The	zmq_send() function is
	   not implemented for this socket type.

	   Table 10. Summary of	ZMQ_PULL characteristics
	   Compatible peer sockets     ZMQ_PUSH

	   Direction		       Unidirectional

	   Send/receive	pattern	       Receive only

	   Incoming routing strategy   Fair-queued

	   Outgoing routing strategy   N/A

	   Action in mute state	       Block

   Exclusive pair pattern
       The exclusive pair pattern is used to connect a peer to precisely one
       other peer. This	pattern	is used	for inter-thread communication across
       the inproc transport.

       The exclusive pair pattern is formally defined by
       http://rfc.zeromq.org/spec:31.

       ZMQ_PAIR
	   A socket of type ZMQ_PAIR can only be connected to a	single peer at
	   any one time. No message routing or filtering is performed on
	   messages sent over a	ZMQ_PAIR socket.

	   When	a ZMQ_PAIR socket enters the mute state	due to having reached
	   the high water mark for the connected peer, or if no	peer is
	   connected, then any zmq_send(3) operations on the socket shall
	   block until the peer	becomes	available for sending; messages	are
	   not discarded.

	       Note
	       ZMQ_PAIR	sockets	are designed for inter-thread communication
	       across the zmq_inproc(7)	transport and do not implement
	       functionality such as auto-reconnection.	ZMQ_PAIR sockets are
	       considered experimental and may have other missing or broken
	       aspects.

	   Table 11. Summary of	ZMQ_PAIR characteristics
	   Compatible peer sockets     ZMQ_PAIR

	   Direction		       Bidirectional

	   Send/receive	pattern	       Unrestricted

	   Incoming routing strategy   N/A

	   Outgoing routing strategy   N/A

	   Action in mute state	       Block

   Native Pattern
       The native pattern is used for communicating with TCP peers and allows
       asynchronous requests and replies in either direction.

       ZMQ_STREAM
	   A socket of type ZMQ_STREAM is used to send and receive TCP data
	   from	a non-0MQ peer,	when using the tcp:// transport. A ZMQ_STREAM
	   socket can act as client and/or server, sending and/or receiving
	   TCP data asynchronously.

	   When	receiving TCP data, a ZMQ_STREAM socket	shall prepend a
	   message part	containing the identity	of the originating peer	to the
	   message before passing it to	the application. Messages received are
	   fair-queued from among all connected	peers.

	   When	sending	TCP data, a ZMQ_STREAM socket shall remove the first
	   part	of the message and use it to determine the identity of the
	   peer	the message shall be routed to,	and unroutable messages	shall
	   cause an EHOSTUNREACH or EAGAIN error.

	   To open a connection	to a server, use the zmq_connect call, and
	   then	fetch the socket identity using	the ZMQ_IDENTITY
	   zmq_getsockopt call.

	   To close a specific connection, send	the identity frame followed by
	   a zero-length message (see EXAMPLE section).

	   When	a connection is	made, a	zero-length message will be received
	   by the application. Similarly, when the peer	disconnects (or	the
	   connection is lost),	a zero-length message will be received by the
	   application.

	   The ZMQ_SNDMORE flag	is ignored on data frames. You must send one
	   identity frame followed by one data frame.

	   Also, please	note that omitting the ZMQ_SNDMORE flag	will prevent
	   sending further data	(from any client) on the same socket.

	   Table 12. Summary of	ZMQ_STREAM characteristics
	   Compatible peer sockets     none.

	   Direction		       Bidirectional

	   Send/receive	pattern	       Unrestricted

	   Outgoing routing strategy   See text

	   Incoming routing strategy   Fair-queued

	   Action in mute state	       EAGAIN

RETURN VALUE
       The zmq_socket()	function shall return an opaque	handle to the newly
       created socket if successful. Otherwise,	it shall return	NULL and set
       errno to	one of the values defined below.

ERRORS
       EINVAL
	   The requested socket	type is	invalid.

       EFAULT
	   The provided	context	is invalid.

       EMFILE
	   The limit on	the total number of open 0MQ sockets has been reached.

       ETERM
	   The context specified was terminated.

EXAMPLE
       Creating	a simple HTTP server using ZMQ_STREAM.

	   void	*ctx = zmq_ctx_new ();
	   assert (ctx);
	   /* Create ZMQ_STREAM	socket */
	   void	*socket	= zmq_socket (ctx, ZMQ_STREAM);
	   assert (socket);
	   int rc = zmq_bind (socket, "tcp://*:8080");
	   assert (rc == 0);
	   /* Data structure to	hold the ZMQ_STREAM ID */
	   uint8_t id [256];
	   size_t id_size = 256;
	   /* Data structure to	hold the ZMQ_STREAM received data */
	   uint8_t raw [256];
	   size_t raw_size = 256;
	   while (1) {
		   /*  Get HTTP	request; ID frame and then request */
		   id_size = zmq_recv (socket, id, 256,	0);
		   assert (id_size > 0);
		   do {
			   raw_size = zmq_recv (socket,	raw, 256, 0);
			   assert (raw_size >= 0);
		   } while (raw_size ==	256);
		   /* Prepares the response */
		   char	http_response [] =
			   "HTTP/1.0 200 OK\r\n"
			   "Content-Type: text/plain\r\n"
			   "\r\n"
			   "Hello, World!";
		   /* Sends the	ID frame followed by the response */
		   zmq_send (socket, id, id_size, ZMQ_SNDMORE);
		   zmq_send (socket, http_response, strlen (http_response), ZMQ_SNDMORE);
		   /* Closes the connection by sending the ID frame followed by	a zero response	*/
		   zmq_send (socket, id, id_size, ZMQ_SNDMORE);
		   zmq_send (socket, 0,	0, ZMQ_SNDMORE);
		   /* NOTE: If we don't	use ZMQ_SNDMORE, then we won't be able to send more */
		   /* message to any client */
	   }
	   zmq_close (socket);
	   zmq_ctx_destroy (ctx);

SEE ALSO
       zmq_init(3) zmq_setsockopt(3) zmq_bind(3) zmq_connect(3)	zmq_send(3)
       zmq_recv(3) zmq_inproc(7) 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.

0MQ 4.1.5			  07/02/2017			 ZMQ_SOCKET(3)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLE | SEE ALSO | AUTHORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=zmq_socket&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help