laelaps::LaeThread Class Reference

#include <laeThread.h>

Inheritance diagram for laelaps::LaeThread:

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

Public Member Functions
	LaeThread (const std::string &strThreadName)
	Default constructor.
virtual	~LaeThread ()
	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	ThreadPriorityMin = 1
	minimum scheduling priority
static const int	ThreadPriorityMax = 99
	maximum scheduling priority
static const double	ThreadMinHz = 0.001
	minimum thread Hertz More...

Protected Member Functions
void	lock ()
	Lock the I2C bus. More...
void	unlock ()
	Unlock the I2C bus. 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 (seconds)
struct timespec	m_tsExecPeriod
	task execution period (converted)
struct timespec	m_tsJitter
	allowable scheduling jitter
struct timespec	m_tsSched
	working scheduler time stamp
struct timespec	m_tsExecLast
	start of last execution time stamp
struct timespec	m_tsExecThis
	start of this execution time stamp
int	m_nSlipErrCnt
	slipped error count leaky bucket

Detailed Description

Thread base class.

Definition at line 77 of file laeThread.h.

Member Enumeration Documentation

enum laelaps::LaeThread::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 93 of file laeThread.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 LaeThread::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 244 of file laeThread.cxx.

References m_condSync, and m_eState.

Referenced by laelaps::LaeThreadAsync::exec(), runThread(), terminateThread(), thread(), and unlock().

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

int LaeThread::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 107 of file laeThread.cxx.

References laelaps::cap(), laelaps::LAE_ECODE_NO_EXEC, laelaps::LAE_OK, lock(), m_condSync, m_eState, m_mutexSync, m_nPriority, m_thread, thread(), ThreadPriorityMax, ThreadPriorityMin, ThreadStateExit, ThreadStateUninit, and unlock().

Referenced by laelaps::LaeThreadAsync::createThread(), mainInit(), and laelaps::LaeRobot::startThread().

{
  pthread_attr_t      attr;
  struct sched_param  parm;
  double              f;
  int                 prioMin, prioMax;
  int                 rc;

  // 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.
  //
  nPriority = cap(nPriority, ThreadPriorityMin, ThreadPriorityMax);
  f = (double)nPriority/(double)(ThreadPriorityMax - ThreadPriorityMin + 1);
  nPriority = (int)(f * (double)(prioMax - prioMin + 1) + 0.5);
  m_nPriority = cap(nPriority, prioMin, prioMax);

  //
  // Set the priority for this thread.
  //
  parm.sched_priority = m_nPriority;
  pthread_attr_setschedparam(&attr, &parm);

  // Create kinematics thread.
  rc = pthread_create(&m_thread, &attr, LaeThread::thread, (void *)this);
 
  // failure to create
  if( rc != 0 )
  {
    LOGSYSERROR("pthread_create()");
    m_eState = ThreadStateExit;
    return -LAE_ECODE_NO_EXEC;
  }

  //
  // Wait for thread to initialize.
  //
  lock();

  while( m_eState == ThreadStateUninit )
  {
    pthread_cond_wait(&m_condSync, &m_mutexSync);
  }

  unlock();

  return LAE_OK;
}

void LaeThread::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 laelaps::LaeThreadAsync, UTThread, laelaps::LaeThreadKin, laelaps::LaeThreadWd, laelaps::LaeThreadRange, and laelaps::LaeThreadImu.

Definition at line 350 of file laeThread.cxx.

References m_strThreadName, m_tsExecLast, and m_tsExecThis.

Referenced by thread(), and unlock().

{
  struct timespec tsDelta;

  tsDelta = m_tsExecThis - m_tsExecLast;

  printf("Thread %s: [%ld.%09ld] delta seconds.\n",
          m_strThreadName.c_str(), tsDelta.tv_sec, tsDelta.tv_nsec);

  fflush(stdout);
}

double laelaps::LaeThread::getThreadHz ( ) const

inline

Get thread run full cycle rate.

Returns

Thread hertz.

Definition at line 189 of file laeThread.h.

References m_fHz.

    {
      return m_fHz;
    }

std::string laelaps::LaeThread::getThreadName ( ) const

inline

Get assigned thread name.

Returns

Thread string name.

