ossim::Thread Class Reference

Thread is an abstract class. More...

#include <Thread.h>

Inheritance diagram for ossim::Thread:

Classes
class	Interrupt
	This is an Interrupt exception that is thrown if the. More...

Public Member Functions
	Thread ()
	Constructor for this thread. More...
virtual	~Thread ()
	Destructor for this thread. More...
void	start ()
	Will actually start the thread and will call the. More...
bool	isRunning () const
bool	isInterruptable () const
	This is typically set if. More...
virtual void	cancel ()
	This basically requests that the thread be canceled. More...
virtual void	setCancel (bool flag)
virtual void	waitForCompletion ()
	Convenience to allow one to wait for this thread to finish it's work. More...
void	pause ()
	Enables the thread to be paused. More...
void	resume ()
	This will resume a blocked thread. More...
bool	isPaused () const

Static Public Member Functions
static void	sleepInSeconds (ossim_uint64 seconds)
	Utility method to allow one to sleep in seconds. More...
static void	sleepInMilliSeconds (ossim_uint64 millis)
	Utility method to allow one to sleep in milliseconds. More...
static void	sleepInMicroSeconds (ossim_uint64 micros)
	Utility method to allow one to sleep in microseconds. More...
static std::thread::id	getCurrentThreadId ()
	Utility method to get the current thread ID. More...
static ossim_uint64	getNumberOfProcessors ()
	Utility to return the number of processors (concurrent threads) More...
static void	yieldCurrentThread ()
	Will yield the current thread. More...

Protected Member Functions
virtual void	run ()=0
	This method must be overriden and is the main entry point for any work that needs to be done. More...
virtual void	interrupt ()
	This is the interrupt interface and will cause an internal exception that is caught by. More...
virtual void	runInternal ()
	runInternal sets up internal flags such as setting m_running to true and checks to make sure it's not interrupted and will then call the More...

Private Member Functions
void	setInterruptable (bool flag)

Private Attributes
std::shared_ptr< std::thread >	m_thread
std::atomic< bool >	m_running
std::atomic< bool >	m_interrupt
std::shared_ptr< ossim::Barrier >	m_pauseBarrier
std::condition_variable	m_runningCondition
std::mutex	m_runningMutex

Detailed Description

Thread is an abstract class.

It provides a general purpose thread interface that handles preliminary setup of the std c++11 thread. It allows one to derive from Thread and override the run method. Your thread should have calls to interrupt() whenever your thread is in a location that is interruptable. If cancel is called then any thread that is interruptable will throw an Interrupt and be caught in the base Thread class and then exit the thread.

Example:

#include <ossim/base/Thread.h>
#include <ossim/base/Barrier.h>
class TestThread : public ossim::Thread
 {
 public:
     TestThread():ossim::Thread(){}
     ~TestThread(){
        waitForCompletion();
     }

  protected:
     virtual void run()
     {
        barrierStart.block();
        for(int x =0 ; x < 10;++x){
           std::cout << "THREAD: " << getCurrentThreadId() << "\n";
           // simulate 10 milliseconds of uninterruptable work
           sleepInMilliSeconds(10);
           interrupt();
        }
        barrierFinished.block();
     }
  };
int main(int agrc, char* argv[])
{
   std::vector<std::shared_ptr<TestThread> > threads(nThreads);
   for(auto& thread:threads)
   {
     thread = std::make_shared<TestThread>();
     thread->start();
   }

   // now let's wait for each thread to finish 
   // before exiting
   for(auto& thread:threads)
   {
     thread->waitForCompletion();
   }
}

Definition at line 66 of file Thread.h.

Constructor & Destructor Documentation

Thread()

ossim::Thread::Thread

(

)

Constructor for this thread.

Definition at line 3 of file Thread.cpp.

:m_running(false),
 m_interrupt(false),
 m_pauseBarrier(std::make_shared<ossim::Barrier>(1))
{
}

~Thread()

ossim::Thread::~Thread ( )

virtual

Destructor for this thread.

