eut::RepeatingThread Class Reference

Base class for a thread that executes its work endlessly until aborted. More...

#include <EuRepeatingThread.h>

Inheritance diagram for eut::RepeatingThread:

Public Types
enum	EuTHREADERROR { EuTHREAD_ERR_NO_THREAD = -10301 , EuTHREAD_ERR_THREAD_ALREADY_WORKING = -10302 , EuTHREAD_ERR_THREAD_BREAK_COUNT_LESS_THAN_ZERO = -10303 , EuTHREAD_ERR_UNKNOWN = -10400 }
	Error range = -10301 to -10400 More...
enum	ORDER { eUNDEFINED , eDO_WORK , eEXIT }
enum	STATUS {   eAT_THE_START , eWORKING , ePAUSING , eENDING ,   eCOMPLETED }

Public Member Functions
	RepeatingThread ()
virtual	~RepeatingThread ()
virtual void	cancel ()
virtual void	finishBreak ()
int	getBreakCounter ()
bool	isInExclusiveAccess () const
void	setExclusiveAccess ()
void	signalInput ()
virtual int	start ()
RepeatingThread::STATUS	status () const
virtual void	takeABreak ()
bool	testCancel ()
void	unsetExclusiveAccess ()
void	waitForInput ()

Public Attributes
std::string	m_strDebugInfo

Protected Member Functions
ORDER	getOrder ()
STATUS	getStatus ()
void	setStatus (STATUS eStatus)
void	threadWork ()
void	toOrder (ORDER eOrder)
virtual void	work ()=0

Private Member Functions
	RepeatingThread (const RepeatingThread &)
RepeatingThread &	operator= (const RepeatingThread &)

Private Attributes
std::condition_variable	m_BreakCondVar
std::mutex	m_BreakMutex
ORDER	m_eOrder
STATUS	m_eStatus
CriticalSection	m_ExclusiveAccessSection
int	m_iBreakCounter
int	m_iDataReady
std::condition_variable	m_InputCondVar
std::thread *	m_pThread
std::mutex	m_WaitMutex

Detailed Description

Base class for a thread that executes its work endlessly until aborted.

In subclasses, only the virtual method RepeatingThread::work() must be overwritten.

Attention

The thread must be terminated after the start with cancel() before calling the destructor!

Author

Helmut Jakoby

Copyright

© 2010 Helmut Jakoby

Member Enumeration Documentation

EuTHREADERROR

enum eut::RepeatingThread::EuTHREADERROR

Error range = -10301 to -10400

Enumerator
EuTHREAD_ERR_NO_THREAD	-10301: An expected thread is not available or not started.
EuTHREAD_ERR_THREAD_ALREADY_WORKING	-10302: The thread is already started.
EuTHREAD_ERR_THREAD_BREAK_COUNT_LESS_THAN_ZERO	-10303: The thread has been woken from sleep too often.
EuTHREAD_ERR_UNKNOWN	-10400: Undefined error.

ORDER

enum eut::RepeatingThread::ORDER

A RepeatingThread can be given instructions after the start.

Enumerator
eUNDEFINED	Undefined.
eDO_WORK	Thread should work.
eEXIT	Thread should end.

STATUS

enum eut::RepeatingThread::STATUS

To be able to control the thread, it is helpful to know the work status.

Enumerator
eAT_THE_START	The thread has not yet worked.
eWORKING	The thread is working.
ePAUSING	The thread is paused.
eENDING	The thread is just finishing its work.
eCOMPLETED	The thread is finished with its work.

Constructor & Destructor Documentation

RepeatingThread() [1/2]

eut::RepeatingThread::RepeatingThread

(

)

Standard constructor.

~RepeatingThread()

virtual eut::RepeatingThread::~RepeatingThread ( )

virtual

Destructor.

Attention

The method cancel() must be called before the destructor! Since cancel() is virtual, it cannot be executed in dtor.

RepeatingThread() [2/2]

eut::RepeatingThread::RepeatingThread ( const RepeatingThread & )

private

The copy constructor is not available.

Member Function Documentation

cancel()

virtual void eut::RepeatingThread::cancel ( )

virtual

Terminates the thread.

Attention

Must be called before the destructor if started with start()! Since cancel() is virtual, it cannot be executed in dtor.

Reimplemented in tcp::Client, tcp::ClientReceiver, tcp::Server, tcp::ServerAcceptReceiver, tcp::ServerReceiver, tcp::Transmitter, glo::ClientThread, glo::CommunicaterThread, glo::LocalThread, glo::Server, and glo::WatchNotifyManager.

finishBreak()

virtual void eut::RepeatingThread::finishBreak ( )

virtual

Ends the working pause. Must have been initiated by takeABreak().

Reimplemented in tcp::ReceiverTransmitter.

getBreakCounter()

int eut::RepeatingThread::getBreakCounter

(

)

Returns the pause counter.

See also

m_iBreakCounter

getOrder()

ORDER eut::RepeatingThread::getOrder ( )

protected

Returns the last transferred instruction.

Returns

The current instructions.

getStatus()

STATUS eut::RepeatingThread::getStatus ( )

protected

Returns the current status.

Returns

The seted status.

isInExclusiveAccess()

bool eut::RepeatingThread::isInExclusiveAccess

(

)

const

Is the thread in an exclusive area?

Returns

If true, it's in an exclusive area.

