Qore zmq Module  1.0.0
Qore::ZMQ::ZSocketRouter Class Reference

The ZSocketRouter class implements a ZeroMQ ROUTER socket. More...

Inheritance diagram for Qore::ZMQ::ZSocketRouter:
Qore::Qore::ZMQ::ZSocket

Public Member Methods

 constructor (Qore::ZMQ::ZContext ctx, *string identity, string endpoint)
 constructs a ROUTER zsocket with an explicit identity and endpoint More...
 
 constructor (Qore::ZMQ::ZContext ctx)
 constructs an unconnected ROUTER zsocket with a default system-assigned identity More...
 
 setMandatory (softbool mandatory)
 sets the ZMQ_ROUTER_MANDATORY option on the socket More...
 
- Public Member Methods inherited from Qore::Qore::ZMQ::ZSocket
nothing attach (*string endpoints, bool do_bind=False)
 Attaches the socket to zero or more endpoints. More...
 
int bind (string format,...)
 Bind the ZSocket to a formatted endpoint. More...
 
nothing connect (string format,...)
 Connects the socket to a formatted endpoint. More...
 
 copy ()
 Throws an exception; copying ZSocket objects is not currently supported. More...
 
nothing disconnect (string format,...)
 Disconnects the socket from a formatted endpoint. More...
 
*string endpoint ()
 Returns the last bound endpoint, if any or nothing if not. More...
 
*string getIdentity ()
 retrieves the socket identity string More...
 
auto getOption (int opt, int bufsize=100)
 Retrieves the value of the given socket option. More...
 
nothing monitor (int events, string format,...)
 Creates a bound PAIR socket on the given endpoint which will send the specified events to a single client. More...
 
ZFrame recvFrame ()
 Receives a frame from the socket. More...
 
ZMsg recvMsg ()
 Receives a message from the socket. More...
 
nothing send (Qore::ZMQ::ZMsg msg)
 Sends the given message over the socket; the message is consumed by this call. More...
 
nothing send (Qore::ZMQ::ZFrame frame, int flags=0)
 Sends the given frame over the socket; the frame is consumed by this call unless Qore::ZMQ::ZFRAME_REUSE is used in the flags argument. More...
 
nothing send (data val,...)
 Sends one or more strings or binary data objects over the socket. More...
 
nothing send ()
 Sends a zero-length message over the socket. More...
 
nothing setIdentity (string id)
 Sets the socket identity string. More...
 
 setOption (int opt, int value)
 Sets the given socket option to the given value. More...
 
 setOption (int opt, bool value)
 Sets the given socket option to the given value. More...
 
 setOption (int opt, data value)
 Sets the given socket option to the given value. More...
 
nothing setRecvHighWaterMark (int value)
 Sets the receive high water mark. More...
 
nothing setRecvTimeout (timeout timeout_ms)
 Sets the receive timeout in milliseconds. More...
 
nothing setSendTimeout (timeout timeout_ms)
 Sets the send timeout in milliseconds. More...
 
nothing setTimeout (timeout timeout_ms)
 Sets the send and receive timeout in milliseconds. More...
 
string type ()
 Returns the socket type as a string. More...
 
nothing unbind (string format,...)
 Unbinds the socket from a formatted endpoint. More...
 
nothing waitRead (timeout timeout_ms)
 Waits for data to read on the socket; if data does not arrive before the timeout expires, a ZSOCKET-TIMEOUT-ERROR exception is thrown. More...
 
nothing waitWrite (timeout timeout_ms)
 Waits for data to be written on the socket; if data is not sent before the timeout expires, a ZSOCKET-TIMEOUT-ERROR exception is thrown. More...
 

Additional Inherited Members

- Static Public Member Methods inherited from Qore::Qore::ZMQ::ZSocket
static list< hash< ZmqPollInfo > > poll (list< hash< ZmqPollInfo >> items, timeout timeout_ms)
 polls multiple sockets and returns all sockets with events More...
 
