This class provides a mechanism to run two threads alternately. More...

#include <AlternateThreadPT.hxx>

Collaboration diagram for YACS::BASES::AlternateThreadPT:

Public Types
enum	ThreadStatus { UNEXISTING, NORMAL_CYCLE, TERMINATION_REQUESTED, READY_TO_JOIN }

Public Member Functions
	AlternateThreadPT ()

virtual	~AlternateThreadPT ()

void	start ()
	Create and launch the slave thread. More...

virtual void	signalSlaveAndWait ()
	Block the master thread and release the slave thread. More...

void	terminateSlaveThread ()
	Terminate the slave thread. More...

virtual void	signalMasterAndWait ()
	Block the slave thread and release the master thread. More...

bool	isTerminationRequested () const
	Return true if the master requested the slave thread termination. More...

ThreadStatus	getThreadStatus () const
	Return the thread status. More...

Protected Member Functions
virtual void	run ()=0
	This method must be implemented in subclasses and will be run in the slave thread. More...

Private Member Functions
void	signalAndWait ()

Static Private Member Functions
static void *	runThread (void *instance)

static void	threadCleanupFct (void *instance)

Private Attributes
pthread_t	_threadId

ThreadStatus	_threadStatus

pthread_cond_t	_pingPongCond

pthread_mutex_t	_pingPongMutex

Detailed Description

This class provides a mechanism to run two threads alternately.

Alternate threads can be necessary when two pieces of code must run alternately and communicate but are difficult or impossible to synchronize explicitly (e.g. asynchronous algorithms in optimizer loop). This class guarantees that the two threads NEVER run concurrently, so no lock mechanism is necessary when sharing data between them.

The two threads are called "master thread" and "slave thread". The master thread is the one that calls the method start() and that will continue to run after the destruction of this object. The slave thread is created when the method start() is called. It will run the code in the method run() and will be destroyed when the master thread calls terminateSlaveThread() or at the destruction of this object.

When the master thread calls start(), it will block and the slave thread will begin to execute the code in the method run(). The two threads can then alternate by calling the method signalMasterAndWait() (in the slave thread) and signalSlaveAndWait() (in the master thread). Finally, the master thread must call terminateSlaveThread() to terminate the slave thread. There is no explicit mechanism for the slave thread to request its own termination, but this can be done with an external flag (see the pool object in OptimizerLoop for instance).

This class is purely virtual. Subclasses must implement the run() method that will be executed in the slave thread.

Definition at line 55 of file AlternateThreadPT.hxx.

Member Enumeration Documentation

enum YACS::BASES::AlternateThreadPT::ThreadStatus

Enumerator
UNEXISTING
NORMAL_CYCLE
TERMINATION_REQUESTED
READY_TO_JOIN

Definition at line 58 of file AlternateThreadPT.hxx.

58 {UNEXISTING, NORMAL_CYCLE, TERMINATION_REQUESTED, READY_TO_JOIN};

Constructor & Destructor Documentation

AlternateThreadPT::AlternateThreadPT ( )

Definition at line 31 of file AlternateThreadPT.cxx.

References _pingPongCond, _pingPongMutex, and YASSERT.

   : _threadStatus(UNEXISTING)
 {
   YASSERT(pthread_cond_init(&_pingPongCond, NULL) == 0)
   YASSERT(pthread_mutex_init(&_pingPongMutex, NULL) == 0)
 }

AlternateThreadPT::~AlternateThreadPT ( )

virtual

Definition at line 38 of file AlternateThreadPT.cxx.

References _pingPongCond, _pingPongMutex, terminateSlaveThread(), and YASSERT.

 {
   try {
     terminateSlaveThread();
     YASSERT(pthread_mutex_destroy(&_pingPongMutex) == 0)
     YASSERT(pthread_cond_destroy(&_pingPongCond) == 0)
   } catch (const exception & e) {
     cerr << "Exception happened in AlternateThreadPT destructor: " << e.what() << endl;
   } catch (...) {
     cerr << "Unknown exception happened in AlternateThreadPT destructor." << endl;
   }
 }