See also

setExclusiveAccess() and unsetExclusiveAccess()

operator=()

RepeatingThread & eut::RepeatingThread::operator= ( const RepeatingThread & )

private

Assignment operator is not available.

setExclusiveAccess()

void eut::RepeatingThread::setExclusiveAccess

(

)

Initiates a CriticalSection. Must be canceled using unsetExclusiveAccess ().

See also

m_ExclusiveAccessSection

setStatus()

void eut::RepeatingThread::setStatus ( STATUS eStatus )

protected

Set the status.

Parameters

[in]

eStatus

The status to be set.

signalInput()

void eut::RepeatingThread::signalInput

(

)

Ends the wait without activity initiated by waitForInput().

start()

virtual int eut::RepeatingThread::start ( )

virtual

Starts the thread.

Returns

A return value < 0 indicates an error. E.g. if thread is already running.

Attention

The thread must be terminated after start() before the destructor with cancel().

status()

RepeatingThread::STATUS eut::RepeatingThread::status

(

)

const

Returns the status of the thread.

Returns

The status.

takeABreak()

virtual void eut::RepeatingThread::takeABreak ( )

virtual

Initiates a pause of the thread to interrupt the processing. Must be ended again with finishBreak().

Note

Since the thread only skips the processing (i.e. is still running) a real suspension of the thread can be achieved by using the method waitForInput() in the method work() of the derived class.

Reimplemented in tcp::ReceiverTransmitter.

testCancel()

bool eut::RepeatingThread::testCancel

(

)

Returns true when thread has ended.

Returns

see above.

threadWork()

void eut::RepeatingThread::threadWork ( )

protected

This method, executed by the thread, calls the method work() in a loop.

toOrder()

void eut::RepeatingThread::toOrder ( ORDER eOrder )

protected

Accepts the transferred instruction.

Parameters

[in]

eOrder

The statement to be set.

unsetExclusiveAccess()

void eut::RepeatingThread::unsetExclusiveAccess

(

)

Cancels an initiated CriticalSection if set by setExclusiveAccess()

See also

m_ExclusiveAccessSection

waitForInput()

void eut::RepeatingThread::waitForInput

(

)

Lets the thread wait at a defined position without activity. Must be terminated again by signalInput().

Note

This method can be used in the method work() of a derived class to suspend the thread. The thread wakes up again with signalInput(), which must also be initiated in the derived class.

work()

virtual void eut::RepeatingThread::work ( )

protectedpure virtual

This method is executed by the thread and must be overwritten in subclasses.

See also

threadWork()

Implemented in tcp::Client, tcp::ClientReceiver, tcp::Server, tcp::ServerAcceptReceiver, tcp::ServerReceiver, tcp::Transmitter, glo::CommunicaterThread, glo::Communicator, glo::Manager, and glo::WatchNotifyManager.

Member Data Documentation

m_BreakCondVar

std::condition_variable eut::RepeatingThread::m_BreakCondVar

private

Condition_variable to pause

See also

threadWork(), finishBreak() and m_BreakMutex

m_BreakMutex

std::mutex eut::RepeatingThread::m_BreakMutex

private

Mutex to pause.

See also

threadWork() und m_BreakCondVar

m_eOrder

ORDER eut::RepeatingThread::m_eOrder

private

A thread can be given a command which is set here.

m_eStatus

STATUS eut::RepeatingThread::m_eStatus

private

The working status.

m_ExclusiveAccessSection

CriticalSection eut::RepeatingThread::m_ExclusiveAccessSection

private

Is required to define access protected areas by RepeatingThread::setExclusiveAccess() or RepeatingThread::unsetExclusiveAccess().

m_iBreakCounter

int eut::RepeatingThread::m_iBreakCounter

private

If a RepeatingThread is to pause, this counter is incremented. If the thread should wake up again, this counter is decremented. At 0 the thread is woken up again.

This enables a nested sleep and wake up.

m_iDataReady

int eut::RepeatingThread::m_iDataReady

private

To avoid "lost wakeup" and "spurious wakeups" this variable is necessary.

• Lost wakeup: The phenomenon of the lost wakeup is that the sender sends its notification before the receiver gets to its wait state. The consequence is that the notification is lost. The C++ standard describes condition variables as a simultaneous synchronisation mechanism: "The condition_variable class is a synchronisation primitive that can be used to block a thread, or multiple threads at the same time, ...". So the notification gets lost, and the receiver is waiting and waiting and ... .
• Spurious wakeup: It may happen that the receiver wakes up, although no notification happened. At a minimum POSIX Threads and the Windows API can be victims of these phenomena.

Found in: https://www.modernescpp.com/index.php/c-core-guidelines-be-aware-of-the-traps-of-condition-variables

m_InputCondVar

std::condition_variable eut::RepeatingThread::m_InputCondVar

private

Condition_variable to wait for input.

See also

waitForInput(), signalInput() and m_WaitMutex

m_pThread

std::thread* eut::RepeatingThread::m_pThread

private

The 'real' thread.

m_strDebugInfo

std::string eut::RepeatingThread::m_strDebugInfo

Here you can write something in for DEBUG purposes.

m_WaitMutex

std::mutex eut::RepeatingThread::m_WaitMutex

private

Mutex to wait for input.

See also

waitForInput() and m_InputCondVar

---

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

• EuRepeatingThread.h