static nothing proxy (ZSocket frontend, ZSocket backend, *ZSocket capture)
 starts the built-in ZeroMQ proxy to connect messages between two sockets More...
 

Detailed Description

The ZSocketRouter class implements a ZeroMQ ROUTER socket.

Restrictions:
Qore::PO_NO_NETWORK
Overview
A socket of type ROUTER is an advanced socket type used for extending request/reply sockets. When receiving messages a ROUTER socket shall prepend a message part containing the identity of the originating peer to the message before passing it to the application. Messages received are fair-queued from among all connected peers. When sending messages a ROUTER socket shall remove the first part of the message and use it to determine the identity of the peer the message shall be routed to. If the peer does not exist anymore the message shall be silently discarded by default, unless ZSocketRouter::setMandatory() is set to True.

When a ROUTER socket enters the mute state due to having reached the high water mark for all peers, then any messages sent to the socket shall be dropped until the mute state ends. Likewise, any messages routed to a peer for which the individual high water mark has been reached shall also be dropped, unless ZSocketRouter::setMandatory() is set to True.

When a REQ socket is connected to a ROUTER socket, in addition to the identity of the originating peer each message received shall contain an empty delimiter message part. Hence, the entire structure of each received message as seen by the application becomes:
  • one or more identity parts
  • delimiter part
  • one or more body parts
When sending replies to a REQ socket, the application must include the delimiter part.

Summary of ROUTER characteristics
Property Value
Compatible peer sockets DEALER, REQ, ROUTER
Direction Bidirectional
Send/receive pattern Unrestricted
Outgoing routing strategy See text
Incoming routing strategy Fair-queued
Action in mute state Drop (see text)
Note
  • This class is not designed to be accessed from multiple threads; it was created without locking for fast and efficient use when used from a single thread. For methods that would be unsafe to use in another thread, any use of such methods in threads other than the thread where the constructor was called will cause a ZSOCKET-THREAD-ERROR to be thrown.
  • It is recommended to use an identity with ROUTER sockets

Member Function Documentation

◆ constructor() [1/2]

Qore::ZMQ::ZSocketRouter::constructor ( Qore::ZMQ::ZContext  ctx,
*string  identity,
string  endpoint 
)

constructs a ROUTER zsocket with an explicit identity and endpoint

Example
ZSocketRouter sock(ctx, "my-identity", "tcp://127.0.0.1:8001");
Parameters
ctxthe context for the socket
identitythe identity value for the socket; a missing or empty value here results in the default identity being assigned
endpointthe endpoint for the socket; the default action is bind
Exceptions
ZSOCKET-CONSTRUCTOR-ERRORthis exception is thrown if there is any error creating the socket
ZSOCKET-BIND-ERRORthis exception is thrown if there is any error connecting the socket
Note
It is recommended to use an identity with ROUTER sockets

◆ constructor() [2/2]

Qore::ZMQ::ZSocketRouter::constructor ( Qore::ZMQ::ZContext  ctx)

constructs an unconnected ROUTER zsocket with a default system-assigned identity

Example
# create an unconnected ROUTER socket
ZSocketRouter router(zctx);
# set the router's identity value explicitly before binding
router.setIdentity(RouterIdentity);
port = router.bind("tcp://127.0.0.1:*");
Parameters
ctxthe context for the socket
Exceptions
ZSOCKET-CONSTRUCTOR-ERRORthis exception is thrown if there is any error creating the socket
Note
It is recommended to use an identity with ROUTER sockets

◆ setMandatory()

Qore::ZMQ::ZSocketRouter::setMandatory ( softbool  mandatory)

sets the ZMQ_ROUTER_MANDATORY option on the socket

Example
router.setMandatory(True);
Parameters
mandatorythe mandatory option for the socket
Exceptions
ZSOCKET-SETMANDATORY-ERRORthis exception is thrown if there is any error setting the socket option
ZSOCKET-CONTEXT-ERRORthe context is no longer valid
See also
ZMQ_ROUTER_MANDATORY

The documentation for this class was generated from the following file: