Vault  4.1
Public Member Functions
VListenerThread Class Reference

A VListenerThread is a thread whose run() method listens on a socket and creates a new VSocket for each incoming connection and a VSocketThread object to manage each such VSocket. More...

#include <vlistenerthread.h>

Inheritance diagram for VListenerThread:
VThread

List of all members.

Public Member Functions

 VListenerThread (const VString &threadBaseName, bool deleteSelfAtEnd, bool createDetached, VManagementInterface *manager, int portNumber, const VString &bindAddress, VSocketFactory *socketFactory, VSocketThreadFactory *threadFactory, VClientSessionFactory *sessionFactory=NULL, bool initiallyListening=true)
 Constructs the listener thread to listen on a specified port.
virtual ~VListenerThread ()
 Destructor.
virtual void stop ()
 Stops the thread; for VListenerThread this also stops listening and stops the socket threads (threads running connections established from this listener).
virtual void run ()
 Run method, listens and then goes into a loop that accepts incoming connections until the thread has been externally stopped.
void socketThreadEnded (VSocketThread *socketThread)
 Handles bookkeeping upon the termination of a VSocketThread that was previously created.
int getPortNumber () const
 Returns the port number we're listening on.
VSocketInfoVector enumerateActiveSockets ()
 Returns a list of information about all of this listener's current socket threads; note that because this information is so dynamic, the caller receives a snapshot of the information, which may be stale at any moment.
void stopSocketThread (VSocketID socketID, int localPortNumber)
 Attempts to stop the specified socket thread that was created by this listener.
void stopAllSocketThreads ()
 Attempts to stop all socket threads that were created by this listener.
void startListening ()
 Sets the thread to listen if it isn't already.
void stopListening ()
 Sets the thread to stop listening if it's currently listening.
bool isListening () const
 Returns true if the thread is in listening mode.

Detailed Description

A VListenerThread is a thread whose run() method listens on a socket and creates a new VSocket for each incoming connection and a VSocketThread object to manage each such VSocket.

You control the kind of VSocket- and VSocketThread-derived subclass that is instantiated by passing a factory object for each thing in the VListenerThread constructor.

Implementing a listener is trivially simple:

1. Define your VSocketThread subclass and override the run() method. In this method you will probably create a VIOStream based on a VSocketStream based on the VSocketThread's mSocket. Do reads on the stream to read requests from the client, and do writes on the stream to write your responses to the client. When you see that this->isStopped() returns true, return from your run() method.

2. Define your VSocketThreadFactory subclass and override the createThread() method to create an instance of your VSocketThread subclass.

3. When you want to shut down the listener, call its stop() method.

That's it!

Definition at line 50 of file vlistenerthread.h.


Constructor & Destructor Documentation

VListenerThread::VListenerThread ( const VString threadBaseName,
bool  deleteSelfAtEnd,
bool  createDetached,
VManagementInterface manager,
int  portNumber,
const VString bindAddress,
VSocketFactory socketFactory,
VSocketThreadFactory threadFactory,
VClientSessionFactory sessionFactory = NULL,
bool  initiallyListening = true 
)

Constructs the listener thread to listen on a specified port.

If you are using a VManagementInterface to manage your server behavior, you can supply it to the VListenerThread so that it can let the manager know when the thread starts and ends.

Parameters:
threadBaseNamea distinguishing base name for the thread, useful for debugging purposes; the thread name will be composed of this and the socket's IP address and port
deleteSelfAtEnd
See also:
VThread
Parameters:
createDetached
See also:
VThread
Parameters:
managerthe object that receives notifications for this thread, or NULL
portNumberthe port number to listen on
bindAddressif empty, the socket will bind to INADDR_ANY (usually a good default); if a value is supplied the socket will bind to the supplied IP address (can be useful on a multi-homed server)
socketFactorya factory for creating a VSocket for each incoming connection
threadFactorya factory for creating a VSocketThread for each incoming connection, if sessionFactory is not supplied (threadFactory OR sessionFactory should be NULL)
sessionFactorya factory that will create a session object for each incoming connection if not using the threadFactory (threadFactory OR sessionFactory should be NULL)
initiallyListeningtrue if the thread should be listening when it first starts; false means it won't listen until you call startListening()

Definition at line 24 of file vlistenerthread.cpp.


Member Function Documentation

void VListenerThread::run ( ) [virtual]

Run method, listens and then goes into a loop that accepts incoming connections until the thread has been externally stopped.

Each new VSocketThread is kept track of internally.

Implements VThread.

Definition at line 54 of file vlistenerthread.cpp.

References VThread::isRunning(), VDuration::SECOND(), and VThread::sleep().

void VListenerThread::socketThreadEnded ( VSocketThread socketThread)

Handles bookkeeping upon the termination of a VSocketThread that was previously created.

The object notifies us of its termination.

Parameters:
socketThreadthe thread that ended

Definition at line 64 of file vlistenerthread.cpp.

References VThread::getName().

int VListenerThread::getPortNumber ( ) const

Returns the port number we're listening on.

Returns:
the port number

Definition at line 75 of file vlistenerthread.cpp.

VSocketInfoVector VListenerThread::enumerateActiveSockets ( )

Returns a list of information about all of this listener's current socket threads; note that because this information is so dynamic, the caller receives a snapshot of the information, which may be stale at any moment.

For example, by the time you look at the information, it may refer to sockets that have since been closed.

Definition at line 79 of file vlistenerthread.cpp.

References VThread::getName().

void VListenerThread::stopSocketThread ( VSocketID  socketID,
int  localPortNumber 
)

Attempts to stop the specified socket thread that was created by this listener.

Throws a VException if that socket thread no longer exists. These two parameters are used to identify the socket because the sock ID can re-used by another socket after a given socket is closed.

Parameters:
socketIDthe socket ID
localPortNumberthe socket's port number

Definition at line 92 of file vlistenerthread.cpp.

References VSocketThread::closeAndStop(), VThread::getName(), VSocket::getPortNumber(), VSocketThread::getSocket(), and VSocket::getSockID().

void VListenerThread::startListening ( ) [inline]

Sets the thread to listen if it isn't already.

If the thread is currently listening, nothing changes. If it's sleeping in non-listening mode, next time through the loop it will start listening again.

Definition at line 145 of file vlistenerthread.h.

void VListenerThread::stopListening ( ) [inline]

Sets the thread to stop listening if it's currently listening.

If the thread is not currently listening, nothing changes. If it's running in the listen loop, the loop will bail out within a few seconds, and go into non-listening mode until a call to startListening() is made.

Definition at line 152 of file vlistenerthread.h.

bool VListenerThread::isListening ( ) const [inline]

Returns true if the thread is in listening mode.

Note that this doesn't mean it's actually listening at this moment, but rather whether it is set to listen; during transition phases between listening and not listening, this flag may reflect the pending state rather than the current state.

Definition at line 159 of file vlistenerthread.h.


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.