The base class to be used any thread. More...

#include <KKThread.h>

Inheritance diagram for KKB::KKThread:

Public Types
typedef KKThread *	KKThreadPtr

enum	ThreadPriority : int { ThreadPriority::Null, ThreadPriority::Low, ThreadPriority::Normal, ThreadPriority::High }

enum	ThreadStatus : int { ThreadStatus::Null, ThreadStatus::NotStarted, ThreadStatus::Starting, ThreadStatus::Running, ThreadStatus::Stopping, ThreadStatus::Stopped }

Public Member Functions
	KKThread (const KKStr &_threadName, KKThreadManagerPtr _threadManager, MsgQueuePtr _msgQueue)

virtual	~KKThread ()

void	AddShutdownPrerequistite (KKThreadPtr _thread)
	Specify threads that must stop before this thread is started. More...

void	AddStartPrerequistite (KKThreadPtr _thread)
	Specify threads that must start before this thread is started. More...

VolConstBool &	CancelFlag () const

bool	Crashed () const

void	Crashed (bool _crashed)

const KKStr &	ExceptionText () const

void	ExceptionText (const KKStr &_exceptionText)

KKStrListPtr	GetMsgs ()

void	Kill ()
	stops the running thread and frees the thread handle More...

kkint32	MemoryConsumedEstimated ()

KKB::MsgQueuePtr	MsgQueue ()

bool	OkToShutdown () const

bool	OkToStart () const

virtual void	Run ()

VolConstBool &	ShutdownFlag () const

void	ShutdownThread ()

void	Start (ThreadPriority _priority, bool &successful)

ThreadStatus	Status () const

void	Status (ThreadStatus _status)

const KKStr &	StatusStr () const

VolConstBool &	TerminateFlag () const

virtual void	TerminateFlagChanged ()
	Will be called whenever the value of 'terminateFlag' is changed; derived classes should override this method if they need to be aware that the terminaeFlag has changed. This give them a chance to let other objects/methods know that the flag has changed. More...

void	TerminateThread ()

kkint32	ThreadId () const

const KKStr &	ThreadName () const

bool	ThreadStillProcessing () const

void	WaitForThreadToStop (kkuint32 maxTimeToWait)
	Called by separate thread; will stay in loop until the thread controlled by this instance shutdown or it waited the 'maxTimeToWait'. More...

Static Public Member Functions
static const KKStr &	ThreadStatusToStr (ThreadStatus)

Protected Member Functions
void	AddMsg (KKStrPtr msg)

void	AddMsg (const KKStr &msg)

bool	ShutdownOrTerminateRequested ()

bool	ThereIsACircularReferenceShutdown (KKThreadPtr _thread) const

bool	ThereIsACircularReferenceStart (KKThreadPtr _thread) const

Detailed Description

The base class to be used any thread.

This will be the base class for each one of the different types of processing.

Definition at line 27 of file KKThread.h.

Member Typedef Documentation

typedef KKThread* KKB::KKThread::KKThreadPtr

Definition at line 30 of file KKThread.h.

Member Enumeration Documentation

enum KKB::KKThread::ThreadPriority : int

strong

Enumerator
Null
Low
Normal
High

Definition at line 32 of file KKThread.h.

enum KKB::KKThread::ThreadStatus : int

strong

Enumerator
Null
NotStarted
Starting
Running
Stopping
Stopped

Definition at line 39 of file KKThread.h.

                              : int
                    {Null,
                     NotStarted,
                     Starting,
                     Running,
                     Stopping,
                     Stopped
                    };

Constructor & Destructor Documentation

KKThread::KKThread	(	const KKStr &	_threadName,
		KKThreadManagerPtr	_threadManager,
		MsgQueuePtr	_msgQueue
	)

Definition at line 83 of file KKThread.cpp.

References KKB::KKStr::KKStr(), Normal, and NotStarted.

Referenced by KKB::KKThreadManager::KKThreadManager().

                     :
    crashed               (false),
    msgQueue              (_msgQueue),
    priority              (ThreadPriority::Normal),
    shutdownFlag          (false),
    shutdownPrerequisites (NULL),
    startPrerequisites    (NULL),
    status                (ThreadStatus::NotStarted),
    terminateFlag         (false),
    threadId              (0),
    threadName            (_threadName)
 
 {
 #if  defined(WIN32)
   windowsThreadHandle  = NULL;
   windowsThreadId = 0;
 #else
   linuxThreadId = 0;
 #endif
 }

KKThread::~KKThread ( )

virtual

Definition at line 109 of file KKThread.cpp.

 {
   delete  shutdownPrerequisites;  shutdownPrerequisites = NULL;
   delete  startPrerequisites;     startPrerequisites    = NULL;
 }

Member Function Documentation

void KKThread::AddMsg ( KKStrPtr msg )

protected

Taking ownership of 'msg' and will append to 'msgQueue'.

Definition at line 154 of file KKThread.cpp.

References KKB::MsgQueue::AddMsg().

 {
   if  (msgQueue == NULL)
   {
     cerr << endl 
          << "KKThread::AddMsg   ***ERROR***    msgQuue is not defined."  << endl
          << "                   Msg[" << *msg << "]." << endl
          << endl;
     delete  msg;
     msg = NULL;
   }
   else
   {
     msgQueue->AddMsg (msg);
   }
 }  /* AddMsg */

void KKThread::AddMsg ( const KKStr & msg )

protected

A copy of the message 'msg' will be added to the end of msgQueue.

Definition at line 174 of file KKThread.cpp.

References KKB::MsgQueue::AddMsg(), KKB::KKStr::Concat(), KKB::KKStr::KKStr(), KKB::KKStr::Len(), KKB::osGetLocalDateTime(), KKB::osGetThreadId(), and KKB::DateTime::Time().

Referenced by Run().

 {
   if  (msgQueue == NULL)
   {
     cerr << endl 
          << "KKThread::AddMsg   ***ERROR***    msgQuue is not defined."  << endl
          << "                       Msg[" << msg << "]." << endl
          << endl;
   }
   else
   {
     KKStr msgTemp (msg.Len () + 20);
     msgTemp << osGetThreadId () << " - " << osGetLocalDateTime ().Time () << "->" << msg;
     msgQueue->AddMsg (msgTemp);
   }
 }  /* AddMsg */

void KKThread::AddShutdownPrerequistite ( KKThreadPtr _thread )

Specify threads that must stop before this thread is started.

This method can be called multiple times; the information is used by the 'KKTHreadManager' instance to control the orderly shutdown of the controlling 'KKTHreadManager' instance.

Parameters

[in] _thread A thread that needs to be in the 'Stopped' status before this thread can be shutdown; we do NOT take ownership.

Definition at line 510 of file KKThread.cpp.

References KKB::KKThreadList::KKThreadList().

 {
   if  (!shutdownPrerequisites)
     shutdownPrerequisites = new KKThreadList (false);
   shutdownPrerequisites->PushOnBack (_thread);
 }

void KKThread::AddStartPrerequistite ( KKThreadPtr _thread )

Specify threads that must start before this thread is started.

This method can be called multiple times; the information is used by the 'KKTHreadManager' instance to control the start of the thread.

Parameters

[in] _thread A thread that needs to be in the 'Running' status before this thread can start; we do NOT take ownership.

Definition at line 501 of file KKThread.cpp.

References KKB::KKThreadList::KKThreadList().

 {
   if  (!startPrerequisites)
     startPrerequisites = new KKThreadList (false);
   startPrerequisites->PushOnBack (_thread);
 }

VolConstBool& KKB::KKThread::CancelFlag ( ) const

inline

Another name for 'TerminateFlag'.

Definition at line 60 of file KKThread.h.

bool KKB::KKThread::Crashed ( ) const

inline

Signifies that this thread had to terminate on its own because of an abnormal situation; such as a memory corruption.

Definition at line 62 of file KKThread.h.

Referenced by KKB::KKThreadManager::AnyProcessorsCrashed().

void KKB::KKThread::Crashed ( bool _crashed )

inline

Definition at line 89 of file KKThread.h.

Referenced by KKB::ThreadStartCallBack().

89 {crashed = _crashed;}

const KKStr& KKB::KKThread::ExceptionText ( ) const

inline

If the overloaded 'Run' method of a derived class generates a exception that is not caught; then the ''ThreadStartCallBack' will catch it and store the related text in this field. In this case the 'Crashed()' method will return 'true'.

Definition at line 66 of file KKThread.h.

