Detailed Description

The PSocket class represents a network socket which relies on 0-MQ distributed messaging library; NOT thread-safe.

Definition at line 26 of file PSocket.h.

#include <PSocket.h>

Member Enumeration Documentation

◆ ESocketBinding

Enumerator
E_UNSPECIFIED
E_BIND
E_CONNECT

Definition at line 47 of file PSocket.h.

◆ ESocketType

enum PSocket::ESocketType

All available type of sockets, see http://api.zeromq.org/4-0:zmq-socket for details.

Enumerator
E_NULL
E_REPLY	traditional client/server; SERVER side
E_REQUEST	traditional client/server; CLIENT side
E_DEALER
E_ROUTER
E_PUBLISHER	publisher/subscriber pattern
E_SUBSCRIBER	publisher/subscriber pattern: subscriber must call Subscriber() to start receiving messages. Warning: subscribers must NOT BE in the same thread than publisher
E_PUSH	push/pull pattern: messages are round-robined to all connected clients; can be used for load-balancing
E_PULL	push/pull pattern: messages are round-robined to all connected clients; can be used for load-balancing
E_PAIR
E_STREAM

Definition at line 32 of file PSocket.h.

Constructor & Destructor Documentation

◆ PSocket() [1/2]

PSocket::PSocket ( )

Constructs an unspecified / unbound socket.

See also: Open()

◆ PSocket() [2/2]

PSocket::PSocket ( const PSocket & other )

Constructs a shared copy of other.

◆ ~PSocket()

virtual PSocket::~PSocket ( )

virtual

Destroys this object.

Member Function Documentation

◆ Bind()

PResult PSocket::Bind ( const PString & endPoint )

Connects this socket to the specified LOCAL end-point (accepts incoming connections on this socket).

Returns PResult::C_OK if success, another result otherwise.

See also: Connect()

◆ Close()

PResult PSocket::Close ( )

Closes this socket.

Any outstanding messages physically received from the network but not yet received by the application Receive() shall be discarded. The behaviour for discarding messages sent by the application Send() but not yet physically transferred to the network depends on the value of the LINGER socket option for the specified socket (see SetLingerPeriod()). By default, linger period is infinite: pending messages shall not be discarded after a call to Close().

Returns PResult::C_OK if success, another result otherwise.

See also: SetLingerPeriod()

◆ Connnect()

PResult PSocket::Connnect ( const PString & endPoint )

Connects this socket to the specified REMOTE end-point (creates outgoing connection from this socket).

Returns PResult::C_OK if success, another result otherwise.

NOTE This function will likely be renamed due to type in the name FIXME(AK)

See also: Bind()

◆ GetBoundAddress()

PResult PSocket::GetBoundAddress ( PString & boundAddress ) const

Returns the bound IP address if this socket is bound, and PResult::Error otherwise.

◆ GetBoundPoint()

PResult PSocket::GetBoundPoint ( PString & boundPoint ) const

Returns PResult::C_OK if socket is in bound state and bound point could be retrieved, another result otherwise.

Bound point is in the form "tcp://IP:port".

◆ GetBoundPort()

PResult PSocket::GetBoundPort ( papillon::uint32 & boundPort ) const

Returns the bound port number if this socket is bound, and PResult::Error otherwise.

◆ IsOpened()

bool PSocket::IsOpened ( ) const

Returns true if this socket is bound, false otherwise.

◆ IsPendingIncomingMessage()

PResult PSocket::IsPendingIncomingMessage ( papillon::int32 timeOutMs = 0 ) const

Returns PResult::C_OK if and only at least one message may be received from this socket without blocking, returns C_FALSE it there is no pending messages, another result otherwise.

If there is no pending message, then IsPendingIncomingMessage() shall wait timeout milliseconds for an event to occur. By default, do not wait (timeOutMs = 0).

◆ IsPendingOutgoingMessage()

PResult PSocket::IsPendingOutgoingMessage ( int32 timeOutMs = 0 ) const

Returns PResult::C_OK if and only at least one message may be sent to this socket without blocking, returns C_FALSE it there is no pending messages, another result otherwise.

If there is no pending message, then IsPendingOutgoingMessage() shall wait timeout milliseconds for an event to occur. By default, do not wait (timeOutMs = 0).

◆ Open()

static PResult PSocket::Open	(	PSocket &	socket,
		ESocketType	socketType,
		ESocketBinding	binding = `E_UNSPECIFIED`,
		const PString &	endPoint = `PString::Empty()`
	)

static