It will determine if this thread is joinable to the main thread and if so it will do a join before continuing. If this is not done then an exeption is thrown by the std.

Definition at line 10 of file Thread.cpp.

{
   if(m_thread)
   {
      // we will wait as a sanity but this should be done in derived Thread
      waitForCompletion();
      if(m_thread->joinable()) m_thread->join();
      m_thread = 0;         
   }
   m_running = false;
}

Member Function Documentation

cancel()

virtual void ossim::Thread::cancel ( )

inlinevirtual

This basically requests that the thread be canceled.

See also

setCancel. Note, cancellation is not done immediately and a thread is only cancleed if derived classes call the interrupt().

we will make these virtual just in case derived classes want to set conditions

Reimplemented in ossimJobThreadQueue.

Definition at line 117 of file Thread.h.

{setCancel(true);}

getCurrentThreadId()

std::thread::id ossim::Thread::getCurrentThreadId ( )

static

Utility method to get the current thread ID.

Returns

current thread ID

Definition at line 93 of file Thread.cpp.

{
   return std::this_thread::get_id();
}

getNumberOfProcessors()

ossim_uint64 ossim::Thread::getNumberOfProcessors ( )

static

Utility to return the number of processors (concurrent threads)

Definition at line 88 of file Thread.cpp.

Referenced by ossim::getNumberOfThreads().

{
   return std::thread::hardware_concurrency();
}

interrupt()

void ossim::Thread::interrupt ( )

protectedvirtual

This is the interrupt interface and will cause an internal exception that is caught by.

See also

runInternal

Definition at line 103 of file Thread.cpp.

Referenced by ossimJobThreadQueue::run().

{
   if(m_interrupt)
   {
      throw ossim::Thread::Interrupt();
   }
   m_pauseBarrier->block();
}

isInterruptable()

bool ossim::Thread::isInterruptable ( ) const

inline

This is typically set if.

See also

cancel() is called or if

setCancel is called with argument set to true.

Returns

true if the thread is interruptable and false otherwise.

Definition at line 108 of file Thread.h.

{return m_interrupt.load(std::memory_order_relaxed);}

isPaused()

bool ossim::Thread::isPaused

(

)

const

Returns

true if the thread is blocked and false otherwise

Definition at line 68 of file Thread.cpp.

Referenced by ossimJobThreadQueue::setJobQueue().

{
   return (m_pauseBarrier->getBlockedCount()>0);
}

isRunning()

bool ossim::Thread::isRunning ( ) const

inline

Returns

true if the current thread is running and false otherwise.

Definition at line 100 of file Thread.h.

Referenced by ossimJobThreadQueue::cancel(), ossimJobThreadQueue::setJobQueue(), and ossimJobThreadQueue::startThreadForQueue().

{return m_running.load(std::memory_order_relaxed);}

pause()

void ossim::Thread::pause

(

)

Enables the thread to be paused.

If the interrupt is called it will block the thread

Definition at line 58 of file Thread.cpp.

Referenced by ossimJobThreadQueue::setJobQueue().

{
   m_pauseBarrier->reset(2);
}

resume()

void ossim::Thread::resume

(

)

This will resume a blocked thread.

Definition at line 63 of file Thread.cpp.

Referenced by ossimJobThreadQueue::setJobQueue().

{
   m_pauseBarrier->reset(1);
}

run()

virtual void ossim::Thread::run ( )

protectedpure virtual

This method must be overriden and is the main entry point for any work that needs to be done.

Implemented in ossimJobThreadQueue.

runInternal()

void ossim::Thread::runInternal ( )

protectedvirtual

runInternal sets up internal flags such as setting m_running to true and checks to make sure it's not interrupted and will then call the

See also

run() method.

runInternal also will trap any Interrupt exceptions. If the thread is interruptable and the work calls interrupt then an exception is thrown and the work is stopped and the execution of the thread is marked as not running and returns.

Definition at line 117 of file Thread.cpp.

Referenced by start().