void KKB::KKThread::ExceptionText ( const KKStr & _exceptionText )

inline

Definition at line 90 of file KKThread.h.

References KKB::KKStr::operator=().

Referenced by KKB::ThreadStartCallBack().

90 {exceptionText = _exceptionText;}

KKStrListPtr KKThread::GetMsgs ( )

Definition at line 193 of file KKThread.cpp.

References KKB::MsgQueue::GetNextMsg(), and KKB::KKStrList::KKStrList().

 {
   KKStrListPtr  results = new KKStrList (true);
   KKStrPtr  msg = msgQueue->GetNextMsg ();
   while  (msg)
   {
     results->PushOnBack (msg);
     msg = msgQueue->GetNextMsg ();
   }
 
   return results;
 }  /* GetMsgs */

void KKThread::Kill ( )

stops the running thread and frees the thread handle

Definition at line 427 of file KKThread.cpp.

Referenced by KKB::KKThreadManager::KillAllRunningThreads(), and WaitForThreadToStop().

 {
     if  (windowsThreadHandle == NULL)
     return; 
 
     WaitForSingleObject (windowsThreadHandle, INFINITE);
     CloseHandle (windowsThreadHandle);
     windowsThreadHandle = NULL;
 }  /* Kill */

kkint32 KKThread::MemoryConsumedEstimated ( )

Definition at line 117 of file KKThread.cpp.

References KKB::MsgQueue::MemoryConsumedEstimated(), KKB::KKThreadList::MemoryConsumedEstimated(), and KKB::KKStr::MemoryConsumedEstimated().

Referenced by KKB::KKThreadList::MemoryConsumedEstimated().

 {
   kkint32  estMem = sizeof (crashed)                + 
                   sizeof (msgQueue)               + 
                   sizeof (shutdownFlag)           +
                   sizeof (startPrerequisites)     +
                   sizeof (shutdownPrerequisites)  +
                   sizeof (status)                 + 
                   sizeof (terminateFlag)          +
                   threadName.MemoryConsumedEstimated ();
 
   if  (msgQueue)
     estMem += msgQueue->MemoryConsumedEstimated ();
 
   if  (startPrerequisites)
     estMem += startPrerequisites->MemoryConsumedEstimated ();
 
   if  (shutdownPrerequisites)
     estMem += shutdownPrerequisites->MemoryConsumedEstimated ();
 
   return  estMem;
 }

KKB::MsgQueuePtr KKB::KKThread::MsgQueue ( )

inline

Definition at line 71 of file KKThread.h.

71 {return msgQueue;}

bool KKThread::OkToShutdown ( ) const

Returns 'true' if all shutdown prerequisites are in the 'Stopped' status.

Definition at line 519 of file KKThread.cpp.

References Status(), and Stopped.

Referenced by KKB::KKThreadManager::ShutdownProcessing().

 {
   if  (!shutdownPrerequisites)
     return true;
 
   KKThreadList::const_iterator  idx;
   for  (idx = shutdownPrerequisites->begin ();  idx != shutdownPrerequisites->end ();  ++idx)
   {
     KKThreadPtr  preReq = *idx;
     if  (preReq->Status () != ThreadStatus::Stopped)
       return false;
   }
   return  true;
 }  /* OkToShutdown */

bool KKThread::OkToStart ( ) const

Returns 'true' if all start prerequisites are in the 'Running' status.

Definition at line 536 of file KKThread.cpp.

References Running, and Status().

 {
   if  (!startPrerequisites)
     return true;
 
   KKThreadList::const_iterator  idx;
   for  (idx = startPrerequisites->begin ();  idx != startPrerequisites->end ();  ++idx)
   {
     KKThreadPtr  preReq = *idx;
     if  (preReq->Status () != ThreadStatus::Running)
       return false;
   }
   return  true;
 }  /* OkToStart */

void KKThread::Run ( )

virtual

Reimplemented in KKB::KKThreadManager.

Definition at line 447 of file KKThread.cpp.

References AddMsg().

Referenced by KKB::ThreadStartCallBack().

 {
   // This method should have been over ridden by a derived class.
  const char*  msg = "KKThread::Run   ***ERROR***       This method should have been over ridden by a derived class.";
 
   cerr << endl << endl << msg << endl
        << endl;
   AddMsg (msg);
 }