Member Function Documentation

AlternateThreadPT::ThreadStatus AlternateThreadPT::getThreadStatus ( ) const

Return the thread status.

Definition at line 134 of file AlternateThreadPT.cxx.

References _threadStatus.

 {
   return _threadStatus;
 }

bool AlternateThreadPT::isTerminationRequested ( ) const

Return true if the master requested the slave thread termination.

Definition at line 129 of file AlternateThreadPT.cxx.

References _threadStatus, and TERMINATION_REQUESTED.

 {
   return (_threadStatus == TERMINATION_REQUESTED);
 }

virtual void YACS::BASES::AlternateThreadPT::run ( )

protectedpure virtual

This method must be implemented in subclasses and will be run in the slave thread.

The slave thread must call signalMasterAndWait() when necessary to give the control back to the master thread. When returning from this method, the slave thread MUST check for an eventual termination request (with the method isTerminationRequested()). If the termination is requested, the slave thread must perform any necessary cleanup and finish as soon as possible.

Referenced by runThread().

void * AlternateThreadPT::runThread ( void * instance )

staticprivate

Definition at line 139 of file AlternateThreadPT.cxx.

References _pingPongMutex, _threadStatus, DEBTRACE, NORMAL_CYCLE, run(), threadCleanupFct(), and YASSERT.

Referenced by start().

 {
   try {
     AlternateThreadPT * instanceCst = (AlternateThreadPT *)instance;
     YASSERT(pthread_mutex_lock(&instanceCst->_pingPongMutex) == 0)
     DEBTRACE("Slave thread is now running")
     instanceCst->_threadStatus = NORMAL_CYCLE;
     pthread_cleanup_push(threadCleanupFct, instance);
     instanceCst->run();
     pthread_cleanup_pop(1);
   } catch (const exception & e) {
     cerr << "Unrecoverable error: an exception was caught in AlternateThread "
             "(exceptions should normally be caught before getting here). "
             "Exception type is: " << typeid(e).name() << ", message is: " <<
             e.what() << endl;
     threadCleanupFct(instance);
   }
   // We can't catch (...) here because it causes problems with thread cancellation, at least
   // with gcc 4.1.2 and older. With newer versions it should be possible to do something like
   // catch (abi::__forced_unwind e) { throw; }. See
   // http://gcc.gnu.org/bugzilla/show_bug.cgi?id=28145 for details.
   // The problem is that no exception should get out of the thread scope without being caught
   // (otherwise the program aborts). So for now the user has to take care of catching all
   // exceptions, but he cannot use catch (...).
   return NULL;
 }

void AlternateThreadPT::signalAndWait ( )

private

Definition at line 122 of file AlternateThreadPT.cxx.

References _pingPongCond, _pingPongMutex, _threadStatus, NORMAL_CYCLE, TERMINATION_REQUESTED, and YASSERT.

Referenced by signalMasterAndWait(), and signalSlaveAndWait().

 {
   YASSERT(_threadStatus == NORMAL_CYCLE || _threadStatus == TERMINATION_REQUESTED)
   YASSERT(pthread_cond_signal(&_pingPongCond) == 0)
   YASSERT(pthread_cond_wait(&_pingPongCond, &_pingPongMutex) == 0)
 }

void AlternateThreadPT::signalMasterAndWait ( )

virtual

Block the slave thread and release the master thread.

Definition at line 114 of file AlternateThreadPT.cxx.

References _threadId, DEBTRACE, signalAndWait(), and YASSERT.

 {
   YASSERT(pthread_equal(pthread_self(), _threadId))
   DEBTRACE("Slave signaling master and waiting");
   signalAndWait();
   DEBTRACE("Slave running again");
 }

