Vault  4.1
Public Member Functions | Protected Member Functions | Protected Attributes
VClientSession Class Reference

This base class provides the API and services general to the various types of client sessions that may keep a connection alive for a relatively long time, typically with a user's login credentials. More...

#include <vclientsession.h>

List of all members.

Public Member Functions

 VClientSession (const VString &sessionBaseName, VServer *server, const VString &clientType, VSocket *socket, VMessageInputThread *inputThread, VMessageOutputThread *outputThread, const VDuration &standbyTimeLimit, Vs64 maxQueueDataSize)
 Initializes the session object.
virtual void initIOThreads ()
 The code that instantiates the VClientSession must call initIOThreads promptly upon return to finish initialization.
const VStringgetName () const
const VStringgetClientType () const
VMessageInputThreadgetInputThread () const
VMessageOutputThreadgetOutputThread () const
virtual bool isClientOnline () const =0
 Returns true if the session is "on-line", meaning that messages posted to its output queue should be sent; if not on-line, such messages will be queued up to be sent once the client becomes on-line.
virtual bool isClientGoingOffline () const =0
 Returns true fi the session is in the process of shutting down, meaning that messages posted to its output queue should be ignored rather than sent.
virtual void shutdown (VThread *callingThread)
 Triggers a tear-down of the client session, typically in response to an i/o thread ending its run() method.
void postOutputMessage (VMessagePtr message, bool isForBroadcast=false)
 Posts a message to be sent to the client; if the session is using an output thread, the message is posted to the thread's output queue, where it will be sent when the output thread wakes up; if the session is NOT using an output thread, the message is written to the output stream immediately.
void postBroadcastOutputMessage (VMessagePtr message)
 Convenience function for posting a message to the session, when the message is being broadcast to other sessions.
void sendMessageToClient (VMessagePtr message, const VString &sessionLabel, VBinaryIOStream &out)
 Sends a message immediately to the supplied output stream, if the session is in a valid state (not in the middle of shutting down).
virtual const VStringgetClientAddress () const
 Returns a string containing the client's address in address:port form.
virtual VBentoNodegetSessionInfo () const
 Returns a new bento node with attributes describing the session.

Protected Member Functions

void _moveStandbyMessagesToAsyncOutputQueue ()
 Moves messages from mStartupStandbyQueue to the output queue.
int _getOutputQueueSize () const
 Returns the number of messages currently queued on the output thread.
virtual void _postStandbyMessageToAsyncOutputQueue (VMessagePtr message)
 This function can be overridden if the session needs to filter messages being moved from standby queue to output queue.

Protected Attributes

VString mName
 A name for the session to use in logging; built from supplied base name + IP address + port.
VString mLoggerName
 The logger name which we will use when emitting log output.
VMutex mMutex
 A mutex we use to enforce sequential processing of outbound messages, and to protect our task list.
VServermServer
 The server that keeps track of this session.
VString mClientType
 A string distinguishing this type of session.
VString mClientIP
 The client's IP address (could be name or number).
int mClientPort
 The IP port number of the client session.
VString mClientAddress
 The user-visible string we use for logging, contains IP address + port of session.
VMessageInputThreadmInputThread
 The thread that is reading inbound messages from the client.
VMessageOutputThreadmOutputThread
 If using a separate output thread, this is it (may be NULL for sync i/o model).
bool mIsShuttingDown
 True if we are in the process of tearing down the session.

Detailed Description

This base class provides the API and services general to the various types of client sessions that may keep a connection alive for a relatively long time, typically with a user's login credentials.

Its primary functions are to manage the queue of outbound messages, and to ensure that it is not destructed until pending attached threaded tasks complete (see _selfDestruct() mechanism).

Definition at line 45 of file vclientsession.h.


Constructor & Destructor Documentation

VClientSession::VClientSession ( const VString sessionBaseName,
VServer server,
const VString clientType,
VSocket socket,
VMessageInputThread inputThread,
VMessageOutputThread outputThread,
const VDuration standbyTimeLimit,
Vs64  maxQueueDataSize 
)

Initializes the session object.

The i/o threads are neither attached nor started by the constructor; the caller is required to call initIOThreads() promptly upon return. (This is due to being unable to call shared_from_this() in the constructor.)

Parameters:
sessionBaseNameused to prefix unique info to build mName
serverthe server that keeps track of the session
clientTypea string to distinguish the type of session
socketthe socket the session is using
inputThreadthe thread that reads message input on the socket for this session; NULL is allowed but not an expected use case
outputThreadthe thread where message output is posted and processed; NULL is common and indicates the session uses the socket in a synchronous fashion, reading input on the input thread and then writing output immediately on that same thread
standbyTimeLimita time limit for this session to be in startup standby mode after which it will be closed as an error condition; zero means no timeout
maxQueueDataSizethe max num bytes of queued data allowed on this session, after which it will be closed as an error condition; zero means no limit

Definition at line 22 of file vclientsession.cpp.

References VString::chars(), getClientAddress(), mClientAddress, mClientIP, mClientPort, mLoggerName, mMutex, mName, mServer, NULL, and VMutex::setName().


Member Function Documentation

void VClientSession::initIOThreads ( ) [virtual]

