A ClientSession is used to initiate OpaqueClientRPCs. More...

#include <ClientSession.h>

Classes
class	MessageSocketHandler
	This handles events from messageSocket. More...
struct	Response
	This contains an expected response for a OpaqueClientRPC object. More...
class	Timer
	This is used to time out RPCs and sessions when the server is no longer responding. More...
Public Types
typedef Address::Clock	Clock
	Clock used for timeouts.
typedef Address::TimePoint	TimePoint
	Type for absolute time values used for timeouts.
Public Member Functions
	~ClientSession ()
	Destructor.
OpaqueClientRPC	sendRequest (Core::Buffer request)
	Initiate an RPC.
std::string	getErrorMessage () const
	If the socket has been disconnected, return a descriptive message.
std::string	toString () const
	Return a string describing this session.
Static Public Member Functions
static std::shared_ptr < ClientSession >	makeSession (Event::Loop &eventLoop, const Address &address, uint32_t maxMessageLength, TimePoint timeout, const Core::Config &config)
	Return a new ClientSession object.
static std::shared_ptr < ClientSession >	makeErrorSession (Event::Loop &eventLoop, const std::string &errorMessage)
	Return a ClientSession object that's already in an error state.
Private Member Functions
	ClientSession (Event::Loop &eventLoop, const Address &address, uint32_t maxMessageLength, TimePoint timeout, const Core::Config &config)
	This constructor is private because the class must be allocated in a particular way.
void	cancel (OpaqueClientRPC &rpc)
	Called by the RPC when it is no longer interested in its response.
void	update (OpaqueClientRPC &rpc)
	Called by the RPC when it wants to be learn of its response (non-blocking).
void	wait (const OpaqueClientRPC &rpc, TimePoint timeout)
	Called by the RPC to wait for its response (blocking).
	ClientSession (const ClientSession &)
ClientSession &	operator= (const ClientSession &)
Private Attributes
std::weak_ptr< ClientSession >	self
	This is used to keep this object alive while there are outstanding RPCs.
const uint64_t	PING_TIMEOUT_NS
	The number of nanoseconds to wait until the client gets suspicious about the server not responding.
Event::Loop &	eventLoop
	The event loop that is used for non-blocking I/O.
const Address	address
	The RPC server address provided to the constructor.
MessageSocketHandler	messageSocketHandler
	Receives events from messageSocket.
Timer	timer
	This is used to time out RPCs and sessions when the server is no longer responding.
std::mutex	mutex
	This mutex protects several members of this class:
MessageSocket::MessageId	nextMessageId
	The message ID to assign to the next RPC.
std::unordered_map < MessageSocket::MessageId, Response * >	responses
	A map from MessageId to Response objects that is used to store the response to RPCs and look it up for OpaqueClientRPC objects.
std::string	errorMessage
	If this session is disconnected then this holds the error message.
uint32_t	numActiveRPCs
	The number of outstanding RPC requests that have been sent but whose responses have not yet been received.
bool	activePing
	When numActiveRPCs is > 0, this field indicates that we are waiting for a ping response as evidence that the server is still alive.
std::unique_ptr< MessageSocket >	messageSocket
	The MessageSocket used to send RPC requests and receive RPC responses.
Event::Timer::Monitor	timerMonitor
	Registers timer with the event loop.
Static Private Attributes
static std::function< int(int sockfd, const struct sockaddr *addr, socklen_t addrlen)	connectFn )
	Usually set to connect() but mocked out in some unit tests.
Friends
class	OpaqueClientRPC

Detailed Description

A ClientSession is used to initiate OpaqueClientRPCs.

It encapsulates a connection to a server. Sessions can be relatively expensive to create, so clients should keep them around.

Definition at line 47 of file ClientSession.h.

Member Typedef Documentation

typedef Address::Clock LogCabin::RPC::ClientSession::Clock

Clock used for timeouts.

Definition at line 50 of file ClientSession.h.

