mcs::Thread Class Reference

#include <mcs.hh>

Inheritance diagram for mcs::Thread:

Inheritance graph
[legend]

List of all members.


Detailed Description

A class to create separate threads.

This class let you run code in a separate thread. You can derive this class and overload its virtual method run(), this will be the thread body being executed when you start the new thread.

A thread can be started from the parent thread in two ways:

The child thread will always execute three methods: initial(), run(), final(). These are virtual methods, so you can overload them in derived classes. The initial() method can be used to perform initialization tasks. It is useful because it is guarranteed that the start() (or startDetached()) method won't return until the initial() method has returned, so the main thread knows that the separate thread is already running. The run() method is the body of the separate thread execution. A thread can terminate in three different ways:

The final() method can be used to free resources allocated by the separate thread. This method is useful because a thread can terminate either by returning from the run() method, or because it is stopped from another thread. In any case the final() method will be executed in the separate thread, so it can be used to free allocated resources.

If the adress of a parent object has been provided in the constructor call, then it will be notified of thread termination (see notify() method), after the final() method has been executed.

This class provide the state() method which tells in which "state" of its life-cycle a thread is. The value of the state can be one of the follows:

Definition at line 2508 of file mcs.hh.


Public Member Functions

Eventerror ()
 Return last error message.
int id ()
 Returns the Thread object identificator.
Threadoperator= (const Thread &)
 Declared to avoid using of default assignment operator.
Threadparent ()
 Returns the address of the parent.
void start ()
 Start a new thread in the joinable state.
void startDetached (bool selfDelete=false)
 Start a new thread in the detached state.
int state ()
 Return the state of the thread.
void stop ()
 Stop thread execution.
 Thread (int id=0, Thread *parent=NULL)
 Constructor.
 Thread (const Thread &)
 Declared to avoid using of default copy constructor.
virtual ~Thread ()
 Destructor.

Protected Member Functions

virtual void final ()
 Finalization method.
virtual void initial ()
 Initialization method.
virtual void notify (int id, Thread *ref)
 A method called from child threads to notify their termination.
virtual void run ()
 Body of the thread execution.
void set_cancel_state (bool cancel)
 Set cancellation state for current thread.
void test_cancel ()
 Test if a cancellation request is pending.

Protected Attributes

Eventlerror
 Last error.

Private Member Functions

bool checkTerminating ()
 Check if the thread is already terminating (true) or not (false).

Static Private Member Functions

static void cleanup_Handler (void *This)
 Static wrapper around final().
static void * RunThread (void *args)
 Starting point for the separate thread.

Private Attributes

bool detached
 Tell if the thread is to be created in the detached state.
int lid
 General purpose Thread identifier.
Threadlparent
 Reference to parent Thread object, if any is given in the constructor.
int lstate
 State of the object, see state() method.
pthread_t lthrID
 System's thread identifier.
 MCS_DEBUG_ALLOC
bool selfDelete
 Tell if the object should delete himself once the thread is terminated.
Synchro syn_lstate

Constructor & Destructor Documentation

mcs::Thread::Thread ( const Thread  ) 

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::Thread::Thread ( int  id = 0,
Thread parent = NULL 
)

Constructor.

Parameters:
id Thread general purpose identificator, this can be retrieved with the id() method.
parent Address of a parent Thread object, this will be used to notify the thread termination. If NULL is passed no notification will occur.

Definition at line 195 of file Thread.cc.

mcs::Thread::~Thread (  )  [virtual]

Destructor.

You should avoid destroying Thread objects unless you are sure that the separate thread has terminated.

A good choice to destroy Thread objects is to place a "delete" statement inside the notify() method, otherwise you can start the thread in the detached state (with the startDetached() method) and set the "selfDelete" flag to true.

Definition at line 213 of file Thread.cc.


Member Function Documentation

bool mcs::Thread::checkTerminating (  )  [private]

Check if the thread is already terminating (true) or not (false).

Definition at line 413 of file Thread.cc.

void mcs::Thread::cleanup_Handler ( void *  This  )  [static, private]

Static wrapper around final().

This method is automatically called once another thread tries to terminate the thread.

Definition at line 243 of file Thread.cc.

Event * mcs::Thread::error (  ) 

Return last error message.

Definition at line 237 of file Thread.cc.

void mcs::Thread::final (  )  [protected, virtual]

Finalization method.

This method is executed inside the separate thread once the thread has terminated (the run() method has returned or another thread called the stop() method).