VolConstBool& KKB::KKThread::ShutdownFlag ( ) const

inline

Indicates that the application wants this thread to complete what work is queued up for it top process. Threads need to monitor this flag; if it goes true they are to complete all processing that is queued up and then shutdown. This is

Definition at line 75 of file KKThread.h.

Referenced by KKB::KKThreadManager::ShutdownProcessing().

bool KKB::KKThread::ShutdownOrTerminateRequested ( )

inlineprotected

Definition at line 148 of file KKThread.h.

148 {return (terminateFlag || shutdownFlag);}

void KKThread::ShutdownThread ( )

Call this method to have its thread finish what ever is in the queue and then exit.

Definition at line 231 of file KKThread.cpp.

Referenced by KKB::KKThreadManager::ShutdownProcessing().

 {
   shutdownFlag = true;
 }

void KKThread::Start	(	ThreadPriority	_priority,
		bool &	successful
	)

Call this method to start thread; it will call the method "Run".

Definition at line 352 of file KKThread.cpp.

References KKB::KKException::KKException().

 {
   priority = _priority;
 
   windowsThreadHandle = (unsigned long*)CreateThread (NULL,
                                                 0,
                                                 (LPTHREAD_START_ROUTINE)ThreadStartCallBack,
                                                 (KKThreadPtr)this,
                                                 0,
                                                 &windowsThreadId
                                                );
   if  (windowsThreadHandle == NULL)
   {
     successful = false;
     throw KKException ("Failed to create thread");
   }
   else
   {
     threadId = (kkint32)windowsThreadId;
 
     switch  (priority)
     {
     case  ThreadPriority::Null:
     case  ThreadPriority::Normal:
       SetThreadPriority (windowsThreadHandle, THREAD_PRIORITY_BELOW_NORMAL);
       break;
 
     case  ThreadPriority::Low:
       SetThreadPriority (windowsThreadHandle, THREAD_PRIORITY_NORMAL);
       break;
 
     case  ThreadPriority::High:
       SetThreadPriority (windowsThreadHandle, THREAD_PRIORITY_ABOVE_NORMAL);
       break;
     }
     SetThreadName ();
     successful = true;
   }
 }  /* Start */

ThreadStatus KKB::KKThread::Status ( ) const

inline

Definition at line 72 of file KKThread.h.

Referenced by KKB::KKThreadManager::AllThreadsTerminated(), OkToShutdown(), OkToStart(), and KKB::KKThreadManager::ShutdownProcessing().

72 {return status;}

void KKB::KKThread::Status ( ThreadStatus _status )

inline

Definition at line 91 of file KKThread.h.

Referenced by KKB::ThreadStartCallBack().

91 {status = _status;}

const KKStr& KKB::KKThread::StatusStr ( ) const

inline

Definition at line 73 of file KKThread.h.

References ThreadStatusToStr().

73 {return ThreadStatusToStr (status);}

KKB::KKThread::ThreadStatusToStr

static const KKStr & ThreadStatusToStr(ThreadStatus)

Definition: KKThread.cpp:144

VolConstBool& KKB::KKThread::TerminateFlag ( ) const

inline

Indicates that thread is to stop processing ASAP, release any resources it holds and terminate. Threads need to monitor this flag; if it goes 'true' they need to terminate ASAP releasing all allocated resources. Typically set to true when user request to cancel processing.

Definition at line 80 of file KKThread.h.

void KKThread::TerminateFlagChanged ( )

virtual

Will be called whenever the value of 'terminateFlag' is changed; derived classes should override this method if they need to be aware that the terminaeFlag has changed. This give them a chance to let other objects/methods know that the flag has changed.

Definition at line 216 of file KKThread.cpp.

Referenced by TerminateThread().

217 {

218 }

void KKThread::TerminateThread ( )

Call this method to have its thread stop right away and exit.

Definition at line 208 of file KKThread.cpp.

References TerminateFlagChanged().

Referenced by KKB::KKThreadManager::TerminateProcessing().

 {
   terminateFlag = true;
   TerminateFlagChanged ();
 }

bool KKThread::ThereIsACircularReferenceShutdown ( KKThreadPtr _thread ) const

protected

Definition at line 480 of file KKThread.cpp.

