Main server class for a MCS-based application. More...

#include <mcs.hh>

Inheritance diagram for mcs::Server:

Public Member Functions
RecordSet *	getAll_ClientInfo ()
	Return a RecordSet object containing informations about all clients connections. More...

Server &	operator= (const Server &)
	Declared to avoid using of default assignment operator. More...

	Server (const Server &)
	Declared to avoid using of default copy constructor. More...

	Server (Env *lenv)
	Constructor. More...

	~Server ()
	Destructor. More...

Public Member Functions inherited from mcs::BaseThread
	BaseThread (const BaseThread &)
	Declared to avoid using of default copy constructor. More...

	BaseThread (Thread *parent, int lID)
	Constructor invoked from ClienThread objects. More...

	BaseThread (Thread parent, const char ltID)
	Constructor invoked from other objects. More...

int	chkExt (string &s)
	Check if an external program or script is registered in the configuration file. More...

BaseThread &	operator= (const BaseThread &)
	Declared to avoid using of default assignment operator. More...

const char *	tid ()
	Return the thread identifier. More...

	~BaseThread ()
	Destructor. More...

Public Member Functions inherited from mcs::Thread
Event *	error ()
	Return last error message. More...

int	id ()
	Returns the Thread object identificator. More...

Thread *	parent ()
	Returns the address of the parent. More...

void	start ()
	Start a new thread in the joinable state. More...

void	startDetached (bool selfDelete=false)
	Start a new thread in the detached state. More...

int	state ()
	Return the state of the thread. More...

void	stop ()
	Stop thread execution. More...

	Thread (int id=0, Thread *parent=NULL)
	Declared to avoid using of default copy constructor. More...

virtual	~Thread ()
	Destructor. More...

Public Attributes
RetValue(*	cb_auth )(int &, bool &)
	Pointer to a callback function, called by hk_auth(). More...

RetValue(*	cb_connect )()
	Pointer to a callback function, called by hk_connect(). More...

void(*	cb_disconnect )()
	Pointer to a callback function, called by hk_disconnect(). More...

RetValue(*	cb_exec )(CommandParser *, bool &_executed)
	Pointer to a callback function, called by hk_exec(). More...

void(*	cb_log )(UserThread *p, Event e)
	Pointer to a callback function, called by hk_log(). More...

void(*	cb_newClient )(int i)
	Pointer to a void callback function, called by hk_newClient(). More...

void(*	cb_postexec )(CommandParser *, RetValue)
	Pointer to a callback function, called by hk_postexec(). More...

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

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

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

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

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

Record	dispatch
	Record of Data objects to be sent to various threads. More...

Protected Member Functions
virtual void	hk_newClient (int i)
	Virtual method called when a new user connects to the server. More...

void	killAllClients ()
	Kills all UserThread and the LocalThread objects. More...

void	killClient (int i)
	Kill client with specified identifier. More...

void	newClient (int newsock)
	Search for a free identifier and creates a new UserThread object. More...

virtual LocalThread *	newLocalThread ()
	Wrapper around LocalThread constructors. More...

virtual UserThread *	newUserThread (int lID, int newsock)
	Wrapper around UserThread constructors. More...

void	notify (int id, Thread *ref)
	Called when a child thread terminate, used to free resources. More...

Protected Member Functions inherited from mcs::BaseThread
RetValue	Log (Event e)
	Logging facility. More...

Protected Member Functions inherited from mcs::Thread
virtual void	final ()
	Finalization method. More...

virtual void	initial ()
	Initialization method. More...

void	set_cancel_state (bool cancel)
	Set cancellation state for current thread. More...

void	test_cancel ()
	Test if a cancellation request is pending. More...

Private Member Functions
int	find_free_id ()
	Search for a free client identifier when a new client tries to connect. See Env.max_users. More...

void	run ()
	Server thread body. More...

Private Attributes
	MCS_DEBUG_ALLOC

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

Friends
class	LocalThread