You can use this method to perform finalizations like memory cleanup, objects destructions, etc...

Warning:
Don't use this method to destroy the Thread object, instead use the notify() method of parent's thread, or start the thread in the detached state with the "selfDelete" flag set to true.

Definition at line 227 of file Thread.cc.

int mcs::Thread::id (  ) 

Returns the Thread object identificator.

This is a general purpose identificator, it's not used inside the class so user can give it any value (using the constructor).

Returns:
Thread object identificator.

Definition at line 234 of file Thread.cc.

void mcs::Thread::initial (  )  [protected, virtual]

Initialization method.

This method is executed inside the newly created thread once the start() method is called from parent thread.

You can use this method to perform initializations, it is guarranteed that the start() method won't return until this method is completely executed.

Definition at line 224 of file Thread.cc.

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

A method called from child threads to notify their termination.

If the address of a parent thread is provided in the constructor then the child can notify its parent of its termination through this method.

Note that this method will always be ran inside the child thread.

This method can be used to destroy Thread objects once their thread is terminated, for example:

    void MyThread::notify(int id, Thread* ref)
    {
      cout << "Thread " << id << " is terminated." << endl;
      delete ref;
    }

Parameters:
id Thread identifier of the terminating thread.
ref Address of the Thread object whose thread is terminated.

Reimplemented in mcs::Server.

Definition at line 250 of file Thread.cc.

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

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.

Thread * mcs::Thread::parent (  ) 

Returns the address of the parent.

Reimplemented in mcs::UserThread.

Definition at line 240 of file Thread.cc.

void mcs::Thread::run (  )  [protected, virtual]

Body of the thread execution.

When the new thread starts it will automatically execute the code in the run() method. This is the method you should overload in derived class to do the work you need.

Thread will be terminated once this method returns.

Reimplemented in mcs::ThreadFunc, mcs::UserThread, mcs::LocalThread, and mcs::Server.

Definition at line 247 of file Thread.cc.

void * mcs::Thread::RunThread ( void *  args  )  [static, private]

Starting point for the separate thread.

This method calls the appropriate virtual method run().

Definition at line 326 of file Thread.cc.

void mcs::Thread::set_cancel_state ( bool  cancel  )  [protected]

Set cancellation state for current thread.

Definition at line 262 of file Thread.cc.

void mcs::Thread::start (  ) 

Start a new thread in the joinable state.

If you start the thread using this method then you can stop the thread execution using the stop() method.

This method will return only after the initial() method has been executed.

Exceptions:
MCS_FATAL MSG_CALLING_PTHREAD_CREATE;

Definition at line 302 of file Thread.cc.

void mcs::Thread::startDetached ( bool  selfDelete = false  ) 

Start a new thread in the detached state.

If you start the thread using this method then you cannot stop the thread execution, it will terminate by itself.

This method will return only after the initial() method has been executed.

Parameters:
selfDelete If set to true once the thread is terminated the object will be automatically destroyed.
Exceptions:
MCS_FATAL MSG_CALLING_PTHREAD_CREATE;

Definition at line 294 of file Thread.cc.

int mcs::Thread::state (  ) 

Return the state of the thread.

The thread can be if four different states:

Returns:
The state of the thread.

Definition at line 231 of file Thread.cc.

void mcs::Thread::stop (  ) 

Stop thread execution.

This method has an effect only if the thread has been started in the joinable state (using the start() method).

If the child can notify its termination it will do it before this method returns.

Definition at line 383 of file Thread.cc.

void mcs::Thread::test_cancel (  )  [protected]

Test if a cancellation request is pending.

Definition at line 278 of file Thread.cc.


Member Data Documentation

bool mcs::Thread::detached [private]

Tell if the thread is to be created in the detached state.

Definition at line 2547 of file mcs.hh.

Event* mcs::Thread::lerror [protected]

Last error.

Definition at line 2632 of file mcs.hh.

int mcs::Thread::lid [private]

General purpose Thread identifier.

Definition at line 2520 of file mcs.hh.

Thread* mcs::Thread::lparent [private]

Reference to parent Thread object, if any is given in the constructor.

Definition at line 2514 of file mcs.hh.

int mcs::Thread::lstate [private]

State of the object, see state() method.

Definition at line 2523 of file mcs.hh.

pthread_t mcs::Thread::lthrID [private]

System's thread identifier.

Definition at line 2517 of file mcs.hh.

bool mcs::Thread::selfDelete [private]

Tell if the object should delete himself once the thread is terminated.

Definition at line 2550 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