void AlternateThreadPT::signalSlaveAndWait ( )

virtual

Block the master thread and release the slave thread.

Definition at line 106 of file AlternateThreadPT.cxx.

References _threadId, DEBTRACE, signalAndWait(), and YASSERT.

Referenced by terminateSlaveThread().

 {
   YASSERT(!pthread_equal(pthread_self(), _threadId))
   DEBTRACE("Master signaling slave and waiting");
   signalAndWait();
   DEBTRACE("Master running again");
 }

void AlternateThreadPT::start ( )

Create and launch the slave thread.

This method must not be called by the slave thread or if a slave thread is already running.

Definition at line 51 of file AlternateThreadPT.cxx.

References _pingPongCond, _pingPongMutex, _threadId, _threadStatus, DEBTRACE, runThread(), UNEXISTING, and YASSERT.

 {
   // This method must not be called if a slave thread is running
   YASSERT(_threadStatus == UNEXISTING)
 
   YASSERT(pthread_mutex_lock(&_pingPongMutex) == 0)
   DEBTRACE("Starting thread")
   YASSERT(pthread_create(&_threadId, 0, runThread, this) == 0)
   DEBTRACE("Master waiting for slave")
   YASSERT(pthread_cond_wait(&_pingPongCond, &_pingPongMutex) == 0)
   DEBTRACE("Master running again")
 }

void AlternateThreadPT::terminateSlaveThread ( )

Terminate the slave thread.

Definition at line 64 of file AlternateThreadPT.cxx.

References _pingPongCond, _pingPongMutex, _threadId, _threadStatus, DEBTRACE, NORMAL_CYCLE, READY_TO_JOIN, signalSlaveAndWait(), TERMINATION_REQUESTED, UNEXISTING, and YASSERT.

Referenced by ~AlternateThreadPT().

 {
   // This method must not be called by the slave thread
   YASSERT(_threadStatus == UNEXISTING || !pthread_equal(pthread_self(), _threadId))
 
   switch (_threadStatus) {
     case UNEXISTING:
       return;
     case READY_TO_JOIN:
       break;
     case NORMAL_CYCLE:
     {
       // First try to signal the slave thread to end properly
       DEBTRACE("Master is trying to terminate slave by signaling error")
       _threadStatus = TERMINATION_REQUESTED;
       signalSlaveAndWait();
 
       if (_threadStatus != READY_TO_JOIN) {
         // Try to cancel the thread
         cerr << "Warning: Slave thread in AlternateThread did not end properly. "
                 "Thread will be canceled." << endl;
         YASSERT(pthread_cancel(_threadId) == 0)
         YASSERT(pthread_cond_wait(&_pingPongCond, &_pingPongMutex) == 0)
 
         if (_threadStatus != READY_TO_JOIN) {
           // If cancel failed, we can do nothing more, throw an exception
           YASSERT(false);
         }
       }
       break;
     }
     default:
       YASSERT(false)
   }
 
   // Finally join the thread
   YASSERT(pthread_mutex_unlock(&_pingPongMutex) == 0)
   YASSERT(pthread_join(_threadId, NULL) == 0)
   _threadStatus = UNEXISTING;
   DEBTRACE("AlternateThread terminated")
 }

void AlternateThreadPT::threadCleanupFct ( void * instance )

staticprivate

Definition at line 166 of file AlternateThreadPT.cxx.

References _pingPongCond, _pingPongMutex, _threadStatus, DEBTRACE, and READY_TO_JOIN.

Referenced by runThread().

 {
   // Beware of not throwing exceptions in this method
   DEBTRACE("Cleaning up slave thread")
   AlternateThreadPT * instanceCst = (AlternateThreadPT *)instance;
   instanceCst->_threadStatus = READY_TO_JOIN;
   pthread_cond_signal(&instanceCst->_pingPongCond);
   pthread_mutex_unlock(&instanceCst->_pingPongMutex);
 }