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 _messaging pattern_, 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. 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_flush[3]
linkzmq:zmq_recv[3]


AUTHORS
-------
The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
Martin Lucina <mato@kotelna.sk>.