libzmq/doc/zmq_socket.txt

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 _messaging patterns_ are defined:


Peer to peer pattern
~~~~~~~~~~~~~~~~~~~~
The simplest messaging pattern, used for communicating between two peers.

Socket type:: 'ZMQ_P2P'
Compatible peer sockets:: 'ZMQ_P2P'

A socket of type 'ZMQ_P2P' 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_P2P' socket.


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.


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.


Parallelized pipeline pattern
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The parallelized pipeline pattern is used for distributing work between
_components_ of a pipeline. Work travels down the pipeline and at each stage
can be processed by any number of _components_ in parallel.

Socket type:: 'ZMQ_UPSTREAM'
Compatible peer sockets:: 'ZMQ_DOWNSTREAM'

A socket of type 'ZMQ_UPSTREAM' is used by a _component_ of a pipeline to
receive messages from upstream stages of the pipeline. Messages are fair-queued
from among all connected upstream _components_. The _zmq_send()_ function is
not implemented for this socket type.

Socket type:: 'ZMQ_DOWNSTREAM'
Compatible peer sockets:: 'ZMQ_UPSTREAM'

A socket of type 'ZMQ_DOWNSTREAM' is used by a _component_ of a pipeline to
send messages to downstream stages of the pipeline. Messages are load-balanced
to all connected downstream _components_. The _zmq_recv()_ function is not
implemented for this socket type.


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>.