mirror of
https://github.com/zeromq/libzmq.git
synced 2024-12-14 11:06:59 +01:00
143 lines
4.5 KiB
Plaintext
143 lines
4.5 KiB
Plaintext
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 following sections present the socket types defined by 0MQ, grouped by the
|
|
general _messaging pattern_ built from related socket types.
|
|
|
|
|
|
Request-reply pattern
|
|
~~~~~~~~~~~~~~~~~~~~~
|
|
The request-reply pattern is used for sending requests from a _client_ to a
|
|
_service_, and receiving subsequent replies to each request sent.
|
|
|
|
Socket type:: 'ZMQ_REQ'
|
|
Compatible peer sockets:: 'ZMQ_REP'
|
|
|
|
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 connected _services_.
|
|
|
|
Socket type:: 'ZMQ_REP'
|
|
Compatible peer sockets:: 'ZMQ_REQ'
|
|
|
|
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
|
|
reply is routed to the _client_ that issued the last received request.
|
|
|
|
|
|
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.
|
|
|
|
Socket type:: 'ZMQ_PUB'
|
|
Compatible peer sockets:: 'ZMQ_SUB'
|
|
|
|
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 _zmq_recv()_ function is not implemented for this socket type.
|
|
|
|
Socket type:: 'ZMQ_SUB'
|
|
Compatible peer sockets:: 'ZMQ_PUB'
|
|
|
|
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()_ to specify
|
|
which messages to subscribe to. The _zmq_send()_ function is not implemented
|
|
for this socket type.
|
|
|
|
|
|
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 processed by all connected _nodes_ in
|
|
parallel.
|
|
|
|
Socket type:: 'ZMQ_DOWNSTREAM'
|
|
Compatible peer sockets:: 'ZMQ_UPSTREAM'
|
|
|
|
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.
|
|
|
|
Socket type:: 'ZMQ_UPSTREAM'
|
|
Compatible peer sockets:: 'ZMQ_DOWNSTREAM'
|
|
|
|
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.
|
|
|
|
|
|
Exclusive pair pattern
|
|
~~~~~~~~~~~~~~~~~~~~~~
|
|
The exclusive pair pattern is used for communicating exclusively between two
|
|
peers.
|
|
|
|
Socket type:: 'ZMQ_PAIR'
|
|
Compatible peer sockets:: '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.
|
|
|
|
NOTE: 'ZMQ_PAIR' sockets are experimental, and are currently missing several
|
|
features such as auto-reconnection. Developers should consider other patterns
|
|
in preference to the exclusive pair pattern.
|
|
|
|
|
|
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.
|
|
|
|
*EMTHREAD*::
|
|
The number of application threads using sockets within this 'context' has been
|
|
exceeded. See the 'app_threads' parameter of the _zmq_init()_ function.
|
|
|
|
|
|
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]
|
|
|
|
|
|
AUTHORS
|
|
-------
|
|
The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
|
|
Martin Lucina <mato@kotelna.sk>.
|