Provides a ACS aware wrapper for ACE threads. More...

#include <acsThreadBase.h>

Inheritance diagram for ACS::ThreadBase:

Collaboration diagram for ACS::ThreadBase:

Public Types
enum	SleepReturn { SLEEP_OK = 0, SLEEP_SUSPEND, SLEEP_INTERRUPTED, SLEEP_ERROR }
Public Member Functions
	ThreadBase (const ACE_CString &_name, ACE_Thread_Manager _threadManager, void _threadProcedure, void *_parameter, const TimeInterval &_responseTime=ThreadBase::defaultResponseTime, const TimeInterval &_sleepTime=ThreadBase::defaultSleepTime, const bool _create=true, const long _thrFlags=THR_NEW_LWP\|THR_DETACHED, const size_t _stackSize=ACE_DEFAULT_THREAD_STACKSIZE)
virtual	~ThreadBase ()
ACE_CString	getName () const
void *	getThreadProcedure () const
TimeInterval	getResponseTime () const
void	setResponseTime (const TimeInterval &_responseTime)
TimeInterval	getSleepTime () const
void	setSleepTime (const TimeInterval &_sleepTime)
void	setPriority (int _priority)
int	getPriority ()
bool	suspend ()
virtual bool	resume ()
bool	isSuspended () const
bool	isStopped () const
virtual void	exit ()
bool	exitRequested () const
void	setStopped ()
bool	stop (bool terminating=false)
bool	cancel ()
bool	terminate ()
bool	restart ()
void	makeTimeInterval ()
bool	isResponding () const
bool	isAlive () const
bool	check ()
SleepReturn	sleep (TimeInterval timeIn100ns=0) const
ACE_thread_t	getThreadID ()
Static Public Member Functions
static void	setInitializers (InitThreadFunc InitThread_, DoneThreadFunc DoneThread_)
Static Public Attributes
static TimeInterval	defaultResponseTime
static TimeInterval	defaultSleepTime
static ThreadBase *	NullThreadBase
	Pointer to NULL ThreadBase object.
static InitThreadFunc	InitThread
	External thread initialization function.
static DoneThreadFunc	DoneThread
	External thread cleanup function.
Protected Member Functions
bool	create (const long _thrFlags=THR_NEW_LWP\|THR_DETACHED)
virtual void	yield ()
Private Attributes
void *	threadProcedure_mp
	thread worker function. Signature shall be compatible with ACE_THR_FUNC
const void *	parameter_mp
	thread optional parameter.
TimeInterval	responseTime_m
	heartbeat response time in 100ns unit.
TimeInterval	sleepTime_m
	thread default sleep time in 100ns unit.
TimeInterval	timeStamp_m
	thread last heartbeat time in 100ns unit.
volatile int	suspendStatus_m
	true if thread suspended, false otherwise.
volatile bool	exitRequest_m
	is thread received exit request?
volatile bool	stopped_m
	is thread stopped ?
ACE_CString	name_m
	name of the thread
ACE_thread_t	threadID_m
	thread ID
long	thrFlags_m
	Thread flags used in create, to be reused for restart.
size_t	stackSize_m
	Thread stack size.
ACE_Thread_Manager *	threadManager_mp
	thread manager
ACE_Thread_Semaphore	m_suspendSemaphore
	semaphore used for running loop
ACE_Semaphore	m_sleepSemaphore

Detailed Description

Provides a ACS aware wrapper for ACE threads.

This class provides a minimum interface to ACE threads. Note, however, that it is generally a better idea to use the <ThreadManagerBase> programming API rather than the <ThreadBase> API since the thread manager is more powerful. An example of thread function implementation performin a loop:

   static void worker (void* param)
      {
              // pointer to ThreadBaseParameter object is passed as parameter
              // it contains pointer to ThreadBase (self) object and optional extra parameter
 		ThreadBase* myself = ((ThreadBaseParameter*)param)->threadBase;

              // initialize thread
              if (ThreadBase::InitThread) ThreadBase::InitThread(myself->getName());

              // enter the loop
              // check() method ACK heartbeat and returns true unless there is an exit request
 		while (myself->check())
              {
                 // simulate suspend() for systems not supporting it
 	           if (!myself->isSuspended())
 		   {
 		        // do something meaningful here
 		   }

                 // sleep for default thread sleep time
 		   myself->sleep();
 		}

              // ACK exit state
 		myself->setStopped();

              // cleanup thread
              if (ThreadBase::DoneThread) ThreadBase::DoneThread();
 	}