typedef Address::TimePoint LogCabin::RPC::ClientSession::TimePoint

Type for absolute time values used for timeouts.

Definition at line 52 of file ClientSession.h.

Constructor & Destructor Documentation

LogCabin::RPC::ClientSession::ClientSession	(	Event::Loop &	eventLoop,
		const Address &	address,
		uint32_t	maxMessageLength,
		TimePoint	timeout,
		const Core::Config &	config
	)		`[private]`

This constructor is private because the class must be allocated in a particular way.

See makeSession().

Definition at line 221 of file ClientSession.cc.

LogCabin::RPC::ClientSession::~ClientSession ( )

Destructor.

Definition at line 369 of file ClientSession.cc.

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

Member Function Documentation

std::shared_ptr< ClientSession > LogCabin::RPC::ClientSession::makeSession	(	Event::Loop &	eventLoop,
		const Address &	address,
		uint32_t	maxMessageLength,
		TimePoint	timeout,
		const Core::Config &	config
	)		`[static]`

Return a new ClientSession object.

This object is managed by a std::shared_ptr to ensure that it remains alive while there are outstanding RPCs.

This should only be used from worker threads, as it invokes possibly long-running syscalls.

Parameters:

eventLoop	Event::Loop that will be used to find out when the underlying socket may be read from or written to without blocking.
address	The RPC server address on which to connect.
maxMessageLength	The maximum number of bytes to allow per request/response. This exists to limit the amount of buffer space a single RPC can use. Attempting to send longer requests will PANIC; attempting to receive longer requests will disconnect the underlying socket.
timeout	After this time has elapsed, stop trying to initiate the connection and leave the session in an error state.
config	General settings. This object does not keep a reference.

Definition at line 335 of file ClientSession.cc.

std::shared_ptr< ClientSession > LogCabin::RPC::ClientSession::makeErrorSession	(	Event::Loop &	eventLoop,
		const std::string &	errorMessage
	)		`[static]`

Return a ClientSession object that's already in an error state.

This can be useful for delaying errors until an RPC is waited on.

Parameters:

eventLoop	Ignored but usually readily available to callers and needed to satisfy type requirements.
errorMessage	Description of the error, as will be returned by getErrorMessage() later.

Definition at line 352 of file ClientSession.cc.

OpaqueClientRPC LogCabin::RPC::ClientSession::sendRequest ( Core::Buffer request )

Initiate an RPC.

This method is safe to call from any thread.

Parameters:

request The contents of the RPC request.

Returns:: This is be used to wait for and retrieve the reply to the RPC.

Definition at line 378 of file ClientSession.cc.

std::string LogCabin::RPC::ClientSession::getErrorMessage ( ) const

If the socket has been disconnected, return a descriptive message.

The suggested way to detect errors is to wait until an RPC returns an error. This method can be used to detect errors earlier.

This method is safe to call from any thread.

Returns:: If an error has occurred, a message describing that error. Otherwise, an empty string.

Definition at line 405 of file ClientSession.cc.

std::string LogCabin::RPC::ClientSession::toString ( ) const

Return a string describing this session.

It will include the address of the server and, if the session has an error, the error message.

Definition at line 412 of file ClientSession.cc.

void LogCabin::RPC::ClientSession::cancel ( OpaqueClientRPC & rpc ) [private]

Called by the RPC when it is no longer interested in its response.

This may be called while holding the RPC's lock.

TODO(ongaro): It'd be nice to cancel sending the request if it hasn't already gone out, but I guess that's going to be a pretty rare case.

Definition at line 426 of file ClientSession.cc.

void LogCabin::RPC::ClientSession::update ( OpaqueClientRPC & rpc ) [private]

Called by the RPC when it wants to be learn of its response (non-blocking).

This must be called while holding the RPC's lock.

Definition at line 459 of file ClientSession.cc.

void LogCabin::RPC::ClientSession::wait	(	const OpaqueClientRPC &	rpc,
		TimePoint	timeout
	)		`[private]`

