libzmq/doc/zmq_socket.txt

261 lines
8.9 KiB
Plaintext
Raw Normal View History

2010-02-10 16:18:46 +01:00
zmq_socket(3)
=============
NAME
----
2010-03-09 18:47:31 +01:00
zmq_socket - create 0MQ socket
2010-02-10 16:18:46 +01:00
SYNOPSIS
--------
2010-03-09 18:47:31 +01:00
*void *zmq_socket (void '*context', int 'type');*
2010-02-10 16:18:46 +01:00
DESCRIPTION
-----------
2010-03-09 18:47:31 +01:00
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'
2010-03-10 12:19:39 +01:00
argument specifies the socket type, which determines the semantics of
2010-03-09 18:47:31 +01:00
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 linkzmq:zmq_connect[3], or at least one
endpoint must be created for accepting incoming connections with
linkzmq: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 teardown, 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.
.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 _client_ to one
or more instances of a _service_, and receiving subsequent replies to each
request sent.
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 load-balanced among all _services_, and each reply received is
matched with the last issued request.
When a 'ZMQ_REQ' socket enters an exceptional state due to having reached the
high water mark for all _services_, or if there are no _services_ at all, then
any linkzmq:zmq_send[3] operations on the socket shall block until the
exceptional state ends or at least one _service_ becomes available for sending;
messages are not discarded.
[horizontal]
.Summary of ZMQ_REQ characteristics
Compatible peer sockets:: 'ZMQ_REP'
Direction:: Bidirectional
Send/receive pattern:: Send, Receive, Send, Receive, ...
Outgoing routing strategy:: Load-balanced
Incoming routing strategy:: Last peer
ZMQ_HWM option action:: 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.
When a 'ZMQ_REP' socket enters an exceptional state due to having reached the
high water mark for a _client_, then any replies sent to the _client_ in
question shall be dropped until the exceptional state ends.
[horizontal]
.Summary of ZMQ_REP characteristics
Compatible peer sockets:: 'ZMQ_REQ'
Direction:: Bidirectional
Send/receive pattern:: Receive, Send, Receive, Send, ...
Incoming routing strategy:: Fair-queued
Outgoing routing stratagy:: Last peer
ZMQ_HWM option action:: Drop
2010-03-09 18:47:31 +01:00
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 fanout fashion.
ZMQ_PUB
^^^^^^^
2010-03-09 18:47:31 +01:00
A socket of type 'ZMQ_PUB' is used by a _publisher_ to distribute data.
Messages sent are distributed in a fanout fashion to all connected peers.
The linkzmq:zmq_recv[3] function is not implemented for this socket type.
2010-03-09 18:47:31 +01:00
When a 'ZMQ_PUB' socket enters an exceptional 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 exceptional state
ends.
2010-03-09 18:47:31 +01:00
[horizontal]
.Summary of ZMQ_PUB characteristics
Compatible peer sockets:: 'ZMQ_SUB'
Direction:: Unidirectional
Send/receive pattern:: Send only
Incoming routing strategy:: N/A
Outgoing routing strategy:: Fanout
ZMQ_HWM option action:: Drop
ZMQ_SUB
^^^^^^^
2010-03-09 18:47:31 +01:00
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 linkzmq:zmq_setsockopt[3] to
specify which messages to subscribe to. The _zmq_send()_ function is not
implemented for this socket type.
[horizontal]
.Summary of ZMQ_SUB characteristics
Compatible peer sockets:: 'ZMQ_PUB'
Direction:: Unidirectional
Send/receive pattern:: Receive only
Incoming routing strategy:: Fair-queued
Outgoing routing strategy:: N/A
ZMQ_HWM option action:: N/A
2010-03-09 18:47:31 +01:00
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 load-balanced among all connected _nodes_.
2010-03-09 18:47:31 +01:00
ZMQ_DOWNSTREAM
^^^^^^^^^^^^^^
A socket of type 'ZMQ_DOWNSTREAM' is used by a pipeline _node_ to send messages
to downstream pipeline _nodes_. Messages are load-balanced to all connected
downstream _nodes_. The _zmq_recv()_ function is not implemented for this
socket type.
2010-03-09 18:47:31 +01:00
When a 'ZMQ_DOWNSTREAM' socket enters an exceptional state due to having
reached the high water mark for all downstream _nodes_, or if there are no
downstream _nodes_ at all, then any linkzmq:zmq_send[3] operations on the
socket shall block until the exceptional state ends or at least one downstream
_node_ becomes available for sending; messages are not discarded.
[horizontal]
.Summary of ZMQ_DOWNSTREAM characteristics
Compatible peer sockets:: 'ZMQ_UPSTREAM'
Direction:: Unidirectional
Send/receive pattern:: Send only
Incoming routing strategy:: N/A
Outgoing routing strategy:: Load-balanced
ZMQ_HWM option action:: Block
2010-03-09 18:47:31 +01:00
ZMQ_UPSTREAM
^^^^^^^^^^^^
A socket of type 'ZMQ_UPSTREAM' 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.
2010-03-09 18:47:31 +01:00
[horizontal]
.Summary of ZMQ_UPSTREAM characteristics
Compatible peer sockets:: 'ZMQ_DOWNSTREAM'
Direction:: Unidirectional
Send/receive pattern:: Receive only
Incoming routing strategy:: Fair-queued
Outgoing routing strategy:: N/A
ZMQ_HWM option action:: N/A
2010-03-09 18:47:31 +01:00
Exclusive pair pattern
~~~~~~~~~~~~~~~~~~~~~~
The exclusive pair is an advanced pattern used for communicating exclusively
between two peers.
2010-03-09 18:47:31 +01:00
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.
2010-03-09 18:47:31 +01:00
When a 'ZMQ_PAIR' socket enters an exceptional state due to having reached the
high water mark for the connected peer, or if no peer is connected, then
any linkzmq: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 experimental, and are currently missing several
features such as auto-reconnection.
2010-02-10 16:18:46 +01:00
[horizontal]
.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
ZMQ_HWM option action:: Block
2010-02-10 16:18:46 +01:00
RETURN VALUE
------------
2010-03-09 18:47:31 +01:00
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.
2010-02-10 16:18:46 +01:00
ERRORS
------
*EINVAL*::
2010-03-09 18:47:31 +01:00
The requested socket 'type' is invalid.
2010-02-10 16:18:46 +01:00
*EMTHREAD*::
The maximum number of sockets within this 'context' has been exceeded.
2010-02-10 16:18:46 +01:00
SEE ALSO
--------
linkzmq:zmq_init[3]
linkzmq:zmq_setsockopt[3]
linkzmq:zmq_bind[3]
linkzmq:zmq_connect[3]
linkzmq:zmq_send[3]
linkzmq:zmq_recv[3]
linkzmq:zmq[7]
2010-02-10 16:18:46 +01:00
2010-03-09 18:47:31 +01:00
AUTHORS
-------
The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
Martin Lucina <mato@kotelna.sk>.