{
   try
   {
      if(!isInterruptable())
      {
         run();
      }
   }
   catch(Interrupt& e)
   {
   }
   m_running = false;
   m_runningCondition.notify_all();
}

setCancel()

void ossim::Thread::setCancel ( bool  flag )

virtual

Parameters

flag	if true will enable the thread to be interruptable and if false the thread is not interruptable.

Definition at line 37 of file Thread.cpp.

{
   setInterruptable(flag);
   if(flag)
   {
      // if it was paused we will resume.  Calling resume 
      // will reset the barrier so we can cancel the process
      //
      resume();
   }
}

setInterruptable()

void ossim::Thread::setInterruptable ( bool  flag )

private

See also

cancel and

setCancel

Definition at line 112 of file Thread.cpp.

{
   m_interrupt.store(flag, std::memory_order_relaxed);
}

sleepInMicroSeconds()

void ossim::Thread::sleepInMicroSeconds ( ossim_uint64  micros )

static

Utility method to allow one to sleep in microseconds.

Parameters

micros

to sleep

Definition at line 83 of file Thread.cpp.

Referenced by ossimHlzTool::computeHLZ(), and ossimViewshedTool::computeViewshed().

{
   std::this_thread::sleep_for(std::chrono::microseconds(micros));
}

sleepInMilliSeconds()

void ossim::Thread::sleepInMilliSeconds ( ossim_uint64  millis )

static

Utility method to allow one to sleep in milliseconds.

Parameters

millis

to sleep

Definition at line 78 of file Thread.cpp.

{
   std::this_thread::sleep_for(std::chrono::milliseconds(millis));
}

sleepInSeconds()

void ossim::Thread::sleepInSeconds ( ossim_uint64  seconds )

static

Utility method to allow one to sleep in seconds.

Parameters

seconds

to sleep

Definition at line 73 of file Thread.cpp.

{
   std::this_thread::sleep_for(std::chrono::seconds(seconds));
}

start()

void ossim::Thread::start

(

)

Will actually start the thread and will call the.

See also

internalRun.

Definition at line 22 of file Thread.cpp.

References runInternal().

Referenced by ossimJobThreadQueue::startThreadForQueue().

{
   if(isInterruptable()||isRunning()) return;
   m_running = true;

   // we are managing the thread internal.  If we are not running then we may need to join
   // before allocating a new thread
   if(m_thread)
   {
      if(m_thread->joinable()) m_thread->join();
   }

   m_thread = std::make_shared<std::thread>(&Thread::runInternal, this);
}

waitForCompletion()

void ossim::Thread::waitForCompletion ( )

virtual

Convenience to allow one to wait for this thread to finish it's work.

Allow this to be overriden.

Definition at line 49 of file Thread.cpp.

{
   if(m_thread)
   {
      std::unique_lock<std::mutex> lock(m_runningMutex);
      m_runningCondition.wait(lock, [&]{return !isRunning();} );
   }
}

yieldCurrentThread()

void ossim::Thread::yieldCurrentThread ( )

static

Will yield the current thread.

Definition at line 98 of file Thread.cpp.

Referenced by ossimJobThreadQueue::cancel(), and ossimJobThreadQueue::run().

{
    std::this_thread::yield();
}

Member Data Documentation

m_interrupt

std::atomic<bool> ossim::Thread::m_interrupt

private

Definition at line 211 of file Thread.h.

m_pauseBarrier

std::shared_ptr<ossim::Barrier> ossim::Thread::m_pauseBarrier

private

Definition at line 212 of file Thread.h.

m_running

std::atomic<bool> ossim::Thread::m_running

private

Definition at line 210 of file Thread.h.

m_runningCondition

std::condition_variable ossim::Thread::m_runningCondition

private

Definition at line 213 of file Thread.h.

m_runningMutex

std::mutex ossim::Thread::m_runningMutex

mutableprivate

Definition at line 214 of file Thread.h.

m_thread

std::shared_ptr<std::thread> ossim::Thread::m_thread

private

Definition at line 209 of file Thread.h.

---

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

• Thread.h
• Thread.cpp