The socket class represents the zmq sockets. More...

#include <socket.hpp>

Public Member Functions
	socket (context_t const &context, socket_type const type)
	Create a socket for a given type. More...

	~socket ()
	This will close any socket still open before returning. More...

socket_type	type () const
	Get the type of the socket, this works on zmqpp types and not the zmq internal types. More...

void	bind (endpoint_t const &endpoint)
	Asynchronously binds to an endpoint. More...

void	unbind (endpoint_t const &endpoint)
	Unbinds from a previously bound endpoint. More...

void	connect (endpoint_t const &endpoint)
	Asynchronously connects to an endpoint. More...

template<typename InputIterator >
void	connect (InputIterator const &connections_begin, InputIterator const &connections_end)
	Asynchronously connects to multiple endpoints. More...

void	disconnect (endpoint_t const &endpoint)
	Disconnects a previously connected endpoint. More...

template<typename InputIterator >
void	disconnect (InputIterator const &disconnections_begin, InputIterator const &disconnections_end)
	Disconnects from multiple previously connected endpoints. More...

void	close ()
	Closes the internal zmq socket and marks this instance as invalid. More...

bool	send (message_t &message, bool const dont_block=false)
	Sends the message over the connection, this may be a multipart message. More...

bool	receive (message_t &message, bool const dont_block=false)
	Gets a message from the connection, this may be a multipart message. More...

bool	send (std::string const &string, int const flags=normal)
	Sends the byte data held by the string as the next message part. More...

bool	receive (std::string &string, int const flags=normal)
	If there is a message ready then get the next part as a string. More...

bool	send (signal sig, bool dont_block=false)
	Sends a signal over the socket. More...

bool	receive (signal &sig, bool dont_block=false)
	If there is a message ready then we read a signal from it. More...

bool	send_raw (char const *buffer, size_t const length, int const flags=normal)
	Sends the byte data pointed to by buffer as the next part of the message. More...

bool	receive_raw (char *buffer, size_t &length, int const flags=normal)

void	subscribe (std::string const &topic)
	Subscribe to a topic. More...

template<typename InputIterator >
void	subscribe (InputIterator const &topics_begin, InputIterator const &topics_end)
	Subscribe to a topic. More...

void	unsubscribe (std::string const &topic)
	Unsubscribe from a topic. More...

template<typename InputIterator >
void	unsubscribe (InputIterator const &topics_begin, InputIterator const &topics_end)
	Unsubscribe from a topic. More...

bool	has_more_parts () const
	If the last receive part call to the socket resulted in a label or a non-terminating part of a multipart message this will return true. More...

void	set (socket_option const option, int const value)
	Set the value of an option in the underlaying zmq socket. More...

void	set (socket_option const option, bool const value)
	Set the value of an option in the underlaying zmq socket. More...

void	set (socket_option const option, uint64_t const value)
	Set the value of an option in the underlaying zmq socket. More...

void	set (socket_option const option, int64_t const value)
	Set the value of an option in the underlaying zmq socket. More...

void	set (socket_option const option, char const *value, size_t const length)
	Set the value of an option in the underlaying zmq socket. More...

void	set (socket_option const option, char const *value)
	Set the value of an option in the underlaying zmq socket. More...

void	set (socket_option const option, std::string const value)
	Set the value of an option in the underlaying zmq socket. More...

void	get (socket_option const option, int &value) const
	Get a socket option from the underlaying zmq socket. More...

void	get (socket_option const option, bool &value) const
	Get a socket option from the underlaying zmq socket. More...

void	get (socket_option const option, uint64_t &value) const
	Get a socket option from the underlaying zmq socket. More...

void	get (socket_option const option, int64_t &value) const
	Get a socket option from the underlaying zmq socket. More...

void	get (socket_option const option, std::string &value) const
	Get a socket option from the underlaying zmq socket. More...

template<typename Type >
Type	get (socket_option const option) const
	For those that don't want to get into a referenced value this templated method will return the value instead. More...

void	monitor (endpoint_t const monitor_endpoint, int events_required)
	Attach a monitor to this socket that will send events over inproc to the specified endpoint. More...

signal	wait ()
	Wait on signal, this is useful to coordinate thread. More...

	socket (socket &&source) NOEXCEPT
	Move constructor. More...

socket &	operator= (socket &&source) NOEXCEPT
	Move operator. More...

	operator bool () const
	Check the socket is still valid. More...

	operator void * () const
	Access to the raw 0mq context. More...

