ACS::ThreadBase Class Reference
Provides a ACS aware wrapper for ACE threads.
More...
#include <acsThreadBase.h>
Inheritance diagram for ACS::ThreadBase:
[legend]Collaboration diagram for ACS::ThreadBase:
[legend]List of all members.
|
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 |
void | setInitializers (InitThreadFunc InitThread_, DoneThreadFunc DoneThread_) |
Static Public Attributes |
TimeInterval | defaultResponseTime |
TimeInterval | defaultSleepTime |
ThreadBase * | NullThreadBase |
| Pointer to NULL ThreadBase object.
|
InitThreadFunc | InitThread |
| External thread initialization function.
|
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_Thread_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
|
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. - Enumeration values:
-
SLEEP_OK |
|
SLEEP_SUSPEND |
|
SLEEP_INTERRUPTED |
|
SLEEP_ERROR |
|
|
Constructor & Destructor Documentation
|
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] |
|
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
|
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:
-
- 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 |
( |
|
) |
|
|
virtual bool ACS::ThreadBase::resume |
( |
|
) |
[virtual] |
|
|
Continue the execution of a previously suspended thread. - Returns:
- true if operation was successful
|
|
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:
-
|
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. |
|
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 |
( |
|
) |
|
|
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
|
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
|
|
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. |
|
External thread cleanup function.
|
|
is thread received exit request?
|
|
External thread initialization function.
|
|
semaphore used for running loop
|
|
thread optional parameter.
|
|
heartbeat response time in 100ns unit.
|
|
thread default sleep time in 100ns unit.
|
|
true if thread suspended, false otherwise.
|
|
thread worker function. Signature shall be compatible with ACE_THR_FUNC
|
|
Thread flags used in create, to be reused for restart.
|
|
thread last heartbeat time in 100ns unit.
|
The documentation for this class was generated from the following file:
Generated on Thu Apr 30 02:37:00 2009 for ACS C++ API by
1.3.8