Creates a 0MQ-like socket of the specified type and connect it to the specified end-point if any.

If binding is BIND, then connect the socket to the specified local end-point.
If binding is CONNECT, then connect the socket to the specified remote end-point.
If binding is UNSPECIFIED, then do not connect; in this case, you will have to call Bind() or Connect() later.

Returns PResult::C_OK if success, another result otherwise.

◆ operator=()

PSocket& PSocket::operator= ( const PSocket & other )

Performs a shared copy of other to this object.

◆ operator==()

bool PSocket::operator== ( const PSocket & other ) const

Returns true if this object is the same instance than other, false otherwise.

◆ Receive() [1/3]

PResult PSocket::Receive ( PString & message )

Receives a string message from this socket (atomic message retrieving in blocking-mode).

Waits until a message is available. The specified string is first cleared, then filled with the message. Returns PResult::C_OK if success, another result otherwise (e.g. if the message is not a PString)

◆ Receive() [2/3]

PResult PSocket::Receive ( PByteArray & message )

Receives a message from this socket (atomic message retrieving in blocking-mode).

Waits until a message is available. The specified message buffer is first cleared, then filled with the message. Returns PResult::C_OK if success, another result otherwise.

◆ Receive() [3/3]

PResult PSocket::Receive	(	void *	buffer,
		papillon::int32	sizeofBufferInBytes,
		papillon::int32 &	sizeOfMessageInBytes
	)

Receives a message from this socket (atomic message retrieving in blocking-mode).

Waits until a message is available. The parameter 'sizeofBufferInBytes' is used to check buffer overflow: if the size of the message exceeds the size of the buffer, then returns an error. If success, the size-of the message is put in 'sizeOfMessageInBytes'. Returns PResult::C_OK if success, another result otherwise.

◆ Send() [1/3]

PResult PSocket::Send	(	const PString &	message,
		const PString &	filter = `PString::Empty()`
	)

Sends the specified string message on this socket (atomic message delivery in blocking-mode).

This method is performed in blocking-mode (synchronous); it waits until the message has been delivered. It ensures atomic delivery of messages. Filter (optional) is used to specify which subscribers will receive message. Returns PResult::C_OK if success, another result otherwise.

◆ Send() [2/3]

PResult PSocket::Send	(	const PByteArray &	message,
		const PString &	filter = `PString::Empty()`
	)

Sends the specified message (all bytes of the buffer) on this socket (atomic message delivery in blocking-mode).

This method is performed in blocking-mode (synchronous); it waits until the message has been delivered. It ensures atomic delivery of messages. Filter (optional) is used to specify which subscribers will receive message. Returns PResult::C_OK if success, another result otherwise.

◆ Send() [3/3]

PResult PSocket::Send	(	const void *	buffer,
		int32	lengthInBytes,
		const PString &	filter = `PString::Empty()`
	)

Sends the specified byte buffer on this socket (atomic message delivery in blocking-mode).

This method is performed in blocking-mode (synchronous); it waits until the message has been delivered. Filter (optional) is used to specify which subscribers will receive message. It ensures atomic delivery of messages.

◆ SetLingerPeriod()

PResult PSocket::SetLingerPeriod ( papillon::int32 periodInMs )

Sets the linger period for socket shutdown.

The linger period determines how long pending messages which have yet to be sent to a peer shall linger in memory after a socket is closed. Use -1 for an infinite period, 0 for no linger period or any other positive value for a specific period in milliseconds.

Returns PResult::C_OK if success, another result otherwise.

◆ Subscribe()

PResult PSocket::Subscribe ( const PString & filter = PString::Empty() )

The subscribe option shall establish a new message filter on a E_SUBSCRIBER socket.

Newly created E_SUBSCRIBER sockets shall filter out all incoming messages, therefore you should call this option to establish an initial message filter.

An empty filter of length zero shall subscribe to all incoming messages. A non-empty filter shall subscribe to all messages beginning with the specified prefix. Multiple filters may be attached to a single socket, in which case a message shall be accepted if it matches at least one filter.

Returns PResult::C_OK if success, another result otherwise.

See also: Unsubscribe()

◆ Unsubscribe()

PResult PSocket::Unsubscribe ( const PString & filter )

The unsubscribe option shall remove an existing message filter E_SUBSCRIBER socket.

The filter specified must match an existing filter previously established with the E_SUBSCRIBER option. If the socket has several instances of the same filter attached the unsubscribe option shall remove only one instance, leaving the rest in place and functional.

Returns PResult::C_OK if success, another result otherwise.

See also: Subscribe()