References ThereIsACircularReferenceStart().

 {
   if  (!shutdownPrerequisites)
     return false;
 
   KKThreadList::const_iterator  idx;
   for  (idx = shutdownPrerequisites->begin ();  idx != shutdownPrerequisites->end ();  ++idx)
   {
     KKThreadPtr  preReq = *idx;
     if  (preReq == _thread)
       return true;
 
     else if  (preReq->ThereIsACircularReferenceStart (_thread))
       return true;
   }
   return  false;
 }  /* ThereIsACircularReferenceShutdown */

bool KKThread::ThereIsACircularReferenceStart ( KKThreadPtr _thread ) const

protected

Definition at line 459 of file KKThread.cpp.

References ThereIsACircularReferenceStart().

Referenced by ThereIsACircularReferenceShutdown(), and ThereIsACircularReferenceStart().

 {
   if  (!startPrerequisites)
     return false;
 
   KKThreadList::const_iterator  idx;
   for  (idx = startPrerequisites->begin ();  idx != startPrerequisites->end ();  ++idx)
   {
     KKThreadPtr  preReq = *idx;
     if  (preReq == _thread)
       return true;
 
     else if  (preReq->ThereIsACircularReferenceStart (_thread))
       return true;
   }
   return  false;
 }  /* ThereIsACircularReferenceStart */

kkint32 KKB::KKThread::ThreadId ( ) const

inline

Definition at line 86 of file KKThread.h.

86 {return threadId;}

const KKStr& KKB::KKThread::ThreadName ( ) const

inline

Definition at line 87 of file KKThread.h.

87 {return threadName;}

const KKStr & KKThread::ThreadStatusToStr ( ThreadStatus ts )

static

Definition at line 144 of file KKThread.cpp.

References KKB::KKStr::Concat(), KKB::KKStr::EmptyStr(), Null, and Stopped.

Referenced by StatusStr().

 {
   if  ((ts < ThreadStatus::Null)  ||  (ts > ThreadStatus::Stopped))
     return KKStr::EmptyStr ();
   else
     return  threadStatusDescs[(int)ts];
 }

bool KKThread::ThreadStillProcessing ( ) const

Definition at line 221 of file KKThread.cpp.

References Running, Starting, and Stopping.

 {
   return  ((status == ThreadStatus::Running)   ||  
            (status == ThreadStatus::Starting)  ||
            (status == ThreadStatus::Stopping)
           );
 }

void KKThread::WaitForThreadToStop ( kkuint32 maxTimeToWait )

Called by separate thread; will stay in loop until the thread controlled by this instance shutdown or it waited the 'maxTimeToWait'.

Does not call the 'ShutdownThread' or 'TerminateThread' methods.

Parameters

[in] maxTimeToWait Will wait 'maxTimeToWait' seconds before giving up on waiting at which point will try to kill thread.

Definition at line 238 of file KKThread.cpp.

References Kill(), NotStarted, Null, KKB::osGetLocalDateTime(), KKB::osSleepMiliSecs(), Running, KKB::DateTime::Seconds(), Stopped, and Stopping.

 {
   if  ((status == ThreadStatus::NotStarted)  || 
        (status == ThreadStatus::Stopped)     ||
        (status == ThreadStatus::Null)
       )
   {
     // Thread is not running;  we can return.
     return;
   }
 
   kkuint64  startTime = KKB::osGetLocalDateTime ().Seconds ();
   kkuint32  timeWaitedSoFar = 0;
   while  ((status == ThreadStatus::Running)  ||  (status == ThreadStatus::Stopping))
   {
       osSleepMiliSecs (50);
     if  (maxTimeToWait > 0)
     {
       kkuint64 now = osGetLocalDateTime ().Seconds ();
       timeWaitedSoFar = (kkuint32)(now - startTime);
       if  (timeWaitedSoFar > maxTimeToWait)
         break;
     }
   }
 
 
   if  ((status != ThreadStatus::NotStarted)  &&
        (status != ThreadStatus::Stopped)     &&
        (status != ThreadStatus::Null)
       )
   {
     Kill ();
   }
 
 }  /* WaitForThreadToStop */

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

C:/Users/Kurt/GitHub/KSquareLibraries/KKBase/KKThread.h
C:/Users/Kurt/GitHub/KSquareLibraries/KKBase/KKThread.cpp

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Detailed Description

Member Typedef Documentation

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation