#include <Thread.h>

Inheritance diagram for rnr::Thread:

Public Types
enum	ThreadState { ThreadStateUninit, ThreadStateReady, ThreadStateStart, ThreadStateRunning, ThreadStateExit }
	Kinematics thread states. More...

Public Member Functions
	Thread (const std::string &strThreadName)
	Default constructor.

virtual	~Thread ()
	Destructor.

virtual int	createThread (int nPriority)
	Create the thread. More...

virtual int	runThread (const double fHz)
	Run the thread. More...

virtual int	terminateThread ()
	Terminate the thread. More...

virtual void	setHz (const double fHz)
	Calculate thread new full cycle run rate. More...

std::string	getThreadName () const
	Get assigned thread name. More...

int	getThreadPriority () const
	Get thread system scheduling priority. More...

double	getThreadHz () const
	Get thread run full cycle rate. More...

Static Public Attributes
static const int	ThreadPriorityDft = 0
	default thread attributes

static const int	ThreadPriorityMin = 1
	minimum scheduling priority

static const int	ThreadPriorityMax = 99
	maximum scheduling priority

static const double	ThreadMinHz = 0.001
	minimum Hertz rate More...

Protected Member Functions
void	lock ()
	Lock the I²C bus. More...

void	unlock ()
	Unlock the I²C bus. More...

void	setPriority (int nPriority, pthread_attr_t &attr)
	Set real-time priority attributes of of the thread to be created. More...

void	changeState (ThreadState eNewState)
	Change the thread state. More...

void	timedWait (const struct timespec &tsTimeout)
	Timed wait until state change or time out. More...

virtual void	readyBlock ()
	Block indefinitely while in the ready state. More...

virtual void	schedBlock ()
	Block the thread until the next subcycle task is to be run. More...

virtual void	transToReady ()
	Uninitialized to Ready state transition function. More...

virtual void	transToRunning ()
	Ready to Running state transition function. More...

virtual void	exec ()
	Execute task(s) within scheduled [sub]cycle. More...

virtual void	transToExit ()
	Any to Exit state transition function. More...

Static Protected Member Functions
static void *	thread (void *pArg)
	The thread. More...

Protected Attributes
std::string	m_strThreadName
	thread identifying name

ThreadState	m_eState
	thread state

pthread_mutex_t	m_mutexSync
	synchonization mutex

pthread_cond_t	m_condSync
	synchonization condition

pthread_t	m_thread
	pthread identifier

int	m_nPriority
	thread OS scheduling priority

double	m_fHz
	thread cycle run rate (Hertz)

double	m_fTExec
	task execution cycle period (sec)

chronos::Time	m_tExecPeriod
	task execution period (converted)

chronos::Time	m_tSched
	working scheduler time

chronos::Time	m_tExecLastTimeStamp
	start of last execution time stamp

chronos::Time	m_tExecThisTimeStamp
	start of this execution time stamp

int	m_nSlipErrCnt
	slipped error count leaky bucket

Detailed Description

Thread base class.

Definition at line 59 of file Thread.h.

Member Enumeration Documentation

enum rnr::Thread::ThreadState

Kinematics thread states.

Enumerator
ThreadStateUninit	thread created but unitialized
ThreadStateReady	thread created and blocked, ready to start
ThreadStateStart	start to run
ThreadStateRunning	thread running
ThreadStateExit	thread exiting/exited

Definition at line 76 of file Thread.h.

     {
       ThreadStateUninit,    ///< thread created but unitialized
       ThreadStateReady,     ///< thread created and blocked, ready to start
       ThreadStateStart,     ///< start to run 
       ThreadStateRunning,   ///< thread running
       ThreadStateExit       ///< thread exiting/exited
     };

Member Function Documentation

void Thread::changeState ( ThreadState eNewState )

protected

Change the thread state.

The thread, if blocked, will be immediately unblocked to examine the new state.

Parameters

eNewState New state.

Context:: Any.

Definition at line 252 of file Thread.cxx.

References m_condSync, and m_eState.

Referenced by runThread(), terminateThread(), thread(), and unlock().

 {
   m_eState = eNewState;
   pthread_cond_signal(&m_condSync);
 }

