mcs::Server Class Reference

#include <mcs.hh>

Inheritance diagram for mcs::Server:

Inheritance graph
[legend]

List of all members.


Detailed Description

Main server class for a MCS-based application.

Every MCS-based application must use an object of this class, or a derived one as main server.

When started it create a LocalThread object (using the newLocalThread() method), then it acts like an usual TCP server listening on a specified port and waiting for a connection. When a new connection arrives it create a new UserThread object (using the newUserThread() method) that runs on a separate thread and handle the connection. This object will terminate spotaneously and destroy himself if a FATAL error is raised or if the LocalThread terminate and the Env.cl_root_kills_mcs variable is true. The main program can also terminate this object by calling its exit() method. Remember that you must create the Server object in the heap memory and never try to destroy it, it will destroy by himself, That is because it is an object derived from Thread (see Thread).

To customize MCS you should derive the UserThread and/or LocalThread classes, and use a server object which istantiate the derived classes instead of the standard ones. For this reason, the newLocalThread() and newUserThread() methods are virtual, so you can derive the Server class and overload these methods to use the UserThread and/or LocalThread derived classes. Suppose you implemented a class named MyClient derived from UserThread, and a class named MyLocal derived from LocalThread, here's an example of the code you should write to correctly derive the Server class:

  class MyServer: public Server
  {
  public:
    MyServer(Env* lenv): Server(lenv) {}

    ~MyServer() {}

    UserThread* newUserThread(int lID, int newsock) {
      return new MyClient(this, lID, server);
    }

    LocalThread* newLocalThread() {
      return new MyLocal(this, "LLL");
    }
  };

  MyServer* srv = new MyServer(...);

Since overriding the newLocalThread() and newUserThread() methods are the only reason to derive the Server class, we provide an easiest way to reach the same goal, that is using the MCS_CUSTOM_SERVER macro. The code shown above can be substituted with:

  MCS_CUSTOM_SERVER(MyServer, MyClient, MyLocal);
  MyServer* srv = new MyServer(...);

To create a working server you must first create an Env object containing all information needed to run the server, then you can create the server object. A typical usage is as follows:

  //Define a new server class, with derived UserThread and
  //LocalThread classes.
  MCS_CUSTOM_SERVER(MyServer, MyClient, MyLocal);

  //Create a Env object which reads the configuration file.
  Env* env=new Env("myApp");

  //Create a server object...
  MyServer* srv = new MyServer(env);

  //...and start it.
  srv->start();

We provide a facility function (mcsstart()) that perform all these steps. You can substitute the code above with:

  Env* = mcsstart("myApp");