Member Enumeration Documentation

enum ACS::ThreadBase::SleepReturn

Return values from sleep() method. SLEEP_OK means that the sleep() completed in the requested time SLEEP_SUSPEND that the thread was suspended during the sleep and then resumed. The actual sleep time can be therefore shorter or longer than the value requested SLEEP_INTERRUPTED that the sleep has been interrupted, for example by a cancel() request. The sleep time has been therefore shorter than requested. SLEEP_ERROR an unexpected error occurred. See error logs.

Enumerator:

SLEEP_OK
SLEEP_SUSPEND
SLEEP_INTERRUPTED
SLEEP_ERROR

Constructor & Destructor Documentation

ACS::ThreadBase::ThreadBase	(	const ACE_CString &	_name,
		ACE_Thread_Manager *	_threadManager,
		void *	_threadProcedure,
		void *	_parameter,
		const TimeInterval &	_responseTime = `ThreadBase::defaultResponseTime`,
		const TimeInterval &	_sleepTime = `ThreadBase::defaultSleepTime`,
		const bool	_create = `true`,
		const long	_thrFlags = `THR_NEW_LWP\|THR_DETACHED`,
		const size_t	_stackSize = `ACE_DEFAULT_THREAD_STACKSIZE`
	)

Constructor. Creates a new thread and starts it automatically.

Parameters:

	_name	name of the thread
	_threadManager	reference to the acsthreadManagerBase that will manage the thread
	_threadProcedure	thread worker function. Signature shall be compatible with ACE_THR_FUNC
	_parameter	an optional parameter to the thread
	_responseTime	heartbeat response time in 100ns unit
	_sleepTime	default sleep time in 100ns unit
	_create	should the thread be created in the constructoror not. Default is yes. It is used if constructor is called from a subclass. and this will take care of creating the thread or if we want to call create ourselves.
	_thrFlags	Thread creation flags to be used if _create = TRUE. See ACE threads and pthread documentation for details. Default is now THR_NEW_LWP \| THR_DETACHED
	_stackSize	The size of the stack of the thread. If ACE_DEFAULT_THREAD_STACKSIZE the default stack size is taken.

See also:: the create method for important details about joinable threads.

virtual ACS::ThreadBase::~ThreadBase ( ) [virtual]

Destructor. Also terminates the thread.

Attention:: Always call terminate() in the destructor of user implemented ThreadBase classes.
If the user thread service function uses resources of the Thread object (like accessing member variables) we have to be sure that it is terminated before the object itself is destroyed. This is job of terminate().

See also:: ThreadBase::terminate

Member Function Documentation

bool ACS::ThreadBase::cancel ( )

Cancel (forceful termination) named thread. It tries to immediately stop the thread, without waiting for the thread to gracefully exit. But also this can fail is the thread never goes into a sleep or suspend function. Therefore is the thread is still running after a ceetain time, the function timeouts and return an error. Avoid using this kind of thread termination.

Returns:: true if thread has been stopped

See also:: ThreadBase::terminate

bool ACS::ThreadBase::check ( )

Check the state of thread and update heartbeat. This method is meant to a

while(threadBase->check()) {}

condition, automatically updating heartbeat and checking for exit status of the thread. The developer of a thread is responsible for calling check() at least at heartbeat time intervals. This is very important to ensure that we can effectively stop a thread. See example of usage.

Returns:: true unless a thread has received an exit request

bool ACS::ThreadBase::create ( const long _thrFlags = THR_NEW_LWP|THR_DETACHED ) [protected]

Create a thread.

Parameters:

thrFlags_