int Thread::createThread ( int nPriority )

virtual

Create the thread.

The thread remains blocked in the ready state until runThread() is called.

Parameters

nPriority Thread OS scheduling priority.

Context:: Calling thread.

Returns: On success, OK(0) is returned.
On error, RC_ERROR(-1) is returned.

Definition at line 87 of file Thread.cxx.

References lock(), m_condSync, m_eState, m_mutexSync, m_thread, setPriority(), thread(), ThreadPriorityDft, ThreadStateExit, ThreadStateUninit, and unlock().

Referenced by mainInit().

 {
   pthread_attr_t      attr;
   int                 rc;
 
   //
   // Create thread with default attributes.
   //
   if( nPriority == ThreadPriorityDft )
   {
     rc = pthread_create(&m_thread, NULL, Thread::thread, (void *)this);
   }
 
   //
   // Create thread with a real-time priority.
   //
   else
   {
     setPriority(nPriority, attr);
     rc = pthread_create(&m_thread, &attr, Thread::thread, (void *)this);
   }
 
   // failure to create
   if( rc != 0 )
   {
     LOGSYSERROR("pthread_create()");
     m_eState = ThreadStateExit;
     return RC_ERROR;
   }
 
   //
   // Wait for thread to initialize.
   //
   lock();
 
   while( m_eState == ThreadStateUninit )
   {
     pthread_cond_wait(&m_condSync, &m_mutexSync);
   }
 
   unlock();
 
   return OK;
 }

void Thread::exec ( )

protectedvirtual

Execute task(s) within scheduled [sub]cycle.

This function is called every cycle in the Running state.

A hook for any derived thread class. A simple debug print execution for the base class.

This function executes under the lock/unlock mutex.

Context:: This thread.

Reimplemented in UTThread.

Definition at line 363 of file Thread.cxx.

References m_strThreadName, m_tExecLastTimeStamp, m_tExecThisTimeStamp, and rnr::chronos::Time::ts().

Referenced by thread(), and unlock().

 {
   Time tDelta;
 
   tDelta = m_tExecThisTimeStamp - m_tExecLastTimeStamp;
 
   //fprintf(stderr, "delta=%lf, this=%lf, last=%lf\n",
   //    tDelta.t(), m_tExecThisTimeStamp.t(), m_tExecLastTimeStamp.t());
 
   printf("Thread %s: [%ld.%09ld] delta seconds.\n",
           m_strThreadName.c_str(), tDelta.ts().tv_sec, tDelta.ts().tv_nsec);
 
   fflush(stdout);
 }

double rnr::Thread::getThreadHz ( ) const

inline

Get thread run full cycle rate.

Returns: Thread hertz.

Definition at line 172 of file Thread.h.

References m_fHz.

     {
       return m_fHz;
     }

std::string rnr::Thread::getThreadName ( ) const

inline

Get assigned thread name.

Returns: Thread string name.

Definition at line 152 of file Thread.h.

References m_strThreadName.

     {
       return m_strThreadName;
     }

int rnr::Thread::getThreadPriority ( ) const

inline

Get thread system scheduling priority.

Returns: Thread priority.

Definition at line 162 of file Thread.h.

References m_nPriority.

     {
       return m_nPriority;
     }

void rnr::Thread::lock ( )

inlineprotected

Lock the I²C bus.

The lock()/unlock() primitives provide safe multi-threading access.

Context:: Any.

Definition at line 203 of file Thread.h.

Referenced by createThread(), readyBlock(), setHz(), thread(), and timedWait().

     {
       pthread_mutex_lock(&m_mutexSync);
     }

void Thread::readyBlock ( )

protectedvirtual

Block indefinitely while in the ready state.

Context:: Any.

Definition at line 267 of file Thread.cxx.

References lock(), m_condSync, m_eState, m_mutexSync, ThreadStateReady, and unlock().

Referenced by thread(), and unlock().

 {
   lock();
 
   while( m_eState == ThreadStateReady )
   {
     pthread_cond_wait(&m_condSync, &m_mutexSync);
   }
 
   unlock();
 }

int Thread::runThread ( const double fHz )

virtual

Run the thread.

