Vault
4.1
|
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>
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 VString & | getName () const |
const VString & | getClientType () const |
VMessageInputThread * | getInputThread () const |
VMessageOutputThread * | getOutputThread () 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 VString & | getClientAddress () const |
Returns a string containing the client's address in address:port form. | |
virtual VBentoNode * | getSessionInfo () 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. | |
VServer * | mServer |
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. | |
VMessageInputThread * | mInputThread |
The thread that is reading inbound messages from the client. | |
VMessageOutputThread * | mOutputThread |
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. |
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.
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.)
sessionBaseName | used to prefix unique info to build mName |
server | the server that keeps track of the session |
clientType | a string to distinguish the type of session |
socket | the socket the session is using |
inputThread | the thread that reads message input on the socket for this session; NULL is allowed but not an expected use case |
outputThread | the 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 |
standbyTimeLimit | a 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 |
maxQueueDataSize | the 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().
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.
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.
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.
callingThread | the 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.
message | the message to be sent |
isForBroadcast | true 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.
message | the message to send; the caller still owns it afterward |
sessionLabel | a label to use in log output, to identify the session |
out | the 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.
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().