Additional Inherited Members
Static Public Member Functions inherited from mcs::BaseThread
static int	fileType (string fn)
	Determine the file type of an external program or script. More...

static int	spawn (string fn, string pars, string wpath=".", string thrID="x", string user="x", string pass="x", string dbname="x", string fout="out", string ferr="err")
	Execute an external program or script in a dedicated environment. More...

Protected Attributes inherited from mcs::Thread
Event *	lerror
	Last error. More...

Static Protected Attributes inherited from mcs::BaseThread
static Env *	env
	Pointer to the actual Env object, this can be seen in all threaded object. More...

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 7166 of file mcs.hh.

Constructor & Destructor Documentation

◆ Server() [1/2]

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.

◆ Server() [2/2]

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.

◆ ~Server()

mcs::Server::~Server ( )

Destructor.

Definition at line 67 of file Server.cc.

Member Function Documentation

◆ find_free_id()

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.

◆ getAll_ClientInfo()

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.

◆ hk_newClient()

void mcs::Server::hk_newClient ( int i )

protectedvirtual

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.

◆ killAllClients()

void mcs::Server::killAllClients ( )

protected

Kills all UserThread and the LocalThread objects.

Definition at line 227 of file Server.cc.

◆ killClient()

void mcs::Server::killClient ( int i )

protected

Kill client with specified identifier.

Definition at line 217 of file Server.cc.

◆ newClient()

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.

◆ newLocalThread()

LocalThread * mcs::Server::newLocalThread ( )

protectedvirtual

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.

◆ newUserThread()

UserThread * mcs::Server::newUserThread	(	int	lID,
		int	newsock
	)

protectedvirtual

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.

◆ notify()

void mcs::Server::notify	(	int	id,
		Thread *	ref
	)

protectedvirtual

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.

◆ operator=()

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.

◆ run()

void mcs::Server::run ( )

privatevirtual

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

◆ cb_auth

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

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

Definition at line 7292 of file mcs.hh.

◆ cb_connect

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

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

Definition at line 7289 of file mcs.hh.

◆ cb_disconnect

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

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

Definition at line 7301 of file mcs.hh.

◆ cb_exec

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

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

Definition at line 7295 of file mcs.hh.

◆ cb_log

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

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

Definition at line 7286 of file mcs.hh.

◆ cb_newClient

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

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

Definition at line 7319 of file mcs.hh.

◆ cb_postexec

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

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

Definition at line 7298 of file mcs.hh.

◆ cbwa_auth

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

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

Definition at line 7310 of file mcs.hh.

◆ cbwa_connect

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

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

Definition at line 7307 of file mcs.hh.

◆ cbwa_exec

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

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

Definition at line 7313 of file mcs.hh.

◆ cbwa_log

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

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

Definition at line 7304 of file mcs.hh.

◆ cbwa_postexec

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

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

Definition at line 7316 of file mcs.hh.

◆ dispatch

Record mcs::Server::dispatch

Record of Data objects to be sent to various threads.

Definition at line 7322 of file mcs.hh.

◆ pClient

UserThread** mcs::Server::pClient

private

Array of pointers to UserThread objects.

Definition at line 7172 of file mcs.hh.

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

Public Member Functions

Public Attributes

Protected Member Functions

Private Member Functions

Private Attributes

Friends

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ Server() [1/2]

◆ Server() [2/2]

◆ ~Server()

Member Function Documentation

◆ find_free_id()

◆ getAll_ClientInfo()

◆ hk_newClient()

◆ killAllClients()

◆ killClient()

◆ newClient()

◆ newLocalThread()

◆ newUserThread()

◆ notify()

◆ operator=()

◆ run()

Member Data Documentation

◆ cb_auth

◆ cb_connect

◆ cb_disconnect

◆ cb_exec

◆ cb_log

◆ cb_newClient

◆ cb_postexec

◆ cbwa_auth

◆ cbwa_connect

◆ cbwa_exec

◆ cbwa_log

◆ cbwa_postexec

◆ dispatch

◆ pClient