ADTF  v2.14.3
cThread Class Reference

Thread class encapsulate the operating system dependent implementation of using Threads. More...

Inheritance diagram for cThread:

Classes

struct  tThreadInfo
 Thread infomation for creating threads. More...
 

Public Types

enum  tThreadState { TS_New = 0, TS_Suspended = 1, TS_Running = 2, TS_Finished = 3 }
 Threadstate of the Thread. More...
 
enum  tThreadFlags { TF_None = 0x00, TF_Suspended = 0x01, TF_RealtimeScheduler = 0x02, TF_SelfManaged = 0x04 }
 The Thread Creation Flags. More...
 
enum  tThreadPriorities {
  TP_Undefined = 0x00, TP_Idle = 0x01, TP_BelowNormal = 0x02, TP_Normal = 0x03,
  TP_AboveNormal = 0x04, TP_High = 0x05, TP_Realtime = 0x06, TP_RealtimeMin = 0x0101,
  TP_RealtimeMax = TP_RealtimeMin + 98
}
 Thread Priorities. More...
 
typedef tResult(__STDCALLtThreadEntrance) (tVoid *pvUserData, tSize szUserData)
 Type of thread entry function.
 
typedef tVoid(* tPostDestroyFunc) ()
 Methods that can be passed as post destroy callback.
 
typedef tPostDestroyFunc tPostDestoryFunc
 Methods that can be passed as post destroy callback. More...
 

Public Member Functions

const tThreadInfoGetThreadInfo () const
 Returns the thread info struct. More...
 
 cThread ()
 Default constructor.
 
virtual ~cThread ()
 Destructor.
 
virtual tResult Create (tVoid *pvUserData=NULL, tSize szUserData=0, tUInt32 ui32Flags=0, IThreadFunc *pThreadFunc=NULL, tThreadEntrance fnThreadEntrance=NULL)
 Creates the thread. More...
 
virtual tResult Create (const tThreadInfo *psThreadInfo)
 Creates the thread. More...
 
virtual tVoid Release ()
 Releases all allocated resources and stops the thread.
 
tResult Run (tBool bWait=tFalse)
 Sets the thread state to running. More...
 
tResult Suspend (tBool bWait=tFalse)
 Sets the thread state to suspended. More...
 