Static Public Attributes
static const int	normal = 0

static const int	dont_wait = ZMQ_DONTWAIT

static const int	send_more = ZMQ_SNDMORE

Private Member Functions
	socket (socket const &) NOEXCEPT ZMQPP_EXPLICITLY_DELETED

socket &	operator= (socket const &) NOEXCEPT ZMQPP_EXPLICITLY_DELETED

void	track_message (message_t const &, uint32_t const, bool &)

Private Attributes
void *	_socket

socket_type	_type

zmq_msg_t	_recv_buffer

Detailed Description

The socket class represents the zmq sockets.

A socket can be bound and/or connected to as many endpoints as required with the sole exception of a ::pair socket.

The routing is handled by zmq based on the type set.

The bound side of an inproc connection must occur first and inproc can only connect to other inproc sockets of the same context. This has been solved in 0mq 4.0 or later and is not a requirement of inproc.

This class is c++0x move supporting and cannot be copied.

Constructor & Destructor Documentation

zmqpp::socket::socket	(	context_t const &	context,
		socket_type const	type
	)

Create a socket for a given type.

Parameters

context	the zmq context under which the socket will live
type	a valid socket_type for the socket

zmqpp::socket::~socket ( )

This will close any socket still open before returning.

zmqpp::socket::socket ( socket && source )

Move constructor.

Moves the internals of source to this object, there is no guarantee that source will be left in a valid state.

This constructor is noexcept and so will not throw exceptions

Parameters

source target socket to steal internals from

zmqpp::socket::socket ( socket const & )

private

Member Function Documentation

void zmqpp::socket::bind ( endpoint_t const & endpoint )

Asynchronously binds to an endpoint.

Parameters

endpoint the zmq endpoint to bind to

void zmqpp::socket::close ( )

Closes the internal zmq socket and marks this instance as invalid.

void zmqpp::socket::connect ( endpoint_t const & endpoint )

Asynchronously connects to an endpoint.

If the endpoint is not inproc then zmq will happily keep trying to connect until there is something there.

Inproc sockets must have a valid target already bound before connection will work.

Parameters

endpoint the zmq endpoint to connect to

template<typename InputIterator >

void zmqpp::socket::connect	(	InputIterator const &	connections_begin,
		InputIterator const &	connections_end
	)

inline

Asynchronously connects to multiple endpoints.

If the endpoint is not inproc then zmq will happily keep trying to connect until there is something there.

Inproc sockets must have a valid target already bound before connection will work.

This is a helper function that wraps the single item connect in a loop

Parameters

connections_begin	the starting iterator for zmq endpoints.
connections_end	the final iterator for zmq endpoints.

void zmqpp::socket::disconnect ( endpoint_t const & endpoint )

Disconnects a previously connected endpoint.

Parameters

endpoint the zmq endpoint to disconnect from

template<typename InputIterator >

void zmqpp::socket::disconnect	(	InputIterator const &	disconnections_begin,
		InputIterator const &	disconnections_end
	)

inline

Disconnects from multiple previously connected endpoints.

This is a helper function that wraps the single item disconnect in a loop

Parameters

disconnections_begin	the starting iterator for zmq endpoints.
disconnections_end	the final iterator for zmq endpoints.

void zmqpp::socket::get	(	socket_option const	option,
		int &	value
	)		const

Get a socket option from the underlaying zmq socket.

Parameters

option	a valid socket_option
value	referenced int to return value in

void zmqpp::socket::get	(	socket_option const	option,
		bool &	value
	)		const

Get a socket option from the underlaying zmq socket.

Parameters

option	a valid socket_option
value	referenced bool to return value in

void zmqpp::socket::get	(	socket_option const	option,
		uint64_t &	value
	)		const

Get a socket option from the underlaying zmq socket.

Parameters

option	a valid socket_option
value	referenced uint64_t to return value in

void zmqpp::socket::get	(	socket_option const	option,
		int64_t &	value
	)		const

Get a socket option from the underlaying zmq socket.

Parameters

option	a valid socket_option
value	referenced uint64_t to return value in

void zmqpp::socket::get	(	socket_option const	option,
		std::string &	value
	)		const

Get a socket option from the underlaying zmq socket.

Parameters

option	a valid socket_option
value	referenced std::string to return value in

template<typename Type >

Type zmqpp::socket::get ( socket_option const option ) const

inline