The code that instantiates the VClientSession must call initIOThreads promptly upon return to finish initialization.

Smart pointer shared_from_this() cannot be called from the constructor because the object is not managed by a smart pointer at least until return from the constructor and the caller wraps it. This requires us to use a two-phase init with regard to attaching this to the i/o threads.

Definition at line 65 of file vclientsession.cpp.

References VMessageInputThread::attachSession(), VMessageOutputThread::attachSession(), mInputThread, mOutputThread, NULL, and VThread::start().

virtual bool VClientSession::isClientOnline ( ) const [pure virtual]

Returns true if the session is "on-line", meaning that messages posted to its output queue should be sent; if not on-line, such messages will be queued up to be sent once the client becomes on-line.

This must be implemented by the concrete class per its protocols.

Returns:
obvious
virtual bool VClientSession::isClientGoingOffline ( ) const [pure virtual]

Returns true fi the session is in the process of shutting down, meaning that messages posted to its output queue should be ignored rather than sent.

This must be implemented by the concrete class per its protocols.

Returns:
obvious
void VClientSession::shutdown ( VThread callingThread) [virtual]

Triggers a tear-down of the client session, typically in response to an i/o thread ending its run() method.

Parameters:
callingThreadthe thread invoking the shutdown (NULL if n/a)

Definition at line 77 of file vclientsession.cpp.

References VString::chars(), VThread::getName(), mInputThread, mIsShuttingDown, mLoggerName, mMutex, mOutputThread, mServer, NULL, VServer::removeClientSession(), VMessageOutputThread::stop(), and VThread::stop().

void VClientSession::postOutputMessage ( VMessagePtr  message,
bool  isForBroadcast = false 
)

Posts a message to be sent to the client; if the session is using an output thread, the message is posted to the thread's output queue, where it will be sent when the output thread wakes up; if the session is NOT using an output thread, the message is written to the output stream immediately.

If the broadcast flag is specified and session is not "online" then the message is queued and will be sent after the session goes online.

Parameters:
messagethe message to be sent
isForBroadcasttrue if the message is being broadcast; affects queuing behavior if session is in startup standby mode

Definition at line 110 of file vclientsession.cpp.

References VString::chars(), VSocket::close(), VDuration::getDurationString(), VMessageQueue::getQueueDataSize(), isClientGoingOffline(), isClientOnline(), mClientAddress, mIsShuttingDown, mLoggerName, mMutex, mOutputThread, VInstant::NEVER_OCCURRED(), NULL, VMessageQueue::postMessage(), VMessageOutputThread::postOutputMessage(), and VDuration::ZERO().

void VClientSession::postBroadcastOutputMessage ( VMessagePtr  message) [inline]

Convenience function for posting a message to the session, when the message is being broadcast to other sessions.

Calls postOutputMessage() with the broadcast flag set to true. This means the message will be queued if the session is not yet "online".

Definition at line 125 of file vclientsession.h.

References postOutputMessage().

void VClientSession::sendMessageToClient ( VMessagePtr  message,
const VString sessionLabel,
VBinaryIOStream out 
)

Sends a message immediately to the supplied output stream, if the session is in a valid state (not in the middle of shutting down).

The VMessageOutputThread class must use this to send asynchronous output messages in order to guarantee that the test for state and the act of sending is done in an atomic fashion with respect to the session state. We use our mMutex to protect the send operation and the session shutdown procedure from each other. This means that this method must not be called from inside one of our own methods that has the mutex locked.

Parameters:
messagethe message to send; the caller still owns it afterward
sessionLabela label to use in log output, to identify the session
outthe stream to write to

Definition at line 163 of file vclientsession.cpp.

References VString::chars(), isClientGoingOffline(), VMessage::kMessageQueueOpsLevel, mClientAddress, mIsShuttingDown, and mLoggerName.

virtual const VString& VClientSession::getClientAddress ( ) const [inline, virtual]

Returns a string containing the client's address in address:port form.

Returns:
obvious

Definition at line 143 of file vclientsession.h.

References mClientAddress.

VBentoNode * VClientSession::getSessionInfo ( ) const [virtual]

Returns a new bento node with attributes describing the session.

Subclasses may override this, call inherited, and then add their own attributes to the node. It is recommended to make all attributes strings since this is primarily used to display diagnostic information.

Definition at line 173 of file vclientsession.cpp.

References VBentoNode::addInt(), VBentoNode::addS64(), VBentoNode::addString(), VMessageOutputThread::getOutputQueueSize(), VMessageQueue::getQueueDataSize(), VMessageQueue::getQueueSize(), mClientAddress, mClientType, mIsShuttingDown, mName, mOutputThread, and NULL.

void VClientSession::_postStandbyMessageToAsyncOutputQueue ( VMessagePtr  message) [protected, virtual]

This function can be overridden if the session needs to filter messages being moved from standby queue to output queue.

The supplied message must either be posted (call inherited) or released. You can also fabricate a replacement message and post it instead of the supplied message.

Definition at line 213 of file vclientsession.cpp.

References mOutputThread, and VMessageOutputThread::postOutputMessage().


The documentation for this class was generated from the following files:

Copyright ©1997-2014 Trygve Isaacson. All rights reserved. This documentation was generated with Doxygen.