Valid Current State:: ThreadStateReady

New State:: ThreadStateStart

Context:: Calling thread.

Parameters

fHZ	Thread run rate (Hertz).

Definition at line 189 of file Thread.cxx.

References changeState(), m_eState, m_strThreadName, setHz(), ThreadStateExit, ThreadStateReady, ThreadStateRunning, and ThreadStateStart.

Referenced by mainInit().

 {
   int       rc;       // return code
 
   setHz(fHz);
 
   switch( m_eState )
   {
     case ThreadStateReady:
       changeState(ThreadStateStart);
       rc = OK;
       break;
 
     case ThreadStateStart:
     case ThreadStateRunning:
       break;
 
     case ThreadStateExit:
     default:
       rc = RC_ERROR;
       LOGERROR("%s thread in invalid state %d to run.",
           m_strThreadName.c_str(), m_eState);
       break;
   } 
 
   return rc;
 }

void Thread::schedBlock ( )

protectedvirtual

Block the thread until the next subcycle task is to be run.

Context:: This thread.

Definition at line 279 of file Thread.cxx.

References m_nSlipErrCnt, m_strThreadName, m_tExecPeriod, m_tSched, rnr::chronos::Time::markNow(), timedWait(), and rnr::chronos::Time::ts().

Referenced by thread(), and unlock().

 {
   Time tNow;      // now
   Time tSlip;     // any slippage
 
   // mark now
   tNow.markNow();
 
   // 
   // Next scheduled execution cycle is in the future. Block wait for the next
   // cycle to begin.
   //
   if( tNow < m_tSched )
   {
     timedWait(m_tSched.ts());         // block
     tNow.markNow();                   // new now
     m_tSched = tNow + m_tExecPeriod;  // next scheduled time
     
     // leak
     if( m_nSlipErrCnt > 0 )
     {
       --m_nSlipErrCnt;
     }
   }
 
   //
   // Scheduled execution cycle is now.
   //
   else if( tNow == m_tSched )
   {
     m_tSched = tNow + m_tExecPeriod;     // next scheduled time
 
     if( m_nSlipErrCnt > 0 )
     {
       --m_nSlipErrCnt;
     }
   }
 
   //
   // Scheduled execution cycle slipped.
   //
   else
   {
     tSlip = tNow - m_tSched;
 
     //
     // Slipped by less than two execution cycles. Try to make up the time.
     //
     if( tSlip < m_tExecPeriod )
     {
       m_tSched = tNow + m_tExecPeriod - tSlip;  // next scheduled time
     }
 
     //
     // Slipped a bunch.
     //
     else
     {
       m_tSched = tNow + m_tExecPeriod;
 
       if( m_nSlipErrCnt < 1000 )
       {
         ++m_nSlipErrCnt;
       }
 
       // log moderated slippage
       if( m_nSlipErrCnt < 5 )
       {
         LOGWARN("%s thread: "
           "Execution slipped by %ld.%09ld seconds.",
           m_strThreadName.c_str(), tSlip.ts().tv_sec, tSlip.ts().tv_nsec);
       }
     }
   }
 }

void Thread::setHz ( const double fHz )

virtual

Calculate thread new full cycle run rate.

Parameters

fHZ	Thread run rate (Hertz).

Definition at line 229 of file Thread.cxx.

References lock(), m_fHz, m_fTExec, m_nSlipErrCnt, m_tExecPeriod, ThreadMinHz, and unlock().

Referenced by runThread().

 {
   lock();
 
   m_fHz = fHz;
 
   if( m_fHz < ThreadMinHz )
   {
     m_fHz = ThreadMinHz;
   }
 
   m_fTExec = 1.0 / m_fHz;
 
   m_tExecPeriod = m_fTExec;
 
   m_nSlipErrCnt = 0;
 
   //fprintf(stderr, "hz=%.2lf, m_fTExec=%lf\n", m_fHz, m_fTExec);
   //fprintf(stderr, "ExecPeriod=%lf\n", m_tExecPeriod.t());
 
   unlock();
 }

void Thread::setPriority	(	int	nPriority,
		pthread_attr_t &	attr
	)

protected

Set real-time priority attributes of of the thread to be created.

Parameters

	nPriority	Thread priority [1 (lowest) - 99 (highest)].
[out]	attr	Thread attributes.

Definition at line 132 of file Thread.cxx.

References m_nPriority, ThreadPriorityMax, and ThreadPriorityMin.

Referenced by createThread(), and unlock().

 {
   struct sched_param  parm;
   int                 prioMin, prioMax;
   double              f;
 
   // Initialize thread attributes.
   pthread_attr_init(&attr);
 
   //
   // Set thread scheduling policy.
   // SCHED_FIFO:
   //  + preemptive priority scheduling
   //  + highest priority thread runs until it choses to block/sleep
   //  + when it unblock/wakes it goes to the end of the queue for its priority
   //
   pthread_attr_setschedpolicy(&attr, SCHED_FIFO);
 
   //
   // Get the system's minimum and maximum scheduling priorities for the given
   // scheduling policy.
   //
   prioMin = sched_get_priority_min(SCHED_FIFO);
   prioMax = sched_get_priority_max(SCHED_FIFO);
 
   //
   // Map target priority between system min, max.
   //
   if( nPriority < ThreadPriorityMin )
   {
     nPriority = ThreadPriorityMin;
   }
   else if( nPriority > ThreadPriorityMax )
   {
     nPriority = ThreadPriorityMax;
   }
 
   f = (double)nPriority/(double)(ThreadPriorityMax - ThreadPriorityMin + 1);
 
   nPriority = (int)(f * (double)(prioMax - prioMin + 1) + 0.5);
 
   if( nPriority < prioMin )
   {
     nPriority = prioMin;
   }
   else if( nPriority > prioMax )
   {
     nPriority = prioMax;
   }
 
   //
   // Set the priority for this thread.
   //
   parm.sched_priority = m_nPriority;
   pthread_attr_setschedparam(&attr, &parm);
 }

int Thread::terminateThread ( )

virtual

Terminate the thread.

This function does not return until the thread actually terminates.

Context:: Calling thread.

Returns: On success, OK(0) is returned.
On error, RC_ERROR(-1) is returned.

Definition at line 217 of file Thread.cxx.

References changeState(), m_eState, m_thread, ThreadStateExit, ThreadStateReady, ThreadStateRunning, and ThreadStateStart.

Referenced by mainInit(), and ~Thread().

 {
   if( (m_eState == ThreadStateReady) ||
       (m_eState == ThreadStateStart) ||
       (m_eState == ThreadStateRunning) )
   {
     changeState(ThreadStateExit);
     pthread_join(m_thread, NULL);
   }
   return OK;
 }

void * Thread::thread ( void * pArg )

staticprotected

The thread.

Parameters

pArg	Thread argument (pointer to this object).

Returns: Returns NULL on thread exit.

Definition at line 382 of file Thread.cxx.

References changeState(), exec(), lock(), m_eState, m_fHz, m_nPriority, m_strThreadName, m_tExecLastTimeStamp, m_tExecThisTimeStamp, m_tSched, rnr::chronos::Time::markNow(), readyBlock(), schedBlock(), ThreadStateExit, ThreadStateReady, ThreadStateRunning, ThreadStateStart, transToExit(), transToReady(), transToRunning(), and unlock().