Definition at line 169 of file laeThread.h.

References m_strThreadName.

Referenced by laelaps::LaeRobot::startThread().

    {
      return m_strThreadName;
    }

int laelaps::LaeThread::getThreadPriority ( ) const

inline

Get thread system scheduling priority.

Returns

Thread priority.

Definition at line 179 of file laeThread.h.

References m_nPriority.

    {
      return m_nPriority;
    }

void laelaps::LaeThread::lock ( )

inlineprotected

Lock the I²C bus.

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

Context:

Any.

Definition at line 221 of file laeThread.h.

Referenced by createThread(), readyBlock(), laelaps::LaeThreadImu::reload(), laelaps::LaeThreadRange::reload(), laelaps::LaeThreadKin::reload(), laelaps::LaeThreadWd::reload(), setHz(), thread(), timedWait(), and laelaps::LaeThreadKin::waitOneCycle().

    {
      pthread_mutex_lock(&m_mutexSync);
    }

void LaeThread::readyBlock ( )

protectedvirtual

Block indefinitely while in the ready state.

Context:

Any.

Definition at line 259 of file laeThread.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 LaeThread::runThread ( const double  fHz )

virtual

Run the thread.

Valid Current State:

ThreadStateReady

New State:

ThreadStateStart

Context:

Calling thread.

Parameters

fHZ	Thread run rate (Hertz).

Reimplemented in laelaps::LaeThreadAsync.

Definition at line 174 of file laeThread.cxx.

References changeState(), laelaps::LAE_ECODE_GEN, laelaps::LAE_OK, m_eState, m_strThreadName, setHz(), ThreadStateExit, ThreadStateReady, ThreadStateRunning, and ThreadStateStart.

Referenced by mainInit(), laelaps::LaeThreadAsync::runThread(), and laelaps::LaeRobot::startThread().

{
  int       rc;       // return code

  setHz(fHz);

  switch( m_eState )
  {
    case ThreadStateReady:
      changeState(ThreadStateStart);
      rc = LAE_OK;
      break;

    case ThreadStateStart:
    case ThreadStateRunning:
      break;

    case ThreadStateExit:
    default:
      rc = -LAE_ECODE_GEN;
      LOGERROR("%s thread in invalid state %d to run.",
          m_strThreadName.c_str(), m_eState);
      break;
  } 

  return rc;
}

void LaeThread::schedBlock ( )

protectedvirtual

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

Context:

This thread.

Definition at line 271 of file laeThread.cxx.

References m_nSlipErrCnt, m_strThreadName, m_tsExecPeriod, m_tsJitter, m_tsSched, and timedWait().

Referenced by thread(), and unlock().

{
  struct timespec tsNow;            // now
  struct timespec tsSlip = {0, 0};  // any slippage

  // now
  clock_gettime(CLOCK_REALTIME, &tsNow);

  //prts("now  ", tsNow);
  //prts("sched", m_tsSched);

  // 
  // Next scheduled execution cycle is in the future. Block wait for the next
  // cycle to begin.
  //
  if( tsNow < m_tsSched )
  {
    timedWait(m_tsSched);                   // block
    clock_gettime(CLOCK_REALTIME, &tsNow);  // now again
  }

  //
  // Determine any slip in task schedule.
  //
  if( tsNow > m_tsSched )
  {
    tsSlip = tsNow - m_tsSched;
  } 

  //
  // Slipped by less than an execution cycles. Try to make up the time.
  //
  if( tsSlip <= m_tsExecPeriod )
  {
    m_tsSched = tsNow + m_tsExecPeriod - tsSlip;  // next scheduled time
    if( m_nSlipErrCnt > 0 )
    {
      --m_nSlipErrCnt;
    }
  }

  //
  // Slipped by at least one full cycle, but within acceptable jitter.
  //
  else if( tsSlip < m_tsJitter )
  {
    m_tsSched = tsNow + m_tsExecPeriod;
  }

  //
  // Slipped badly by at least one full cycle.
  //
  else
  {
    m_tsSched = tsNow + m_tsExecPeriod;

    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(), tsSlip.tv_sec, tsSlip.tv_nsec);
    }
  }
}

void LaeThread::setHz ( const double  fHz )

virtual

