A MessageSocket is a message-oriented layer on top of a TCP connection. More...

#include <MessageSocket.h>

Classes
class	Handler
	An interface for handling events generated by a MessageSocket. More...
struct	Header
	This is the header that precedes every message across the TCP socket. More...
struct	Inbound
	This class stages a message while it is being received. More...
struct	Outbound
	This class stages a message while it is being sent. More...
struct	ReceiveSocket
	This class is an Event::File monitor that calls readable() when the socket can be read from without blocking. More...
struct	SendSocket
	This class is an Event::File monitor that calls writable() when the socket can be written to without blocking. More...
Public Types
enum	{ MAX_VERSION_SUPPORTED }
	Largest version of the framing protocol supported by this code. More...
typedef uint64_t	MessageId
	An opaque identifier for a message.
Public Member Functions
	MessageSocket (Handler &handler, Event::Loop &eventLoop, int fd, uint32_t maxMessageLength)
	Constructor.
	~MessageSocket ()
	Destructor.
void	close ()
	Used when the server wishes to close this socket.
void	sendMessage (MessageId messageId, Core::Buffer contents)
	Queue a message to be sent to the other side of this socket.
Private Member Functions
void	disconnect ()
	Cleans up and calls onDisconnect() when the socket has an error.
void	readable ()
	Called when the socket has data that can be read without blocking.
ssize_t	read (void *buf, size_t maxBytes)
	Wrapper around recv(); used by readable().
void	writable ()
	Called when the socket may be written to without blocking.
	MessageSocket (const MessageSocket &)
MessageSocket &	operator= (const MessageSocket &)
Private Attributes
const uint32_t	maxMessageLength
	The maximum number of bytes of payload to allow per message.
Handler &	handler
	Deals with received messages and disconnects.
Event::Loop &	eventLoop
	Used to find out when the socket is readable or writable.
Inbound	inbound
	The current message that is being received.
Core::Mutex	outboundQueueMutex
	Protects outboundQueue only from concurrent modification.
std::deque< Outbound >	outboundQueue
	A queue of messages waiting to be sent.
ReceiveSocket	receiveSocket
	Notifies MessageSocket when the socket can be read from without blocking.
SendSocket	sendSocket
	Notifies MessageSocket when the socket can be transmitted on without blocking.
Event::File::Monitor	receiveSocketMonitor
	Registers receiveSocket with the event loop.
Event::File::Monitor	sendSocketMonitor
	Registers sendSocket with the event loop.

Detailed Description

A MessageSocket is a message-oriented layer on top of a TCP connection.

It sends and receives discrete chunks of data identified by opaque IDs. Higher layers can use this to build an RPC framework, both on the client side and on the server side.

Definition at line 47 of file MessageSocket.h.

Member Typedef Documentation

typedef uint64_t LogCabin::RPC::MessageSocket::MessageId

An opaque identifier for a message.

For RPCs, clients can use this to pair up a response with its request, and servers will want to reply with the same ID as the matching request.

Definition at line 54 of file MessageSocket.h.

Member Enumeration Documentation

anonymous enum

Largest version of the framing protocol supported by this code.

Enumerator:

MAX_VERSION_SUPPORTED

Definition at line 59 of file MessageSocket.h.

Constructor & Destructor Documentation

LogCabin::RPC::MessageSocket::MessageSocket	(	Handler &	handler,
		Event::Loop &	eventLoop,
		int	fd,
		uint32_t	maxMessageLength
	)

Constructor.

Parameters:

handler	Handles received messages and disconnect events.
eventLoop	Event::Loop that will be used to find out when the socket is readable or writable.
fd	Connected file descriptor for the socket. This object will close the file descriptor when it is disconnected.
maxMessageLength	The maximum number of bytes of payload to allow per message. This exists to limit the amount of buffer space a single socket can use. Attempting to send longer messages will PANIC; attempting to receive longer messages will disconnect the socket.

Definition at line 174 of file MessageSocket.cc.

LogCabin::RPC::MessageSocket::~MessageSocket ( )

Destructor.

Definition at line 190 of file MessageSocket.cc.