what kind of thread should be created. Default is kernel space thread (THR_NEW_LWP) detached thread (THR_DETACHED) For a list of the available thread flags, see the documentation for the underlying ACE Threads anr/or the Linux documentation for the behavior of ACE Threads under Linux.

Attention:: A joinable thread must be joined, or we loose system resources. If a joinable thread is not joined after completion, some system resources will remain allocated (see pthread documentation). After the creation of a few hundred threads, the system will be unable to allocate more threads.

virtual void ACS::ThreadBase::exit ( ) [inline, virtual]

Notify thread to exit thread worker function. Thread worker function should always exit when this notification was issued. See example of usage.

Reimplemented in RequestProcessorThread, and ControllerThread.

References exitRequest_m.

Referenced by TestACSThread::runLoop(), SamplingThreadFlush< ACS_SAMP_TL >::runLoop(), and SamplingThread< ACS_SAMP_TL >::runLoop().

bool ACS::ThreadBase::exitRequested ( ) const [inline]

Has thread already received an exit request

Returns:: true if thread has already received an exit request

References exitRequest_m.

ACE_CString ACS::ThreadBase::getName ( ) const [inline]

Get name of the thread.

Returns:: name of the thread

References name_m.

Referenced by TestACSThread::runLoop(), and SamplingThreadFlush< ACS_SAMP_TL >::runLoop().

int ACS::ThreadBase::getPriority ( )

Get thread priority.

Returns:: priority (OS dependent)

TimeInterval ACS::ThreadBase::getResponseTime ( ) const [inline]

Get heartbeat response time in 100ns unit.

Returns:: heartbeat response time in 100ns unit

See also:: ThreadBase::isResponding

References responseTime_m.

TimeInterval ACS::ThreadBase::getSleepTime ( ) const [inline]

Get default sleep time in 100ns unit.

Returns:: default sleep time in 100ns unit

See also:: ThreadBase::sleep

References sleepTime_m.

ACE_thread_t ACS::ThreadBase::getThreadID ( ) [inline]

Returns ACE specific thread ID of the base thread

References threadID_m.

void* ACS::ThreadBase::getThreadProcedure ( ) const [inline]

Get thread worker function.

Returns:: function pointer to the thread worker function. Signature shall be compatible with ACE_THR_FUNC

References threadProcedure_mp.

bool ACS::ThreadBase::isAlive ( ) const [inline]

Checks if named thread is alive (not terminated/stopped).

Returns:: true if named thread is alive

References stopped_m.

bool ACS::ThreadBase::isResponding ( ) const

Checks if named thread is alive (has heartbeat). Having a hearbeat means that <ThreadBase::check()> was called within last <ThreadBase::defaultResponseTime> time.

Parameters:

name

name of the thread

Returns:: true if named thread is alive (has heartbeat)

See also:: ThreadBase::getDefaultResponseTime

bool ACS::ThreadBase::isStopped ( ) const [inline]

Check if thread is already stopped.

Returns:: true if thread is stoped

References stopped_m.

bool ACS::ThreadBase::isSuspended ( ) const [inline]

Check if thread is already suspended.

Returns:: true if thread is suspended

References suspendStatus_m.

void ACS::ThreadBase::makeTimeInterval ( )

Update last heartbeat time. To be used inside the thread function. It is called in check() and can be called by the thread developer to provide an "intermediate checkpoint" if check() cannot be called at the desired frequency.

bool ACS::ThreadBase::restart ( )

Restart the thread. Restarting means terminate and recreate a new thread (i.e. calling terminate() and create() methods).

See also:: ThreadBase::terminate; ThreadBase::create

virtual bool ACS::ThreadBase::resume ( ) [virtual]

Continue the execution of a previously suspended thread.

Returns:: true if operation was successful

static void ACS::ThreadBase::setInitializers	(	InitThreadFunc	InitThread_,
		DoneThreadFunc	DoneThread_
	)			`[inline, static]`

Set external thread initialization and cleanup functions for all threads This allows users of the thread library to define what initialisation and thread functions will have to be called, to customize the behavior of threads based on the rest of the infrastructure. For example, ACS Containers use setInitialisers to control initialisatoin and cleanup of the logging system for each thread.