tResult Reset (tBool bWait=tFalse)
 Resets/Restarts the thread (ThreadInitFunc etc. More...
 
tResult Terminate (tBool bWait=tFalse)
 Terminates the thread. More...
 
tBool IsCurrent () const
 Checks whether the thread is the calling thread. More...
 
tThreadState GetState () const
 Returns the current state of the thread. More...
 
tResult WaitForExit (tInt nTimeout=WAIT_Infinite)
 Blocks the calling thread until the thread has exited. More...
 
tResult SetPriority (tInt nPriority, tUInt32 ui32Flags=0)
 Set the scheduling priority of the thread. More...
 
tResult SetPostDestroyFunc (tPostDestroyFunc pFunc)
 The passed method will be called after this thread has been deleted, if it is self managed. More...
 
tResult SetProcessorAffinity (tUInt64 nMask)
 Set the CPU affinity of the thread. More...
 
tResult GetProcessorAffinity (tUInt64 *pnMask)
 Get the processor affinity of the thread. More...
 
tInt GetId () const
 Returns the system thread id of the current thread The thread id is guaranteed to be unique in the whole system. More...
 

Static Public Member Functions

static tVoid Sleep (tTimeStamp tmMicroseconds)
 The calling thread will sleep for the specified amount of time. More...
 
static tVoid YieldExecution ()
 Gives the scheduler a chance to schedule another thread. More...
 

Static Public Attributes

static const tInt WAIT_Infinite = -1
 definition of wait infinite value
 

Protected Member Functions

virtual tResult ThreadLoop ()
 This will will be called repeatedly by the default ThreadFunc while the Thread is in state running. More...
 
virtual tResult ThreadFunc ()
 This is the default Thread entrance that will be called. More...
 
virtual tResult ThreadInitFunc ()
 This function will be called before the first call to ThreadLoop. More...
 
virtual tResult ThreadExitFunc ()
 This will be called after the last call to ThreadLoop. More...
 
tResult SetState (tThreadState ThreadState, tBool bWait=tFalse)
 Set current state of thread. More...
 
tResult EnableSelfManaged ()
 This can be used by a thread to turn itself into a self managed thread while it is running. More...
 

Detailed Description

Thread class encapsulate the operating system dependent implementation of using Threads.

You can subclass this class and overwrite the virtual methods (e.g ThreadFunc())

When using this the behavior on every supported system should be the same. When something is not supported, have look at the return value of the function.

The cThread implementation always run a ThreadLoop, which runs a managed state machine. This state machine states will be have the states shown in cThread::tThreadState.
To control the thread state from outer space the state can also be set from by using Run, Terminate, Suspend.
The ThreadLoop will call the cThread::ThreadFunc cyclic only when ThreadFunc returns with no error. Otherwise the ThreadLoop will be left and the Thread will set the finished state cThread::TS_Finished by itself.

Remarks
This Thread class is for providing common threading support. When using threading within a ADTF filter or in any other streaming component, use the basic class adtf::cKernelThread. This basic class will encapsulate the using of the adtf::IKernel interface.

Definition at line 660 of file thread.h.

Member Typedef Documentation

Methods that can be passed as post destroy callback.

Deprecated! Use

See also
tPostDestroyFunc

Definition at line 806 of file thread.h.

Member Enumeration Documentation

The Thread Creation Flags.

Enumerator
TF_None 

no flag set.

TF_Suspended 

Create suspended.

TF_RealtimeScheduler 

Only supported by Linux: The thread will use SCHED_FF scheduling policy.

Thread priority can be in interval [TP_RTMin..TP_RTMax].

TF_SelfManaged 

The Thread will delete the thread object when it finishes.

Do not call any other functions after creation!

Definition at line 688 of file thread.h.

Thread Priorities.

Windows: The windows SDK is bound to these enumerations only. They are to be used analogously to the priority stages defined by MSVC: http://msdn.microsoft.com/en-us/library/windows/desktop/ms686277%28v=vs.85%29.aspx

Linux: Commonly no numerical priorities are being used. Up until TP_Normal, only scheduling modes are being altered (as predetermined by Linux pthreads). Priorities may be specified but will have no effect. From TP_AboveNormal upwards, however, real-time scheduling with slightly different manifestations are being applied (see below). Within these stages either the specified priorities may be used or any priority in between 0..99, depending on the implementation of the operating system, may be chosen. (see adtf::IKernel::ThreadCreate and cThread::Create)

Warning: A thread with higher priority may indefinitely block other, important threads if it does not yield execution (applies especially to Linux and the RT scheduling mechanisms and is commonly called "starvation").

Enumerator
TP_Undefined 

Same as TP_Normal.

TP_Idle 

Thread will be in Idle Mode.

Linux specific: Thread will use SCHED_IDLE scheduling policy without a specific scheduling priority. Scheduling is entirely up to the kernel and determined by the scheduling policy.

TP_BelowNormal 

Thread will be Below Normal.

Linux specific: Thread will use SCHED_BATCH scheduling policy without a specific scheduling priority. Scheduling is entirely up to the kernel and determined by the scheduling policy.

TP_Normal 

Thread will have Normal priority.

Linux specific: Thread will use SCHED_OTHER scheduling policy without a specific scheduling priority. Scheduling is entirely up to the kernel and determined by the scheduling policy.

TP_AboveNormal 

Thread will be Above Normal priority.

Linux specific: Thread will use priority 1 with scheduling policy SCHED_RR or SCHED_FF when cThread::TF_RealtimeScheduler is set

TP_High 

Thread will have High priority.

Linux specific: Thread will use priority 50 with scheduling policy SCHED_RR or SCHED_FF when cThread::TF_RealtimeScheduler is set

TP_Realtime 

Thread will have Real time priority.

Linux specific: Thread will use priority 99 with scheduling policy SCHED_RR or SCHED_FF when cThread::TF_RealtimeScheduler is set

TP_RealtimeMin 

Realtime priority representation, lower bound.

Linux specific: Thread will use SCHED_RR or SCHED_FF cThread::TF_RealtimeScheduler scheduling policy with native RT priority 1.
To assign a specific, native RT Priority 30 use for instance cKernel::ThreadSetPriority(<handle>,IKernel::TP_RealtimeMin+30)

TP_RealtimeMax 

Realtime priority representation, upper bound.

Linux specific: Thread will use SCHED_RR or SCHED_FF cThread::TF_RealtimeScheduler scheduling policy with native RT priority 99.

Definition at line 726 of file thread.h.

Threadstate of the Thread.

Enumerator
TS_New 

The thread is created, but not running yet.

TS_Suspended 

The thread loop is running and will sleepy wait until a state change request.

TS_Running 

The thread loop is running and will call the ThreadFunc.

TS_Finished 

The thread is terminated (left the ThreadLoop).

Definition at line 673 of file thread.h.

Member Function Documentation

virtual tResult Create ( tVoid pvUserData = NULL,
tSize  szUserData = 0,
tUInt32  ui32Flags = 0,
IThreadFunc pThreadFunc = NULL,
tThreadEntrance  fnThreadEntrance = NULL 
)
virtual

Creates the thread.

Parameters
pvUserData[in] User data that will be passed to the pThreadFunc or fnThreadEntrance.
szUserData[in] Size of the user data.
ui32Flags[in] See tThreadFlags
pThreadFunc[in] The IThreadFunc interface to use.
fnThreadEntrance[in] The thread entrance function to use, will override pThreadFunc.
Return values
ERR_NOERRORif all went well.
ERR_FAILEDif thread could not be created
ERR_NOT_SUPPORTED(Linux) if thread should be suspended with external thread loop

Reimplemented in cCyclicThread.

virtual tResult Create ( const tThreadInfo psThreadInfo)
virtual

Creates the thread.

Parameters
psThreadInfo[in] Creation info struct.
Return values
ERR_NOERRORif all went well.
ERR_POINTERif psThreadInfo is NULL
ERR_FAILEDif thread could not be created
ERR_NOT_SUPPORTED(Linux) if thread should be suspended with external thread loop

Reimplemented in cCyclicThread.

tResult EnableSelfManaged ( )
protected

This can be used by a thread to turn itself into a self managed thread while it is running.

There is no way to switch back!

Returns
Standard result
tInt GetId ( ) const

Returns the system thread id of the current thread The thread id is guaranteed to be unique in the whole system.

Returns
-1 if thread is not running system thread id otherwise
tResult GetProcessorAffinity ( tUInt64 pnMask)

Get the processor affinity of the thread.

Parameters
pnMask[out] Affinity mask of thread.
Returns
Returns the standard result code.
tThreadState GetState ( ) const

Returns the current state of the thread.

Returns
The state of the thread.
const tThreadInfo* GetThreadInfo ( ) const

Returns the thread info struct.

NEVER EVER RETURN NULL ON THIS!

Returns
The thread info struct.
tBool IsCurrent ( ) const

Checks whether the thread is the calling thread.

Returns
tTrue if the thread is the current thread, tFalse otherwise.
This method is real-time safe.
See The ADTF Real-Time Extension.
tResult Reset ( tBool  bWait = tFalse)

Resets/Restarts the thread (ThreadInitFunc etc.

will be called).

Parameters
bWait[in] Whether or not to wait for an acknowledgment.
Return values
ERR_NOERRORif all went well
ERR_NOT_INITIALISEDif thread was not yet initialized, e.g. Create was not called
ERR_NOT_SUPPORTEDif thread is in an state that cannot be suspended
ERR_UNEXPECTEDif thread could not be suspended for any other reason
tResult Run ( tBool  bWait = tFalse)

Sets the thread state to running.

Parameters
bWait[in] Whether or not to wait for an acknowledgment.
Return values
ERR_NOERRORif all went well
ERR_NOT_INITIALISEDif thread was not yet initialized, e.g. Create was not called
ERR_NOT_SUPPORTEDif thread is in an state that cannot be run
ERR_UNEXPECTEDif thread could not be run for any other reason
tResult SetPostDestroyFunc ( tPostDestroyFunc  pFunc)

The passed method will be called after this thread has been deleted, if it is self managed.

Parameters
[in]pFuncThe method to call after this thread was self destroyed.
Returns
Standard result.
tResult SetPriority ( tInt  nPriority,
tUInt32  ui32Flags = 0 
)

Set the scheduling priority of the thread.

Parameters
nPriority[in] See cThread::tThreadPriorities.
ui32Flags[in] See cThread::tThreadFlags. When TF_Realtime_FF or TF_Realtime_RR is used priority value range is [1..99].
Return values
ERR_NOERRORif priority could be set
ERR_FAILEDif something did not work.
ERR_INVALID_ARGThe given priority could not be applied. It most likely is out of range of what the current user (unix) may set or what the system supports.
ERR_NOT_SUPPORTEDThe combination of priorities and flags do not make sense or are not supported due to limitations of the current operating system.
This method is real-time safe.
See The ADTF Real-Time Extension.
tResult SetProcessorAffinity ( tUInt64  nMask)

Set the CPU affinity of the thread.

Parameters
nMask[in] New affinity mask of thread. Each bit [0..63] is associated with the corresponding processor.
Note
If nMask is 0, the affinity is reset. On Linux this means affinity is set to all available processors (or cores) whereas on Windows the affinity of the thread is being inherited from the parent process.
Returns
Returns the standard result code.
Remarks
Use cSystem::GetProcessorCount to get the total count of available processors.
tResult SetState ( tThreadState  ThreadState,
tBool  bWait = tFalse 
)
protected

Set current state of thread.

See also
tThreadState
Parameters
ThreadStatestate to set
bWaitif tTrue wait for thread to acknowledge state change, else return immediately .
Returns
ERR_NOT_INITIALISED if thread has not been initialised yet.
static tVoid Sleep ( tTimeStamp  tmMicroseconds)
static

The calling thread will sleep for the specified amount of time.

Parameters
tmMicroseconds[in] The time to sleep in microseconds.
Returns
void
tResult Suspend ( tBool  bWait = tFalse)

Sets the thread state to suspended.

Parameters
bWait[in] Whether or not to wait for an acknowledgment.
Return values
ERR_NOERRORif all went well
ERR_NOT_INITIALISEDif thread was not yet initialized, e.g. Create was not called
ERR_NOT_SUPPORTEDif thread is in an state that cannot be suspended
ERR_UNEXPECTEDif thread could not be suspended for any other reason
tResult Terminate ( tBool  bWait = tFalse)

Terminates the thread.

Remarks
if you terminate a thread whose thread function is blocking with bWait equals tFalse and then cause the destructor of the thread of its Release()-function to be called, Release() will hang.
When using a custom thread entry function take special care when calling this method with bWait = tFalse. In this case, the thread will be terminated immediately and has no chance to clean up its resources, especially locks held. On Windows the resulting call to TerminateThread may have severe side-effects! Calling it with bWait = tTrue on a thread with a custom trhead entry function boils down to calling WaitForExit().
Parameters
bWait[in] Whether or not to wait for an acknowledgment.
Return values
ERR_NOERRORif all went well
ERR_NOT_INITIALISEDif thread was not yet initialized, e.g. Create was not called
ERR_NOT_SUPPORTEDif thread is in an state that cannot be suspended
ERR_UNEXPECTEDif thread could not be suspended for any other reason
virtual tResult ThreadExitFunc ( )
protectedvirtual

This will be called after the last call to ThreadLoop.

Returns
RETURN_NOERROR.
virtual tResult ThreadFunc ( )
protectedvirtual

This is the default Thread entrance that will be called.

Returns
if a threadfunc is provided, result of this threadfunc, else ERR_NOERROR.

Reimplemented in cCyclicThread, and cIndexedFileAsyncWriter.

virtual tResult ThreadInitFunc ( )
protectedvirtual

This function will be called before the first call to ThreadLoop.

Returns
RETURN_NOERROR.
virtual tResult ThreadLoop ( )
protectedvirtual

This will will be called repeatedly by the default ThreadFunc while the Thread is in state running.

Returns
ERR_NOERROR.
tResult WaitForExit ( tInt  nTimeout = WAIT_Infinite)

Blocks the calling thread until the thread has exited.

Parameters
nTimeout[in] Maximum time to wait.
Return values
ERR_NOERRORif thread exited within specified timeout
ERR_TIMEOUTif thread did not return within specified timeout
ERR_FAILEDif something went wrong
static tVoid YieldExecution ( )
static

Gives the scheduler a chance to schedule another thread.

Returns
void

Copyright © Audi Electronics Venture GmbH. All rights reserved. (Generated on Fri Mar 22 2019 by doxygen 1.8.10)