LogCabin::RPC::MessageSocket::MessageSocket ( const MessageSocket & ) [private]

Member Function Documentation

void LogCabin::RPC::MessageSocket::close ( )

Used when the server wishes to close this socket.

It invokes Handler::handleDisconnect(), as if the client has disconnected. After this returns, the Handler will not be called again.

Definition at line 195 of file MessageSocket.cc.

void LogCabin::RPC::MessageSocket::sendMessage	(	MessageId	messageId,
		Core::Buffer	contents
	)

Queue a message to be sent to the other side of this socket.

This method is safe to call from any thread.

Parameters:

messageId	An opaque identifier for the message.
contents	The data to send. This must be shorter than the maxMessageLength argument given to the constructor.

Definition at line 207 of file MessageSocket.cc.

void LogCabin::RPC::MessageSocket::disconnect ( ) [private]

Cleans up and calls onDisconnect() when the socket has an error.

Only called from event loop handlers.

Definition at line 228 of file MessageSocket.cc.

void LogCabin::RPC::MessageSocket::readable ( ) [private]

Called when the socket has data that can be read without blocking.

Definition at line 238 of file MessageSocket.cc.

ssize_t LogCabin::RPC::MessageSocket::read	(	void *	buf,
		size_t	maxBytes
	)		`[private]`

Wrapper around recv(); used by readable().

Parameters:

buf	Where to store the data received.
maxBytes	The maximum number of bytes to receive and store into buf.

Returns:: The number of bytes read (<= maxBytes), if successful. The value -1 indicates that the socket was disconnected, in which case the caller must be careful not to access this object and immediately return.

Definition at line 312 of file MessageSocket.cc.

void LogCabin::RPC::MessageSocket::writable ( ) [private]

Called when the socket may be written to without blocking.

Definition at line 327 of file MessageSocket.cc.

MessageSocket& LogCabin::RPC::MessageSocket::operator= ( const MessageSocket & ) [private]

Member Data Documentation

const uint32_t LogCabin::RPC::MessageSocket::maxMessageLength [private]

The maximum number of bytes of payload to allow per message.

This exists to limit the amount of buffer space a single socket can use.

Definition at line 297 of file MessageSocket.h.

Handler& LogCabin::RPC::MessageSocket::handler [private]

Deals with received messages and disconnects.

Definition at line 302 of file MessageSocket.h.

Event::Loop& LogCabin::RPC::MessageSocket::eventLoop [private]

Used to find out when the socket is readable or writable.

Definition at line 307 of file MessageSocket.h.

Inbound LogCabin::RPC::MessageSocket::inbound [private]

The current message that is being received.

Definition at line 312 of file MessageSocket.h.

Core::Mutex LogCabin::RPC::MessageSocket::outboundQueueMutex [private]

Protects outboundQueue only from concurrent modification.

Definition at line 317 of file MessageSocket.h.

std::deque<Outbound> LogCabin::RPC::MessageSocket::outboundQueue [private]

A queue of messages waiting to be sent.

The first one may be in the middle of transmission, while the others have not yet started. This queue is protected from concurrent modifications by outboundQueueMutex.

It's important that this remains a std::deque (or std::queue) because writable() holds a pointer to the first element without the lock, while sendMessage() may concurrently push onto the queue. std::deques are guaranteed not to invalidate pointers while elements are pushed and popped from the ends.

Definition at line 330 of file MessageSocket.h.

ReceiveSocket LogCabin::RPC::MessageSocket::receiveSocket [private]

Notifies MessageSocket when the socket can be read from without blocking.

Definition at line 336 of file MessageSocket.h.

SendSocket LogCabin::RPC::MessageSocket::sendSocket [private]

Notifies MessageSocket when the socket can be transmitted on without blocking.

Definition at line 342 of file MessageSocket.h.

Event::File::Monitor LogCabin::RPC::MessageSocket::receiveSocketMonitor [private]

Registers receiveSocket with the event loop.

Definition at line 347 of file MessageSocket.h.

Event::File::Monitor LogCabin::RPC::MessageSocket::sendSocketMonitor [private]

Registers sendSocket with the event loop.