Referenced by createThread(), and unlock().

 {
   Thread *pThis = (Thread *)pArg;
   int           oldstate;
   int           rc;
 
   pthread_setcancelstate(PTHREAD_CANCEL_ENABLE, &oldstate);
   pthread_setcanceltype(PTHREAD_CANCEL_ASYNCHRONOUS, &oldstate);
 
   // Change state and signal calling thread that created this thread.
   pThis->changeState(ThreadStateReady);
 
   // derived thread specific Ready state transition function
   pThis->transToReady();
 
   LOGDIAG3("%s thread created at priority %d - ready to run.",
       pThis->m_strThreadName.c_str(), pThis->m_nPriority);
 
   //
   // Loop forever until exit
   //
   while( (pThis->m_eState != ThreadStateExit) )
   {
     switch( pThis->m_eState )
     {
       //
       // Blocked on Ready "queue"
       //
       case ThreadStateReady:
         pThis->readyBlock();
         break;
 
       //
       // Start running thread to execute task.
       //
       case ThreadStateStart:
         LOGDIAG3("%s thread started - running at %.3lf Hz.",
                 pThis->m_strThreadName.c_str(), pThis->m_fHz);
  
         // force immediately execution of first task
         pThis->m_tSched.markNow();
 
         pThis->m_tExecThisTimeStamp = pThis->m_tSched;
         pThis->m_tExecLastTimeStamp = pThis->m_tSched;
 
         pThis->changeState(ThreadStateRunning);
 
         // derived thread specific Running state transition function
         pThis->transToRunning();
         break;
 
       //
       // Run wait,execute subcycle
       //
       case ThreadStateRunning:
         pThis->schedBlock();
         if( pThis->m_eState == ThreadStateRunning )
         {
           pThis->m_tExecLastTimeStamp = pThis->m_tExecThisTimeStamp;
           pThis->m_tExecThisTimeStamp.markNow();
 
           pThis->lock();
           pThis->exec();
           pThis->unlock();
         }
         break;
 
       //
       // Exit
       //
       case ThreadStateExit:
         break;
 
       default:
         LOGERROR("%d: Unexpected thread state.", pThis->m_eState);
         pThis->m_eState = ThreadStateExit;
         break;
     }
   }
 
   pThis->transToExit();
 
   LOGDIAG3("%s thread terminated.", pThis->m_strThreadName.c_str());
 
   return NULL;
 }

void Thread::timedWait ( const struct timespec & tsTimeout )

protected

Timed wait until state change or time out.

Parameters

tsTimeout When timeout occurs in absolute time.

Context:: Any.

Definition at line 258 of file Thread.cxx.

References lock(), m_condSync, m_mutexSync, and unlock().

Referenced by schedBlock(), and unlock().

 {
   lock();
 
   pthread_cond_timedwait(&m_condSync, &m_mutexSync, &tsTimeout);
 
   unlock();
 }

void Thread::transToExit ( )

protectedvirtual

Any to Exit state transition function.

This function is called after entering the Exit state but prior to terminating the thread.

A hook for any derived thread class. A no-op for the base class.

This function does not execute under the lock/unlock mutex.

Context:: This thread.

Reimplemented in UTThread.

Definition at line 378 of file Thread.cxx.

Referenced by thread(), and unlock().

379 {

380 }

void Thread::transToReady ( )

protectedvirtual

Uninitialized to Ready state transition function.

This function is called after entering the Ready state but prior to being blocked waiting to be run.

A hook for any derived thread class. A no-op for the base class.

This function does not execute under the lock/unlock mutex.

Context:: This thread.

Reimplemented in UTThread.

Definition at line 355 of file Thread.cxx.

Referenced by thread(), and unlock().

356 {

357 }

void Thread::transToRunning ( )

protectedvirtual

Ready to Running state transition function.

This function is called after entering the Running state but prior to any run execution.

A hook for any derived thread class. A no-op for the base class.

This function does not execute under the lock/unlock mutex.

Context:: This thread.

Reimplemented in UTThread.

Definition at line 359 of file Thread.cxx.

Referenced by thread(), and unlock().

360 {

361 }

void rnr::Thread::unlock ( )

inlineprotected

Unlock the I²C bus.

The lock()/unlock() primitives provide safe multi-threading access.

Context:: Any.

Definition at line 217 of file Thread.h.

References changeState(), exec(), readyBlock(), schedBlock(), setPriority(), thread(), timedWait(), transToExit(), transToReady(), and transToRunning().

Referenced by createThread(), readyBlock(), setHz(), thread(), and timedWait().

     {
       pthread_mutex_unlock(&m_mutexSync);
     }

Member Data Documentation

const double Thread::ThreadMinHz = 0.001

static

minimum Hertz rate

once every 1000 seconds

Definition at line 71 of file Thread.h.

Referenced by setHz(), and Thread().

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

include/rnr/appkit/Thread.h
sw/librnr_appkit/Thread.cxx

Public Types

Public Member Functions

Static Public Attributes

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Detailed Description

Member Enumeration Documentation

Member Function Documentation

Member Data Documentation