PSocket Class Reference

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

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()