Parameters:

	InitThread_	thread initialization function
	DoneThread_	thread cleanup function

References DoneThread, and InitThread.

void ACS::ThreadBase::setPriority ( int _priority )

Set thread priority.

Parameters:

_priority

(OS dependent)

void ACS::ThreadBase::setResponseTime ( const TimeInterval & _responseTime ) [inline]

Set heartbeat response time in 100ns unit.

Parameters:

_responseTime

heartbeat response time in 100ns unit

See also:: ThreadBase::isResponding

References responseTime_m.

void ACS::ThreadBase::setSleepTime ( const TimeInterval & _sleepTime ) [inline]

Set default sleep time in 100ns unit.

Parameters:

_sleepTime

default sleep time in 100ns unit

See also:: ThreadBase::sleep

References sleepTime_m.

void ACS::ThreadBase::setStopped ( ) [inline]

Set thread state as stopped. This function should be called in the thread worker function. See example of usage.

References stopped_m.

SleepReturn ACS::ThreadBase::sleep ( TimeInterval timeIn100ns = 0 ) const

Sleep for given amount of time in 100ns units. If 0 time is given, then default sleep time is used.

This method shall be used INSIDE a thread service function and not outside.

It takes care of handling suspend conditions and of waking up the thread if requested, as if a signal was sent. Instead of an operating system sleep, this method is implemented trying to acquire a busy semaphore with a timeout equal to the sleep time. This allows to "interrupt the sleep" releasing the semaphore from another thread.

Since the sleep can be interrupted, the user shall always call check() after returning from sleep() to verify is the sleep simply completed or was interrupted by a request to resume or exit.

Parameters:

timeIn100ns

time to sleep in 100ns unit.

Returns:: The reason for returning from the sleep method.

bool ACS::ThreadBase::stop ( bool terminating = false )

Stop the thread. Stopping means notifying thread by calling exit() method and then waiting for a while thread to stop, i.e. checking until thread gets in stopped state If after some time the thread is not exited, the method timeouts and returns an error See example of usage.

Parameters:

terminating,set

to true when called by terminate(), for control the "did not stop.." message

Returns:: true if thread has been stopped

bool ACS::ThreadBase::suspend ( )

Suspend the execution of a particular thread. If the suspend function is not supported by the underlying thread implementation, the suspend is simulated.
See example of usage.

Returns:: true if operation was successful

bool ACS::ThreadBase::terminate ( )

Terminate the thread. Terminating means calling stop() method and if even then the thread does not stop, then the cancel() method is called.

Returns:: true if thread has been stopped

See also:: ThreadBase::terminate; ThreadBase::create

Referenced by TestACSThread::~TestACSThread().

virtual void ACS::ThreadBase::yield ( ) [protected, virtual]

Yield the thread to another another ready-to-run, active thread. This method shall (and can) be called just from inside the thread, because we can yield just from actaul/current thread! We can not ask another thread to yield!

Member Data Documentation

TimeInterval ACS::ThreadBase::defaultResponseTime [static]

Default heartbeat response time in 100ns unit. A thread is responsive if the check() method is called at most every defaultResponseTime 100ns. Responsiveness can be verified by calling isResponding().

See also:: ThreadBase::check; ThreadBase::isResponsive

TimeInterval ACS::ThreadBase::defaultSleepTime [static]

Default default sleep time in 100ns unit. Defines the time the thread will sleep if sleep() is called without any parameter. It is typically used when implementing a periodic loop in the thread to define the time the thread shall sleep between two iterations of the loop.

DoneThreadFunc ACS::ThreadBase::DoneThread [static]

External thread cleanup function.

Referenced by setInitializers().

volatile bool ACS::ThreadBase::exitRequest_m [private]

is thread received exit request?

Referenced by exit(), and exitRequested().

InitThreadFunc ACS::ThreadBase::InitThread [static]

External thread initialization function.

Referenced by setInitializers().

ACE_Semaphore ACS::ThreadBase::m_sleepSemaphore [mutable, private]

ACE_Thread_Semaphore ACS::ThreadBase::m_suspendSemaphore [mutable, private]

semaphore used for running loop