For those that don't want to get into a referenced value this templated method will return the value instead.

Parameters

option a valid socket_option

Returns: socket option value

bool zmqpp::socket::has_more_parts ( ) const

If the last receive part call to the socket resulted in a label or a non-terminating part of a multipart message this will return true.

Returns: true if there are more parts

void zmqpp::socket::monitor	(	endpoint_t const	monitor_endpoint,
		int	events_required
	)

Attach a monitor to this socket that will send events over inproc to the specified endpoint.

The monitor will bind on the endpoint given and will be of type PAIR but not read from the stream.

Parameters

monitor_endpoint	the valid inproc endpoint to bind to.
events_required	a bit mask of required events.

zmqpp::socket::operator bool ( ) const

Check the socket is still valid.

This tests the internal state of the socket. If creation failed for some reason or if the move functions were used to move the socket internals to another instance this will return false.

Returns: true if the socket is valid

zmqpp::socket::operator void * ( ) const

Access to the raw 0mq context.

Returns: void pointer to the underlying 0mq socket

socket & zmqpp::socket::operator= ( socket && source )

Move operator.

Moves the internals of source to this object, there is no guarantee that source will be left in a valid state.

This function is noexcept and so will not throw exceptions

Parameters

source target socket to steal internals from

Returns: socket reference to this

socket& zmqpp::socket::operator= ( socket const & )

private

bool zmqpp::socket::receive	(	message_t &	message,
		bool const	dont_block = `false`
	)

Gets a message from the connection, this may be a multipart message.

If dont_block is true and we are unable to get a message then this function will return false.

Parameters

message	reference to fill with received data
dont_block	boolean to dictate if we wait for data.

Returns: true if message sent, false if it would have blocked

bool zmqpp::socket::receive	(	std::string &	string,
		int const	flags = `normal`
	)

If there is a message ready then get the next part as a string.

If the socket::DONT_WAIT flag and there is no message ready to receive then this function will return false.

Parameters

string	message part to receive into
flags	message receive flags

Returns: true if message part received, false if it would have blocked

bool zmqpp::socket::receive	(	zmqpp::signal &	sig,
		bool	dont_block = `false`
	)

If there is a message ready then we read a signal from it.

If dont_block is true and we are unable to send the signal then this function will return false.

Parameters

sig	signal to receive into
flags	message receive flags

Returns: true if signal received, false if it would have blocked

bool zmqpp::socket::receive_raw	(	char *	buffer,
		size_t &	length,
		int const	flags = `normal`
	)

Warning: If the buffer is not large enough for the message part then the data will be truncated. The rest of the part is lost forever.

If there is a message ready then get the next part of it as a raw byte buffer.

If the socket::DONT_WAIT flag and there is no message ready to receive then this function will return false.

Parameters

buffer	byte buffer pointer to start writing to
length	max length of the buffer
flags	message receive flags

Returns: true if message part received, false if it would have blocked

bool zmqpp::socket::send	(	message_t &	message,
		bool const	dont_block = `false`
	)

Sends the message over the connection, this may be a multipart message.

If dont_block is true and we are unable to add a new message then this function will return false.

Parameters

message	message to send
dont_block	boolean to dictate if we wait while sending.

Returns: true if message sent, false if it would have blocked

bool zmqpp::socket::send	(	std::string const &	string,
		int const	flags = `normal`
	)

Sends the byte data held by the string as the next message part.

If the socket::DONT_WAIT flag and we are unable to add a new message to socket then this function will return false.

Parameters

string	message part to send
flags	message send flags

Returns: true if message part sent, false if it would have blocked

bool zmqpp::socket::send	(	zmqpp::signal	sig,
		bool	dont_block = `false`
	)

Sends a signal over the socket.

If dont_block is true and we are unable to send the signal e then this function will return false.

Parameters

sig	signal to send.
flags	message send flags

Returns: true if message part sent, false if it would have blocked

bool zmqpp::socket::send_raw	(	char const *	buffer,
		size_t const	length,
		int const	flags = `normal`
	)

Sends the byte data pointed to by buffer as the next part of the message.

If the socket::DONT_WAIT flag and we are unable to add a new message to socket then this function will return false.

Parameters

buffer	byte buffer pointer to start writing from
length	max length of the buffer
flags	message send flags

Returns: true if message part sent, false if it would have blocked

void zmqpp::socket::set	(	socket_option const	option,
		int const	value
	)