The ZSocketSub class implements a ZeroMQ SUB socket. More...

Inheritance diagram for Qore::ZMQ::ZSocketSub:

Public Member Methods
	constructor (Qore::ZMQ::ZContext ctx, string endpoint, string subscribe)
	constructs a `SUB` zsocket More...

	constructor (Qore::ZMQ::ZContext ctx)
	constructs an unconnected `SUB` zsocket More...

nothing	subscribe (*string subs)
	Adds a subscription to the socket. More...

nothing	unsubscribe (*string subs)
	Removes a subscription from the socket. More...

Public Member Methods inherited from 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::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 ZSocketSub class implements a ZeroMQ SUB socket.

Restrictions:: Qore::PO_NO_NETWORK

Overview

A socket of type SUB is used by a subscriber to subscribe to data distributed by a publisher. Initially a SUB socket is not subscribed to any messages, use the ZSocketSub::subscribe() method to specify which messages to subscribe to. The ZSocket::send() method is not implemented for this socket type.

Summary of SUB characteristics

Property	Value
Compatible peer sockets	PUB, XPUB
Direction	Unidirectional
Send/receive pattern	Receive only
Incoming routing strategy	Fair-queued
Outgoing routing strategy	N/A

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.

Member Function Documentation

◆ constructor() [1/2]

Qore::ZMQ::ZSocketSub::constructor	(	Qore::ZMQ::ZContext	ctx,
		string	endpoint,
		string	subscribe
	)

constructs a SUB zsocket

Example: ZSocketSub sock(ctx, "tcp://127.0.0.1:8001", str);

Parameters

ctx	the context for the socket
endpoint	the endpoint for the socket; the default action is connect
subscribe	the subscription to set; set immediately after the socket is connected

Exceptions

ZSOCKET-CONSTRUCTOR-ERROR	this exception is thrown if there is any error creating the socket
ZSOCKET-CONNECT-ERROR	this exception is thrown if there is any error connecting the socket

◆ constructor() [2/2]

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

constructs an unconnected SUB zsocket

Example: ZSocketSub sock(ctx);

Parameters

ctx	the context for the socket

Exceptions

ZSOCKET-CONSTRUCTOR-ERROR this exception is thrown if there is any error creating the socket

Note: Newly created ZSocketSub objects filter out all incoming messages, therefore you should call subscribe() to establish an initial message filter

◆ subscribe()

nothing Qore::ZMQ::ZSocketSub::subscribe ( *string subs )

Adds a subscription to the socket.

Example:: zsock.subscribe(str);

Parameters

subs	the socket subscription string to set; the string will be converted to UTF-8 encoding if necessary; the subscription string will be cleared if nothing is passed

This call adds a new message filter on the socket. Newly created ZSocketSub objects filter out all incoming messages, therefore you should call thie method to establish an initial message filter.

An empty string (or nothing) means to subscribe to all incoming messages. A non-empty string subscribes to all messages beginning with the specified prefix. Multiple filters may be attached to a single ZSocketSub object, in which case a message will be accepted if it matches at least one filter.

Exceptions

ENCODING-CONVERSION-ERROR	this exception could be thrown if an encoding error is encountered when converting the given string to UTF-8
ZSOCKET-SUBSCRIBE-ERROR	if an error occurs setting the subscription option on the socket
ZSOCKET-THREAD-ERROR	this exception is thrown if this method is called from a thread other than the thread where the object was created
ZSOCKET-CONTEXT-ERROR	the context is no longer valid

See also

◆ unsubscribe()

nothing Qore::ZMQ::ZSocketSub::unsubscribe ( *string subs )

Removes a subscription from the socket.

Example:: zsock.unsubscribe(str);

Parameters

subs	the socket subscription string to remove; the string will be converted to UTF-8 encoding if necessary; the subscription string will be cleared if nothing is passed

This call removes an existing subscription from the socket. The subscription string specified must match an existing filter previously established. If the socket has several instances of the same filter attached, this call will remove only one instance, leaving the rest in place and functional.

Exceptions

ENCODING-CONVERSION-ERROR	this exception could be thrown if an encoding error is encountered when converting the given string to UTF-8
ZSOCKET-UNSUBSCRIBE-ERROR	if an error occurs setting the subscription option on the socket
ZSOCKET-THREAD-ERROR	this exception is thrown if this method is called from a thread other than the thread where the object was created
ZSOCKET-CONTEXT-ERROR	the context is no longer valid

See also

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

QC_ZSocketSub.dox.h

Public Member Methods

Additional Inherited Members

Detailed Description

Member Function Documentation

◆ constructor() [1/2]

◆ constructor() [2/2]

◆ subscribe()

◆ unsubscribe()