This class also provide access to the "callback functions" customizing facilities. Using callback functions you can customize the server behaviour without deriving the UserThread class (as you would do if you want to use the "hooks" methods, instead of callback). Callback functions are C++ functions (not methds!) with well determined parameters and return value, which are called automatically by the "hooks" (note that if you overload those method the callback functions won't be called anymore). In the Server class there are a number of variables whose name start with "cb_" or "cbwa_", which are pointer to functions. There are one "cb_" and one "cbwa_" variable for each "hook" method (described in the relative classes LocalThread and UserThread).

Suppose you want a function to be executed each time a line of log is written, you could of course derive the LocalThread class and overload the hk_log() method. Another way is to set a callback function for that hook, here's an example:

  //Define the callback function
  void myCallbackFunction(int logID, int  tID, Event e)
  {
    //... Do the job ...
  }

  //Istantiate an Env and a  Server (or a derived) object.
  Env* env = new Env("myApp");
  Server* srv = new Server(env);

  //Before starting the server set the appropriate callback variable.
  srv->cb_log = &myCallbackFunction;

  //Finally start the server
  srv->start;

Note that the callback function has the same parameters and return values as the corresponding hook method. Note also that here we used the "cb_log" variable, there is also a "cbwa_log" variable but this, as well as all the other "cbwa_" variables, are pointers to void functions without arguments (the "wa" means just "without arguments").

You can use callback functions instead

See also:
LocalThread

UserThread

Env

Definition at line 7189 of file mcs.hh.


Public Member Functions

RecordSetgetAll_ClientInfo ()
 Return a RecordSet object containing informations about all clients connections.
Serveroperator= (const Server &)
 Declared to avoid using of default assignment operator.
 Server (Env *lenv)
 Constructor.
 Server (const Server &)
 Declared to avoid using of default copy constructor.
 ~Server ()
 Destructor.

Public Attributes

RetValue(* cb_auth )(int &, bool &)
 Pointer to a callback function, called by hk_auth().
RetValue(* cb_connect )()
 Pointer to a callback function, called by hk_connect().
void(* cb_disconnect )()
 Pointer to a callback function, called by hk_disconnect().
RetValue(* cb_exec )(CommandParser *, bool &_executed)
 Pointer to a callback function, called by hk_exec().
void(* cb_log )(UserThread *p, Event e)
 Pointer to a callback function, called by hk_log().
void(* cb_newClient )(int i)
 Pointer to a void callback function, called by hk_newClient().
void(* cb_postexec )(CommandParser *, RetValue)
 Pointer to a callback function, called by hk_postexec().
void(* cbwa_auth )()
 Pointer to a void callback function without arguments, called by hk_auth().
void(* cbwa_connect )()
 Pointer to a void callback function without arguments, called by hk_connect().
void(* cbwa_exec )()
 Pointer to a void callback function without arguments, called by hk_exec().
void(* cbwa_log )()
 Pointer to a void callback function without arguments, called by hk_log().
void(* cbwa_postexec )()
 Pointer to a void callback function without arguments, called by hk_postexec().
Record dispatch
 Record of Data objects to be sent to various threads.

Protected Member Functions

virtual void hk_newClient (int i)
 Virtual method called when a new user connects to the server.
void killAllClients ()
 Kills all UserThread and the LocalThread objects.
void killClient (int i)
 Kill client with specified identifier.
void newClient (int newsock)
 Search for a free identifier and creates a new UserThread object.
virtual LocalThreadnewLocalThread ()
 Wrapper around LocalThread constructors.
virtual UserThreadnewUserThread (int lID, int newsock)
 Wrapper around UserThread constructors.
void notify (int id, Thread *ref)
 Called when a child thread terminate, used to free resources.

Private Member Functions

int find_free_id ()
 Search for a free client identifier when a new client tries to connect. See Env.max_users.
void run ()
 Server thread body.

Private Attributes

 MCS_DEBUG_ALLOC
UserThread ** pClient
 Array of pointers to UserThread objects.

Friends

class LocalThread

Constructor & Destructor Documentation

mcs::Server::Server ( const Server  ) 

Declared to avoid using of default copy constructor.

Warning:
This constructor is declared but not implemented. If you try to use it you will get a compilation error.

mcs::Server::Server ( Env lenv  ) 

Constructor.

Parameters:
lenv Address to a valid Env object;
See also:
Env

Definition at line 32 of file Server.cc.

mcs::Server::~Server (  ) 

Destructor.

Definition at line 67 of file Server.cc.


Member Function Documentation

int mcs::Server::find_free_id (  )  [private]

Search for a free client identifier when a new client tries to connect. See Env.max_users.

Definition at line 185 of file Server.cc.

RecordSet * mcs::Server::getAll_ClientInfo (  ) 

Return a RecordSet object containing informations about all clients connections.

This method return the address of a RecordSet object allocated in the heap. Users should delete this object after use.

Definition at line 237 of file Server.cc.

void mcs::Server::hk_newClient ( int  i  )  [protected, virtual]

Virtual method called when a new user connects to the server.

This method calls the cb_newClient() callback functions if defined. If you overload this method the callback functions won't be called anymore.

This method work the same as the hk_connect() virtual method, but it is used inside the Server class instead of UserThread.

If you overload this method the callback functions won't be called anymore.

Parameters:
i Index of the newly created UserThread object.

Definition at line 290 of file Server.cc.

void mcs::Server::killAllClients (  )  [protected]

Kills all UserThread and the LocalThread objects.

Definition at line 227 of file Server.cc.

void mcs::Server::killClient ( int  i  )  [protected]

Kill client with specified identifier.

Definition at line 217 of file Server.cc.

void mcs::Server::newClient ( int  newsock  )  [protected]

Search for a free identifier and creates a new UserThread object.

Definition at line 200 of file Server.cc.

LocalThread * mcs::Server::newLocalThread (  )  [protected, virtual]

Wrapper around LocalThread constructors.

This method can be overload to istantiate object of a LocalThread derived class.

Definition at line 284 of file Server.cc.

UserThread * mcs::Server::newUserThread ( int  lID,
int  newsock 
) [protected, virtual]

Wrapper around UserThread constructors.

Parameters are passed directly to the constructor. This method can be overload to istantiate object of a UserThread derived class.

Definition at line 279 of file Server.cc.

void mcs::Server::notify ( int  id,
Thread ref 
) [protected, virtual]

Called when a child thread terminate, used to free resources.

Note:
If LocalThread object notify its termination and the Env.cl_root_kills_mcs option is true then this method will call Server.exit(), terminating the ewhole server.

Reimplemented from mcs::Thread.

Definition at line 164 of file Server.cc.

Server& mcs::Server::operator= ( const Server  ) 

Declared to avoid using of default assignment operator.

Warning:
This operator is declared but not implemented. If you try to use it you will get a compilation error.

void mcs::Server::run (  )  [private, virtual]

Server thread body.

Initialize the server socket, then wait for a new connection. When a new connection arrives call the virtual newUserThread() method to istantiate a new client thread that can handle that client connection.

Reimplemented from mcs::Thread.

Definition at line 86 of file Server.cc.


Member Data Documentation

RetValue(* mcs::Server::cb_auth)(int &, bool &)

Pointer to a callback function, called by hk_auth().

RetValue(* mcs::Server::cb_connect)()

Pointer to a callback function, called by hk_connect().

void(* mcs::Server::cb_disconnect)()

Pointer to a callback function, called by hk_disconnect().

RetValue(* mcs::Server::cb_exec)(CommandParser *, bool &_executed)

Pointer to a callback function, called by hk_exec().

void(* mcs::Server::cb_log)(UserThread *p, Event e)

Pointer to a callback function, called by hk_log().

void(* mcs::Server::cb_newClient)(int i)

Pointer to a void callback function, called by hk_newClient().

void(* mcs::Server::cb_postexec)(CommandParser *, RetValue)

Pointer to a callback function, called by hk_postexec().

void(* mcs::Server::cbwa_auth)()

Pointer to a void callback function without arguments, called by hk_auth().

void(* mcs::Server::cbwa_connect)()

Pointer to a void callback function without arguments, called by hk_connect().

void(* mcs::Server::cbwa_exec)()

Pointer to a void callback function without arguments, called by hk_exec().

void(* mcs::Server::cbwa_log)()

Pointer to a void callback function without arguments, called by hk_log().

void(* mcs::Server::cbwa_postexec)()

Pointer to a void callback function without arguments, called by hk_postexec().

Record mcs::Server::dispatch

Record of Data objects to be sent to various threads.

Definition at line 7344 of file mcs.hh.

UserThread** mcs::Server::pClient [private]

Array of pointers to UserThread objects.

Definition at line 7195 of file mcs.hh.


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

MCS (My Customizable Server) ver. 0.3.3-alpha3
Documentation generated on Thu Mar 22 13:22:23 UTC 2012