Calculate thread new full cycle run rate.

Parameters

fHZ	Thread run rate (Hertz).

Definition at line 214 of file laeThread.cxx.

References laelaps::fcap(), lock(), m_fHz, m_fTExec, m_nSlipErrCnt, m_tsExecPeriod, m_tsJitter, ThreadMinHz, and unlock().

Referenced by laelaps::LaeThreadImu::reload(), laelaps::LaeThreadRange::reload(), laelaps::LaeThreadKin::reload(), and runThread().

{
  lock();

  m_fHz = fHz;

  if( m_fHz < ThreadMinHz )
  {
    m_fHz = ThreadMinHz;
  }

  m_fTExec = 1.0 / m_fHz;

  //fprintf(stderr, "hz=%.2lf, m_fTExec=%lf\n", m_fHz, m_fTExec);

  m_tsExecPeriod.tv_sec  = (long)floor(m_fTExec); 
  m_tsExecPeriod.tv_nsec = (long)fcap(
                                (m_fTExec-floor(m_fTExec)) * (double)BILLION,
                                0.0, (double)(BILLION-1) );

  //prts("execperiod", m_tsExecPeriod);

  m_tsJitter    = m_tsExecPeriod;
  m_tsJitter.tv_nsec += 50000000;   // 5/100th of second

  m_nSlipErrCnt = 0;

  unlock();
}

int LaeThread::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.

Reimplemented in laelaps::LaeThreadAsync.

Definition at line 202 of file laeThread.cxx.

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

Referenced by laelaps::LaeRobot::disconnect(), mainInit(), laelaps::LaeThreadAsync::terminateThread(), and ~LaeThread().

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

void * LaeThread::thread ( void *  pArg )

staticprotected

The thread.

Parameters

pArg	Thread argument (pointer to this object).

Returns

Returns NULL on thread exit.

Definition at line 366 of file laeThread.cxx.

References changeState(), exec(), lock(), m_eState, m_fHz, m_nPriority, m_strThreadName, m_tsExecLast, m_tsExecThis, m_tsSched, readyBlock(), schedBlock(), ThreadStateExit, ThreadStateReady, ThreadStateRunning, ThreadStateStart, transToExit(), transToReady(), transToRunning(), and unlock().

Referenced by createThread(), and unlock().

{
  LaeThread *pThis = (LaeThread *)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
        clock_gettime(CLOCK_REALTIME, &pThis->m_tsSched);
        pThis->m_tsExecThis = pThis->m_tsSched;
        pThis->m_tsExecLast = pThis->m_tsSched;

        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_tsExecLast = pThis->m_tsExecThis;
          clock_gettime(CLOCK_REALTIME, &pThis->m_tsExecThis);
          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 LaeThread::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 250 of file laeThread.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 LaeThread::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 laelaps::LaeThreadAsync, and UTThread.

Definition at line 362 of file laeThread.cxx.

Referenced by thread(), and unlock().

{
}

void LaeThread::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 laelaps::LaeThreadAsync, and UTThread.

Definition at line 342 of file laeThread.cxx.

Referenced by thread(), and unlock().

{
}

void LaeThread::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 laelaps::LaeThreadAsync, UTThread, and laelaps::LaeThreadKin.

Definition at line 346 of file laeThread.cxx.

Referenced by thread(), and unlock().

{
}

void laelaps::LaeThread::unlock ( )

inlineprotected

Unlock the I²C bus.

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

Context:

Any.

Definition at line 235 of file laeThread.h.

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

Referenced by createThread(), readyBlock(), laelaps::LaeThreadImu::reload(), laelaps::LaeThreadRange::reload(), laelaps::LaeThreadKin::reload(), laelaps::LaeThreadWd::reload(), setHz(), thread(), timedWait(), and laelaps::LaeThreadKin::waitOneCycle().

    {
      pthread_mutex_unlock(&m_mutexSync);
    }

Member Data Documentation

const double LaeThread::ThreadMinHz = 0.001

static

minimum thread Hertz

once every 1000 seconds

Definition at line 88 of file laeThread.h.

Referenced by LaeThread(), and setHz().

---

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

• include/Laelaps/laeThread.h
• sw/liblaelaps/laeThread.cxx