Called by the RPC to wait for its response (blocking).

The caller should call update() after this returns to learn of the response.

This must not be called while holding the RPC's lock.

Parameters:

rpc	Wait for response to this.
timeout	After this time has elapsed, stop waiting and return. The RPC's results will probably not be available yet in this case.

Definition at line 493 of file ClientSession.cc.

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

Friends And Related Function Documentation

friend class OpaqueClientRPC [friend]

Definition at line 217 of file ClientSession.h.

Member Data Documentation

std::weak_ptr<ClientSession> LogCabin::RPC::ClientSession::self [private]

This is used to keep this object alive while there are outstanding RPCs.

Definition at line 253 of file ClientSession.h.

const uint64_t LogCabin::RPC::ClientSession::PING_TIMEOUT_NS [private]

The number of nanoseconds to wait until the client gets suspicious about the server not responding.

After this amount of time elapses, the client will send a ping to the server. If no response is received within another PING_TIMEOUT_NS milliseconds, the session is closed.

TODO(ongaro): How should this value be chosen? Ideally, you probably want this to be set to something like the 99-th percentile of your RPC latency.

TODO(ongaro): How does this interact with TCP?

Definition at line 267 of file ClientSession.h.

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

The event loop that is used for non-blocking I/O.

Definition at line 272 of file ClientSession.h.

const Address LogCabin::RPC::ClientSession::address [private]

The RPC server address provided to the constructor.

Definition at line 277 of file ClientSession.h.

MessageSocketHandler LogCabin::RPC::ClientSession::messageSocketHandler [private]

Receives events from messageSocket.

Definition at line 282 of file ClientSession.h.

Timer LogCabin::RPC::ClientSession::timer [private]

This is used to time out RPCs and sessions when the server is no longer responding.

See Timer.

Definition at line 288 of file ClientSession.h.

std::mutex LogCabin::RPC::ClientSession::mutex [mutable, private]

This mutex protects several members of this class:

Definition at line 298 of file ClientSession.h.

MessageSocket::MessageId LogCabin::RPC::ClientSession::nextMessageId [private]

The message ID to assign to the next RPC.

These start at 0 and increment from there.

Definition at line 304 of file ClientSession.h.

std::unordered_map<MessageSocket::MessageId, Response*> LogCabin::RPC::ClientSession::responses [private]

A map from MessageId to Response objects that is used to store the response to RPCs and look it up for OpaqueClientRPC objects.

The Response objects mapped to must be deleted manually when removed from this map (gcc 4.4 doesn't support mapping to non-copyable objects).

Definition at line 312 of file ClientSession.h.

std::string LogCabin::RPC::ClientSession::errorMessage [private]

If this session is disconnected then this holds the error message.

All new RPCs will be immediately 'ready' with this error message. Otherwise, this is the empty string.

Definition at line 319 of file ClientSession.h.

uint32_t LogCabin::RPC::ClientSession::numActiveRPCs [private]

The number of outstanding RPC requests that have been sent but whose responses have not yet been received.

This does not include ping requests sent by the timer (which aren't real RPCs). This is used to determine when to schedule the timer: the timer is scheduled if numActiveRPCs is non-zero.

Definition at line 328 of file ClientSession.h.

bool LogCabin::RPC::ClientSession::activePing [private]

When numActiveRPCs is > 0, this field indicates that we are waiting for a ping response as evidence that the server is still alive.

When numActiveRPCs = 0, this field is undefined.

Definition at line 335 of file ClientSession.h.

std::unique_ptr<MessageSocket> LogCabin::RPC::ClientSession::messageSocket [private]

The MessageSocket used to send RPC requests and receive RPC responses.

This may be NULL if the socket was never created. In this case, errorMessage will be set.

Definition at line 342 of file ClientSession.h.

Event::Timer::Monitor LogCabin::RPC::ClientSession::timerMonitor [private]

Registers timer with the event loop.

Definition at line 347 of file ClientSession.h.