| Class | ZMQ::Socket |
| In: |
rbzmq.c
|
| Parent: | Object |
ZeroMQ message socket.
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 connect(), while simultaneously accepting incoming connections from multiple endpoints bound to the socket using bind(), thus allowing many-to-many relationships.
The following sections present the socket types defined by 0MQ, grouped by the general messaging pattern which is built from related socket types.
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.
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 send(request) and subsequent 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 send() operations on the socket shall block until the exceptional state ends or at least one service becomes available for sending; messages are not discarded.
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 recv(request) and subsequent 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.
The publish-subscribe pattern is used for one-to-many distribution of data from a single publisher to multiple subscribers in a fanout fashion.
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 recv() function is not implemented for this socket type.
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.
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 setsockopt() to specify which messages to subscribe to. The send() function is not implemented for this socket type.
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.
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.
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 send() 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.
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 send() function is not implemented for this socket type.
The exclusive pair is an advanced pattern used for communicating exclusively between two peers.
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 an exceptional state due to having reached the high water mark for the connected peer, or if no peer is connected, then any send() 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.
Creates an endpoint for accepting connections and binds it to the socket.
The endpoint argument is a string consisting of two parts as follows: _transport://address_. The transport part specifies the underlying transport protocol to use. The meaning of the address part is specific to the underlying transport protocol selected.
The following transports are defined:
With the exception of ZMQ:PAIR sockets, a single socket may be connected to multiple endpoints using connect(), while simultaneously accepting incoming connections from multiple endpoints bound to the socket using bind(). Refer to ZMQ::Socket for a description of the exact semantics involved when connecting or binding a socket to multiple endpoints.
Destroys the 0MQ socket. All active connections on the socket shall be terminated, and resources associated with the socket shall be released. Any outstanding messages sent with send() but not yet physically sent to the network shall be dropped. Likewise, any outstanding messages physically received from the network but not yet received by the application with recv() shall also be dropped.
Connects the socket to the endpoint specified by the endpoint argument.
The endpoint argument is a string consisting of two parts as follows: _transport://address_. The transport part specifies the underlying transport protocol to use. The meaning of the address part is specific to the underlying transport protocol selected.
The following transports are defined:
With the exception of ZMQ:PAIR sockets, a single socket may be connected to multiple endpoints using connect(), while simultaneously accepting incoming connections from multiple endpoints bound to the socket using bind(). Refer to ZMQ::Socket for a description of the exact semantics involved when connecting or binding a socket to multiple endpoints.
NOTE: The connection will not be performed immediately, but as needed by 0MQ. Thus, a successful invocation of connect() does not indicate that a physical connection was or can actually be established.
Retrieves the value of the specified 0MQ socket option.
The following options can be retrievesd with the getsockopt() function:
The ZMQ::RCVMORE option shall return a boolean value indicating if the multi-part message currently being read from the specified socket has more message parts to follow. If there are no message parts to follow or if the message currently being read is not a multi-part message a value of false shall be returned. Otherwise, a value of true shall be returned.
Refer to send() and recv() for a detailed description of sending/receiving multi-part messages.
The ZMQ::HWM option shall retrieve the high water mark for the specified socket. The high water mark is a hard limit on the maximum number of outstanding messages 0MQ shall queue in memory for any single peer that the specified socket is communicating with.
If this limit has been reached the socket shall enter an exceptional state and depending on the socket type, 0MQ shall take appropriate action such as blocking or dropping sent messages. Refer to the individual socket descriptions in ZMQ::Socket for details on the exact action taken for each socket type.
The default ZMQ::HWM value of zero means “no limit”.
The ZMQ::SWAP option shall retrieve the disk offload (swap) size for the specified socket. A socket which has ZMQ::SWAP set to a non-zero value may exceed it’s high water mark; in this case outstanding messages shall be offloaded to storage on disk rather than held in memory.
The value of ZMQ::SWAP defines the maximum size of the swap space in bytes.
The ZMQ::AFFINITY option shall retrieve the I/O thread affinity for newly created connections on the specified socket.
Affinity determines which threads from the 0MQ I/O thread pool associated with the socket’s context shall handle newly created connections. A value of zero specifies no affinity, meaning that work shall be distributed fairly among all 0MQ I/O threads in the thread pool. For non-zero values, the lowest bit corresponds to thread 1, second lowest bit to thread 2 and so on. For example, a value of 3 specifies that subsequent connections on socket shall be handled exclusively by I/O threads 1 and 2.
See also ZMQ::Context#new for details on allocating the number of I/O threads for a specific context.
The ZMQ::IDENTITY option shall retrieve the identity of the specified socket. Socket identity determines if existing 0MQ infastructure (message queues, forwarding devices) shall be identified with a specific application and persist across multiple runs of the application.
If the socket has no identity, each run of an application is completely separate from other runs. However, with identity set the socket shall re-use any existing 0MQ infrastructure configured by the previous run(s). Thus the application may receive messages that were sent in the meantime, message queue limits shall be shared with previous run(s) and so on.
Identity can be at least one byte and at most 255 bytes long. Identities starting with binary zero are reserved for use by 0MQ infrastructure.
The ZMQ::Rate option shall retrieve the maximum send or receive data rate for multicast transports using the specified socket.
The ZMQ::RECOVERY_IVL option shall retrieve the recovery interval for multicast transports using the specified socket. The recovery interval determines the maximum time in seconds that a receiver can be absent from a multicast group before unrecoverable data loss will occur.
The ZMQ::MCAST_LOOP option controls whether data sent via multicast transports can also be received by the sending host via loopback. A value of zero indicates that the loopback functionality is disabled, while the default value of 1 indicates that the loopback functionality is enabled. Leaving multicast loopback enabled when it is not required can have a negative impact on performance. Where possible, disable ZMQ::MCAST_LOOP in production environments.
The ZMQ::SNDBUF option shall retrieve the underlying kernel transmit buffer size for the specified socket. A value of zero means that the OS default is in effect. For details refer to your operating system documentation for the SO_SNDBUF socket option.
The ZMQ::RCVBUF option shall retrieve the underlying kernel receive buffer size for the specified socket. A value of zero means that the OS default is in effect. For details refer to your operating system documentation for the SO_RCVBUF socket option.
Receives a message from the socket. If there are no messages available on the socket, the recv() function shall block until the request can be satisfied. The flags argument is a combination of the flags defined below:
A 0MQ message is composed of 1 or more message parts. 0MQ ensures atomic delivery of messages; peers shall receive either all message parts of a message or none at all.
The total number of message parts is unlimited.
An application wishing to determine if a message is composed of multiple parts does so by retrieving the value of the ZMQ::RCVMORE socket option on the socket it is receiving the message from, using getsockopt(). If there are no message parts to follow, or if the message is not composed of multiple parts, ZMQ::RCVMORE shall report a value of false. Otherwise, ZMQ::RCVMORE shall report a value of true, indicating that more message parts are to follow.
Queue the message referenced by the msg argument to be send to the socket. The flags argument is a combination of the flags defined below:
NOTE: A successful invocation of send() does not indicate that the message has been transmitted to the network, only that it has been queued on the socket and 0MQ has assumed responsibility for the message.
A 0MQ message is composed of 1 or more message parts. 0MQ ensures atomic delivery of messages; peers shall receive either all message parts of a message or none at all.
The total number of message parts is unlimited.
An application wishing to send a multi-part message does so by specifying the ZMQ::SNDMORE flag to send(). The presence of this flag indicates to 0MQ that the message being sent is a multi-part message and that more message parts are to follow. When the application wishes to send the final message part it does so by calling send() without the ZMQ::SNDMORE flag; this indicates that no more message parts are to follow.
This function returns true if successful, false if not.
Sets the value of a 0MQ socket option.
The following socket options can be set with the setsockopt() function:
The ZMQ::HWM option shall set the high water mark for the specified socket. The high water mark is a hard limit on the maximum number of outstanding messages 0MQ shall queue in memory for any single peer that the specified socket is communicating with.
If this limit has been reached the socket shall enter an exceptional state and depending on the socket type, 0MQ shall take appropriate action such as blocking or dropping sent messages. Refer to the individual socket descriptions in ZMQ::Socket for details on the exact action taken for each socket type.
The default ZMQ::HWM value of zero means “no limit”.
The ZMQ::SWAP option shall set the disk offload (swap) size for the specified socket. A socket which has ZMQ::SWAP set to a non-zero value may exceed it’s high water mark; in this case outstanding messages shall be offloaded to storage on disk rather than held in memory.
The value of ZMQ::SWAP defines the maximum size of the swap space in bytes.
The ZMQ::AFFINITY option shall set the I/O thread affinity for newly created connections on the specified socket.
Affinity determines which threads from the 0MQ I/O thread pool associated with the socket’s context shall handle newly created connections. A value of zero specifies no affinity, meaning that work shall be distributed fairly among all 0MQ I/O threads in the thread pool. For non-zero values, the lowest bit corresponds to thread 1, second lowest bit to thread 2 and so on. For example, a value of 3 specifies that subsequent connections on socket shall be handled exclusively by I/O threads 1 and 2.
See also ZMQ::Context#new for details on allocating the number of I/O threads for a specific context.
The ZMQ::IDENTITY option shall set the identity of the specified socket. Socket identity determines if existing 0MQ infastructure (message queues, forwarding devices) shall be identified with a specific application and persist across multiple runs of the application.
If the socket has no identity, each run of an application is completely separate from other runs. However, with identity set the socket shall re-use any existing 0MQ infrastructure configured by the previous run(s). Thus the application may receive messages that were sent in the meantime, message queue limits shall be shared with previous run(s) and so on.
Identity should be at least one byte and at most 255 bytes long. Identities starting with binary zero are reserved for use by 0MQ infrastructure.
ZMQ::SUBSCRIBE: Establish message filter The ZMQ::SUBSCRIBE option shall establish a new message filter on a ZMQ::SUB socket. Newly created ZMQ::SUB sockets shall filter out all incoming messages, therefore you should call this option to establish an initial message filter.
An empty value of length zero shall subscribe to all incoming messages. A non-empty value shall subscribe to all messages beginning with the specified prefix. Mutiple filters may be attached to a single ZMQ::SUB socket, in which case a message shall be accepted if it matches at least one filter.
The ZMQ::UNSUBSCRIBE option shall remove an existing message filter on a ZMQ::SUB socket. The filter specified must match an existing filter previously established with the ZMQ::SUBSCRIBE option. If the socket has several instances of the same filter attached the ZMQ::UNSUBSCRIBE option shall remove only one instance, leaving the rest in place and functional.
The ZMQ::RATE option shall set the maximum send or receive data rate for multicast transports such as pgm using the specified socket.
The ZMQ::RECOVERY_IVL option shall set the recovery interval for multicast transports using the specified socket. The recovery interval determines the maximum time in seconds that a receiver can be absent from a multicast group before unrecoverable data loss will occur.
Caution: Exercise care when setting large recovery intervals as the data needed for recovery will be held in memory. For example, a 1 minute recovery interval at a data rate of 1Gbps requires a 7GB in-memory buffer.
The ZMQ::MCAST_LOOP option shall control whether data sent via multicast transports using the specified socket can also be received by the sending host via loopback. A value of zero disables the loopback functionality, while the default value of 1 enables the loopback functionality. Leaving multicast loopback enabled when it is not required can have a negative impact on performance. Where possible, disable ZMQ::MCAST_LOOP in production environments.
The ZMQ::SNDBUF option shall set the underlying kernel transmit buffer size for the socket to the specified size in bytes. A value of zero means leave the OS default unchanged. For details please refer to your operating system documentation for the SO_SNDBUF socket option.
The ZMQ::RCVBUF option shall set the underlying kernel receive buffer size for the socket to the specified size in bytes. A value of zero means leave the OS default unchanged. For details refer to your operating system documentation for the SO_RCVBUF socket option.