ACS::ThreadBase

NAME
SYNOPSIS
Detailed Description
Member Enumeration Documentation
Constructor & Destructor Documentation
Member Function Documentation
Member Data Documentation
Author

NAME

ACS::ThreadBase −

Provides a ACS aware wrapper for ACE threads.

SYNOPSIS

#include <acsThreadBase.h>

Inherits Logging::Loggable.

Inherited by ACS::Thread.

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, ControllerThread, and AcsBulkdata::BulkDataNTArrayThread.

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

ACE_CString ACS::ThreadBase::getName () const [inline] Get name of the thread.

Returns:

name of the thread

Reimplemented in AcsBulkdata::BulkDataNTArrayThread.

Referenced by ACS::ThreadManager::destroy(), 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

TimeInterval ACS::ThreadBase::getSleepTime () const [inline] Get default sleep time in 100ns unit.

Returns:

default sleep time in 100ns unit

See also:

ThreadBase::sleep

ACE_thread_t ACS::ThreadBase::getThreadID () [inline] Returns ACE specific thread ID of the base thread

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

bool ACS::ThreadBase::isAlive () const [inline] Checks if named thread is alive (not terminated/stopped).

Returns:

true if named thread is alive

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

bool ACS::ThreadBase::isSuspended () const [inline] Check if thread is already suspended.

Returns:

true if thread is suspended

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

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

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

void ACS::ThreadBase::setStopped () [inline] Set thread state as stopped. This function should be called in the thread worker function. See example of usage.

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.

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

is thread received exit request?

InitThreadFunc ACS::ThreadBase::InitThread [static]

External thread initialization function.

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

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

semaphore used for running loop

ACE_CString ACS::ThreadBase::name_m [private]

name of the thread

ThreadBase* ACS::ThreadBase::NullThreadBase [static]

Pointer to NULL ThreadBase object.

const void* ACS::ThreadBase::parameter_mp [private]

thread optional parameter.

TimeInterval ACS::ThreadBase::responseTime_m [private]

heartbeat response time in 100ns unit.

TimeInterval ACS::ThreadBase::sleepTime_m [private]

thread default sleep time in 100ns unit.

size_t ACS::ThreadBase::stackSize_m [private]

Thread stack size.

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

is thread stopped ?

volatile int ACS::ThreadBase::suspendStatus_m [private]

true if thread suspended, false otherwise.

ACE_thread_t ACS::ThreadBase::threadID_m [private]

thread ID

ACE_Thread_Manager* ACS::ThreadBase::threadManager_mp [private]

thread manager

void* ACS::ThreadBase::threadProcedure_mp [private]

thread worker function. Signature shall be compatible with ACE_THR_FUNC

long ACS::ThreadBase::thrFlags_m [private]

Thread flags used in create, to be reused for restart.

TimeInterval ACS::ThreadBase::timeStamp_m [private]

thread last heartbeat time in 100ns unit.

Author

Generated automatically by Doxygen for ACS-2015.2 C++ API from the source code.