mcs::Synchro Class Reference

#include <mcs.hh>

Inheritance diagram for mcs::Synchro:

Inheritance graph
[legend]

List of all members.


Detailed Description

A simple class to implement "critical sections".

Critical sections are portions of code which cannot be executed by two different threads simultaneously, that is one thread must wait that the other has finished before it can execute it. This is often useful to synchronize threads, or let them access shared variables. Critical sections are implemented in MCS using mutexes. For example if two threads would execute the same code, accessing the same variable, then you must implement a critical section like the following:

  int shared; //A variable shared between threads.
  Synchro syn; //Object used to implement the critical section.

  void function() {
    syn.enter();  //Enter the critical section

    ...           //Manipulate the shared variable

    syn.leave()   //Exit the critical section
  }

In this code, when multiple threads are executing the function at the same time, then it is guaranteed that only one thread will execute the code in the critical section, while the other are suspended (and consume no CPU time).

Anyway developer should pay attention because critical sections, or better a call to enter(), can be a potential deadlock, that is a point at which the thread remain suspended forever. Actually a thread can be killed (or better cancelled) by itself or by other threads only when it is executing a so called "cancellation point", typically I/O operations or some system call (like (sleep()). The system call to lock a mutex is not a cancellation point, so if the thread is suspended waiting to lock a mutex it cannot be cancelled, the only way to kill it is to kill the entire program using signals. On the other hand enter() and tryenter() are cancellation points, so if a thread received a cancellation request while it was suspended, this methods won't return at all. In other words, once a thread is waiting to enter a critical section that is ran by some other thread, it can't be cancelled until the other thread leave the section. For this reason every critical section must be balanced, that is it must have a starting point (using the enter() or tryenter() methods) and an ending point (using the leave() method).

For these reasons developers should design critical sections appropriately, here we'll give some useful hints:

In the first three cases you MUST provide the balancing call to leave(), anyway we recommend not to use any "return" or "goto" instruction inside critical sections. To handle exceptions you can write a code like the following:

    enter();
    try {
       .... //Critical section
    }
    catch (Event e) {
      leave();
      throw e;
    }
    leave();

As you can see there are one call to the enter() method, but two call to leave(), one for each possible exit point in the function. The code above can be easily implemented using the MCS_CRITICAL_SECTION macros. In the fourth case the Synchro object will leave the section automatically;

Critical sections can be nested, that is a thread can enter a critical section any number of time, while the others are waiting. Each thread must also leave critical sections the same number of time. Other threads are allowed to enter a critical section once it is completely free.

Definition at line 2222 of file mcs.hh.


Public Member Functions

int count ()
 Return how many times the current thread has locked the section.
bool enter (int op=1, unsigned int timeout=0)
 Enter, or try to enter a critical section.
int leave ()
 Leave a critical section.
Synchrooperator= (const Synchro &)
 Declared to avoid using of default assignment operator.
 Synchro ()
 Constructor.
 Synchro (const Synchro &)
 Declared to avoid using of default copy constructor.
void synchronize (bool setactive)
 Enable or disable the synchronization feature.
bool tryenter (unsigned int timeout=0)
 Wrapper around enter(), using op=MCS_SYNCHRO_TRY_LOCK if the parameter is 0, op=MCS_SYNCHRO_TRY_TIMED otherwise.
 ~Synchro ()
 Destructor.

Private Attributes

struct
_pthread_cleanup_buffer 
_buf
 Structure used to implement the cleanup handler.
pthread_mutexattr_t attr
 Attribute of the mutex (PTHREAD_MUTEX_RECURSIVE_NP).
int Count
 How many time the Mutex has been locked, or a thread entered a critical section.
bool isActive
 Whether this object is a "dummy" object or not.
 MCS_DEBUG_ALLOC
pthread_mutex_t mutex
 The mutex used to do the job.

Constructor & Destructor Documentation

mcs::Synchro::Synchro ( const Synchro  ) 

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::Synchro::Synchro (  ) 

Constructor.

This contructor initialize a "dummy" object, that is an object with synchronization disabled. To enable it call synchronize().

That is because several class are derived from Synchro, but not all objects of those classes needs to be synchronized.

Definition at line 37 of file Thread.cc.

mcs::Synchro::~Synchro (  ) 

Destructor.

Definition at line 49 of file Thread.cc.


Member Function Documentation

int mcs::Synchro::count (  ) 

Return how many times the current thread has locked the section.

Reimplemented in mcs::Dynamic_Array< BASE >, mcs::Record, mcs::Dynamic_Array< mcs::Data >, mcs::Dynamic_Array< int >, and mcs::Dynamic_Array< mcs::Record >.

Definition at line 58 of file Thread.cc.

bool mcs::Synchro::enter ( int  op = 1,
unsigned int  timeout = 0 
)

Enter, or try to enter a critical section.

If other threads are locking the critical section the behaviour of this method depends on the first parameter:

If you specify MCS_SYNCHRO_LOCK as first parameter, then the thread must lock the section before it can do anything else. Once the section has been locked this method will return, or the thread will be cancelled (this method won't return) if a cancellation request arrived in the meanwhile.

Parameters:
op A code specifying the behaviour in case the section is already locked;
timeout Use this only if op=MCS_SYNCHRO_TRY_TIMED, the timeout in milliseconds after which a try to lock the section will fail;
Returns:
True if the section has been locked, false otherwise. If op=MCS_SYNCHRO_LOCK this method will always return true or never return.

Definition at line 87 of file Thread.cc.

int mcs::Synchro::leave (  ) 

Leave a critical section.

Leave a critical section (unlock the mutex). There must be a call to this method for each exit point in the critical section.

Returns:
How many times the thread should call this method to completely unlock the section.

Definition at line 131 of file Thread.cc.

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

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::Synchro::synchronize ( bool  setactive  ) 

Enable or disable the synchronization feature.

You must enable or disable the synchronization feature before callling any other method of this class, otherwise an exception will be thrown.

Parameters:
setactive If false this became a "dummy" object, that is every call returns immediately without being synchronized.

Definition at line 62 of file Thread.cc.

bool mcs::Synchro::tryenter ( unsigned int  timeout = 0  ) 

Wrapper around enter(), using op=MCS_SYNCHRO_TRY_LOCK if the parameter is 0, op=MCS_SYNCHRO_TRY_TIMED otherwise.

Definition at line 149 of file Thread.cc.


Member Data Documentation

struct _pthread_cleanup_buffer mcs::Synchro::_buf [read, private]

Structure used to implement the cleanup handler.

Definition at line 2228 of file mcs.hh.

pthread_mutexattr_t mcs::Synchro::attr [private]

Attribute of the mutex (PTHREAD_MUTEX_RECURSIVE_NP).

Definition at line 2234 of file mcs.hh.

int mcs::Synchro::Count [private]

How many time the Mutex has been locked, or a thread entered a critical section.

Definition at line 2237 of file mcs.hh.

bool mcs::Synchro::isActive [private]

Whether this object is a "dummy" object or not.

Definition at line 2240 of file mcs.hh.

pthread_mutex_t mcs::Synchro::mutex [private]

The mutex used to do the job.

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