Symbian
Symbian OS Library

SYMBIAN OS V9.3

[Index] [Spacer] [Previous] [Next]



Location: e32std.h
Link against: euser.lib

Class RThread

class RThread : public RHandleBase;

Description

A handle to a thread.

The thread itself is a kernel object.

Derivation

Members

Defined in RThread:
Context(), Create(), Create(), Create(), ExitCategory(), ExitReason(), ExitType(), GetCpuTime(), HandleCount(), HasCapability(), HasCapability(), Id(), Kill(), Logon(), LogonCancel(), Open(), Open(), Open(), Panic(), Priority(), Process(), ProcessPriority(), RThread(), RenameMe(), Rendezvous(), Rendezvous(), RendezvousCancel(), RequestComplete(), RequestCount(), RequestSignal(), Resume(), SecureId(), SetPriority(), SetProcessPriority(), StackInfo(), Suspend(), Terminate(), VendorId()

Inherited from RHandleBase:
Attributes(), Close(), Duplicate(), FullName(), Handle(), HandleInfo(), Name(), SetHandle(), SetHandleNC(), SetReturnedHandle(), iHandle


Construction and destruction


RThread()

inline RThread();

Description

Default constructor.

The constructor exists to initialise private data within this handle; it does not create the thread object.

Specifically, it sets the handle-number to the value KCurrentThreadHandle. In effect, the constructor creates a default thread handle.

[Top]


Member functions


Create()

IMPORT_C TInt Create(const TDesC &aName, TThreadFunction aFunction, TInt aStackSize, TInt aHeapMinSize, TInt aHeapMaxSize, TAny *aPtr, TOwnerType aType=EOwnerProcess);

Description

Creates a thread belonging to the current process, and opens this handle to that thread.

A new heap is created for this thread.

By default, ownership of this thread handle is vested in the current process, but can be vested in the current thread by passing EOwnerThread as the second parameter to this function.

Parameters

const TDesC &aName

The name to be assigned to this thread.

TThreadFunction aFunction

A pointer to a function.. Control passes to this function when the thread is first resumed, i.e. when the thread is initially scheduled to run.

TInt aStackSize

The size of the new thread's stack.

TInt aHeapMinSize

The minimum size for the new thread's heap.

TInt aHeapMaxSize

The maximum size for the new thread's heap.

TAny *aPtr

A pointer to data to be passed as a parameter to the thread function when the thread is initially scheduled to run. If the thread function does not need any data then this pointer can be NULL.

TOwnerType aType

An enumeration whose enumerators define the ownership of this thread handle. If not explicitly specified, EOwnerProcess is taken as default.

Return value

TInt

KErrNone if successful, otherwise one of the other system-wide error codes. KErrAlreadyExists will be returned if there is another thread in this process with the specified name.

Panic codes

USER

109 if aStackSize is negative.

USER

110 if aHeapMinSize is less than KMinHeapSize.

USER

111 if aHeapMaxSize is less than aHeapMinSize.


Create()

IMPORT_C TInt Create(const TDesC &aName, TThreadFunction aFunction, TInt aStackSize, RAllocator *aHeap, TAny *aPtr, TOwnerType aType=EOwnerProcess);

Description

Creates a thread belonging to the current process, and opens this handle to that thread.

This thread uses the heap whose handle is pointed to by aAllocator. If this is NULL, then the thread uses the heap of the creating thread.

By default, ownership of this thread handle is vested in the current process, but can be vested in the current thread by passing EOwnerThread as the second parameter to this function.

Parameters

const TDesC &aName

The name to be assigned to this thread.

TThreadFunction aFunction

A pointer to a function. Control passes to this function when the thread is first resumed, i.e. when the thread is initially scheduled to run.

TInt aStackSize

The size of the new thread's stack.

RAllocator *aHeap

A pointer to the handle of the heap belonging to another thread which this thread is to use.

TAny *aPtr

A pointer to data to be passed as a parameter to the thread function when the thread is initially scheduled to run. If the thread function does not need any data, then this pointer can be NULL.

TOwnerType aType

An enumeration whose enumerators define the ownership of this thread handle. If not explicitly specified, EOwnerProcess is taken as default.

Return value

TInt

KErrNone if successful otherwise one of the other system-wide error codes. KErrAlreadyExists will be returned if there is another thread in this process with the specified name.

Panic codes

USER

109 if aStackSize is negative.


Open()

IMPORT_C TInt Open(const TDesC &aFullName, TOwnerType aType=EOwnerProcess);

Description

Opens a handle to specifically named thread.

By default, ownership of this thread handle is vested in the current process, but can be vested in the current thread by passing EOwnerThread as the second parameter to this function.

Parameters

const TDesC &aFullName

A reference to the descriptor containing the full name of the thread that is already running.

TOwnerType aType

An enumeration whose enumerators define the ownership of this thread handle. If not explicitly specified, EOwnerProcess is taken as default.

Return value

TInt

KErrNone, if successful, otherwise one of the other system-wide error codes.


Open()

IMPORT_C TInt Open(TThreadId aID, TOwnerType aType=EOwnerProcess);

Description

Opens a handle to the thread with a specific thread Id.

By default, ownership of this thread handle is vested in the current process, but can be vested in the current thread by passing EOwnerThread as the second parameter to this function.

Parameters

TThreadId aID

The thread Id used to find the thread.

TOwnerType aType

An enumeration whose enumerators define the ownership of this thread handle. If not explicitly specified, EOwnerProcess is taken as default.

Return value

TInt

KErrNone, if successful, otherwise one of the other system-wide error codes.


Id()

IMPORT_C TThreadId Id() const;

Description

Gets the Id of this thread.

Return value

TThreadId

The Id of this thread.


Resume()

IMPORT_C void Resume() const;

Description

Makes the thread eligible for execution.

After a thread is created, it is put into a suspended state; the thread is not eligible to run until Resume() is called.

This function must also be called to resume execution of this thread after it has been explicitly suspended by a call to Suspend().

Note that when a thread is created, it is given the priority EPriorityNormal by default. The fact that a thread is initially put into a suspended state means that the thread priority can be changed by calling the thread's SetPriority() member function before the thread is started by a call to Resume().


Suspend()

IMPORT_C void Suspend() const;

Description

Suspends execution of this thread.

The thread is not scheduled to run until a subsequent call to Resume() is made.


RenameMe()

static inline TInt RenameMe(const TDesC &aName);

Description

Parameters

const TDesC &aName

Return value

TInt


Kill()

IMPORT_C void Kill(TInt aReason);

Description

Ends this thread, specifying a reason code.

The owning process must be the current process otherwise a panic is raised.

This method is intended to be used if a thread is exiting under normal conditions.

If the thread is process permanent, the process is also killed. If the thread is system permanent, the entire system is rebooted.

Parameters

TInt aReason

The reason to be associated with the ending of this thread.

See also:


Terminate()

IMPORT_C void Terminate(TInt aReason);

Description

Ends this thread, specifying a reason code.

The owning process must be the current process otherwise a panic is raised.

This method is intended to be used if a thread is exiting under abnormal conditions, for example if an error condition has been detected.

If the thread is process critical or process permanent, the process is also terminated. If the thread is system critical or system permanent, the entire system is rebooted.

Parameters

TInt aReason

The reason to be associated with the ending of this thread.

See also:


Panic()

IMPORT_C void Panic(const TDesC &aCategory, TInt aReason);

Description

Panics this thread, specifying the panic category name and reason.

The length of the category name should be no greater than 16; any name with a length greater than 16 is truncated to 16.

The calling thread, i.e. the thread in which this function is called, must be in the same process as this target thread, otherwise the calling thread is itself panicked.

If the thread is process critical or process permanent, the process also panics. If the thread is system critical or system permanent, the entire system is rebooted.

Parameters

const TDesC &aCategory

A reference to the descriptor containing the text which defines the category name for this panic.

TInt aReason

The panic number.

Panic codes

KERN-EXEC

46 if this target thread's process is not the same as the calling thread's process.

See also:


Process()

IMPORT_C TInt Process(RProcess &aProcess) const;

Description

Opens a process-relative handle to the process which owns this thread.

The caller must construct a default RProcess object and pass this to the function. On return, aProcess is the open process-relative handle to the process owning this thread.

The return value indicates the success or failure of this function.

Parameters

RProcess &aProcess

A reference to a default RProcess handle; on successful return from this function, this is the process-relative handle to the process which owns this thread.

Return value

TInt

KErrNone, if successful, otherwise one of the other system-wide error codes.


Priority()

IMPORT_C TThreadPriority Priority() const;

Description

Gets the priority of this thread.

Return value

TThreadPriority

The priority.


SetPriority()

Capability: ProtServ if aPriority is EPriorityAbsoluteRealTime1 or higher

IMPORT_C void SetPriority(TThreadPriority aPriority) const;

Description

Sets the priority of the thread to one of the values defined by the TThreadPriority enumeration.

The resulting absolute priority of the thread depends on the value of aPriority and the priority of the owning process.

Use of the priority value EPriorityNull is restricted to Symbian OS, and any attempt to explicitly set this value causes a KERN-EXEC 14 panic to be raised.

Parameters

TThreadPriority aPriority

The priority value.

Panic codes

KERN-EXEC

14, if aPriority is invalid or set to EPriorityNull

KERN-EXEC

46, if aPriority is EPriorityAbsoluteRealTime1 or higher and calling process does not have ProtServ capability


ProcessPriority()

IMPORT_C TProcessPriority ProcessPriority() const;

Description

Gets the priority of the process which owns this thread.

Return value

TProcessPriority

The process priority.


SetProcessPriority()

IMPORT_C void SetProcessPriority(TProcessPriority aPriority) const;

Description

Sets the priority of the process which owns this thread to one of the values defined by the TProcessPriority enumeration.

The priority can be set to one of the four values:

EPriorityLow

EPriorityBackground

EPriorityForeground

EPriorityHigh

The absolute priority of all threads owned by the process (and all threads owned by those threads etc.) are re-calculated.

Note:

The use of the priority values EPriorityWindowServer, EPriorityFileServer, EPriorityRealTimeServer and EPrioritySupervisor is restricted to Symbian OS, and any attempt to explicitly set any of these priority values raises a KERN-EXEC 14 panic.

Parameters

TProcessPriority aPriority

The priority value.


RequestCount()

IMPORT_C TInt RequestCount() const;

Description

Gets this thread's request semaphore count.

The request semaphore is created when a thread is created, and is used to support asynchronous requests.

A negative value implies that this thread is waiting for at least one asynchronous request to complete.

Return value

TInt

This thread's request semaphore count.


ExitType()

IMPORT_C TExitType ExitType() const;

Description

Tests whether the thread has ended and, if it has ended, return how it ended.

This information allows the caller to distinguish between normal termination and a panic.

Return value

TExitType

An enumeration whose enumerators describe how the thread has ended.


ExitReason()

IMPORT_C TInt ExitReason() const;

Description

Gets the specific reason associated with the end of this thread.

The reason number together with the category name is a way of distinguishing between different causes of thread termination.

If the thread has panicked, this value is the panic number. If the thread has ended as a result of a call to Kill(), then the value is the one supplied by Kill().

If the thread is still alive, then the returned value is zero.

Return value

TInt

The reason associated with the end of the thread.


ExitCategory()

IMPORT_C TExitCategoryName ExitCategory() const;

Description

Gets the name of the category associated with the end of the thread.

The category name together with the reason number is a way of distinguishing between different causes of thread termination.

If the thread has panicked, the category name is the panic category name; for example, E32USER-CBase or KERN-EXEC. If the thread has ended as a result of call to Kill(), then the category name is Kill.

If the thread has not ended, then the category name is empty, i.e. the length of the category name is zero.

Return value

TExitCategoryName

A TBuf descriptor with a defined maximum length containing the name of the category associated with the end of the thread.

See also:


RequestComplete()

IMPORT_C void RequestComplete(TRequestStatus *&aStatus, TInt aReason) const;

Description

Signals this thread that an asynchronous request originating from this thread, is complete.

The request is associated with the specified request status object supplied by this thread.

Typically, the caller of this function is the service provider responsible for satisfying the request made by this thread.

The request is completed with the completion code passed in aReason. This value is copied into this thread's request status, *aStatus, before signalling this thread's request semaphore.

The meaning of the completion code is a matter of convention to be decided between the service provider and this thread.

In a client-server situation, completion of a request takes place in the context of the server thread, but the pointer is interpreted in the address space of the client.

It is often the case in client-server situations that the client and the server are in the same address space (i.e. the same process).

Setting the pointer to the request status to NULL is a convenience, not all servers need it.

Parameters

TRequestStatus *&aStatus

A reference to a pointer to the request status originally supplied by this thread. This is a pointer into this thread's address space, which may be different to the thread currently executing (this code). On return, the pointer to the request status is set to NULL.

TInt aReason

The completion code of this request.


RequestSignal()

IMPORT_C void RequestSignal() const;

Description

Signal this threads request semaphore.

This is similar to RThread::RequestComplete() except that no TRequestStatus object is modified.

May only be used to signal a thread in the same process as the callers.

Panic codes

KERN-EXEC

46 if the thread is not in the same process as the callers


Logon()

IMPORT_C void Logon(TRequestStatus &aStatus) const;

Description

Requests notification when this thread dies, normally or otherwise.

A request for notification is an asynchronous request, and completes:

A request for notification requires memory to be allocated; if this is unavailable, then the call to Logon() returns, and the asynchronous request completes immediately.

Note that even when a thread has died, it is not possible to create a new thread with the same name until all handles on the dead thread have been closed. If this is attempted, the call to RThread::Create will fail with KErrAlreadyExists.

Parameters

TRequestStatus &aStatus

A reference to the request status object. This contains the reason code describing the reason for the termination of the thread, i.e. the value returned by a call to RThread::ExitReason(). Alternatively, this is set to: KErrCancel, if an outstanding request is cancelled; KErrNoMemory, if there is insufficient memory to deal with the request.

See also:


LogonCancel()

IMPORT_C TInt LogonCancel(TRequestStatus &aStatus) const;

Description

Cancels an outstanding request for notification of the death of this thread.

A request for notification must previously have been made, otherwise the function returns KErrGeneral.

The caller passes a reference to the same request status object as was passed in the original call to Logon().

Parameters

TRequestStatus &aStatus

A reference to the same request status object used in the original call to Logon().

Return value

TInt

KErrGeneral, if there is no outstanding request, KErrNone otherwise.


HandleCount()

IMPORT_C void HandleCount(TInt &aProcessHandleCount, TInt &aThreadHandleCount) const;

Description

Gets the number of handles open in this thread, and the number of handles open in the process which owns this thread.

Parameters

TInt &aProcessHandleCount

On return, contains the number of handles open in the process which owns this thread.

TInt &aThreadHandleCount

On return, contains the number of handles open in this thread.


Context()

IMPORT_C void Context(TDes8 &aDes) const;

Description

Gets the register contents of this thread.

Parameters

TDes8 &aDes

On return, contains the register contents, starting with R0.


StackInfo()

IMPORT_C TInt StackInfo(TThreadStackInfo &aInfo) const;

Description

Gets information about a thread's user mode stack.

Parameters

TThreadStackInfo &aInfo

The TThreadStackInfo object to write the stack infomation to.

Return value

TInt

KErrNone, if sucessful; KErrGeneral, if the thread doesn't have a user mode stack, or it has terminated.

See also:


GetCpuTime()

IMPORT_C TInt GetCpuTime(TTimeIntervalMicroSeconds &aCpuTime) const;

Description

Gets the CPU usage for this thread.

This function is not supported on version 8.0b or 8.1b, and returns KErrNotSupported. From 9.1 onwards it may be supported if the kernel has been compiled with the MONITOR_THREAD_CPU_TIME macro defined.

KErrNotSupported - if this feature is not supported on this version or build of the OS.

Parameters

TTimeIntervalMicroSeconds &aCpuTime

A reference to a time interval object supplied by the caller.

Return value

TInt

KErrNone - if thread CPU time is available.


Open()

inline TInt Open(const TFindThread &aFind, TOwnerType aType=EOwnerProcess);

Description

Opens a handle to the thread found by pattern matching a name.

ATFindThread object is used to find all threads whose full names match a specified pattern.

By default, ownership of this thread handle is vested in the current process, but can be vested in the current thread by passing EOwnerThread as the second parameter to this function.

Parameters

const TFindThread &aFind

A reference to the TFindThread object used to find the thread.

TOwnerType aType

An enumeration whose enumerators define the ownership of this thread handle. If not explicitly specified, EOwnerProcess is taken as default.

Return value

TInt

KErrNone if successful, otherwise one of the other system-wide error codes.


Rendezvous()

IMPORT_C void Rendezvous(TRequestStatus &aStatus) const;

Description

Creates a Rendezvous request with the thread.

The request is an asynchronous request, and completes:

Note that a request requires memory to be allocated; if this is unavailable, then this call to Rendezvous() returns, and the asynchronous request completes immediately.

Parameters

TRequestStatus &aStatus

A reference to the request status object. The Rendezvous completes normally when RThread::Rendezvous(TInt aReason) is called, and this request status object will contain this reason code. If the thread exits or panics, then this is the thread exit reason value, i.e. the same value returned by RThread::ExitReason(). Alternatively, this is set to: KErrCancel, if an outstanding request is cancelled; KErrNoMemory, if there is insufficient memory to deal with the request.


RendezvousCancel()

IMPORT_C TInt RendezvousCancel(TRequestStatus &aStatus) const;

Description

Cancels a previously requested Rendezvous with the thread

The request completes with the value KErrCancel (if it was still outstanding).

Parameters

TRequestStatus &aStatus

A reference to the same request status object used in the original call to Rendezvous(TRequestStatus& aStatus).

Return value

TInt

KErrGeneral, if there is no outstanding request, KErrNone otherwise.


Rendezvous()

static IMPORT_C void Rendezvous(TInt aReason);

Description

Completes all Rendezvous' with the current thread.

Parameters

TInt aReason

The reason code used to complete all rendezvous requests


SecureId()

IMPORT_C TSecureId SecureId() const;

Description

Return the Secure ID of the process to which the thread belongs.

If an intended use of this method is to check that the Secure ID is a given value, then the use of a TSecurityPolicy object should be considered. E.g. Instead of something like:

        RThread& thread;
        TInt error = thread.SecureId()==KRequiredSecureId ? KErrNone : KErrPermissionDenied;

this could be used;

        RThread& thread;
        static _LIT_SECURITY_POLICY_S0(mySidPolicy, KRequiredSecureId);
        TInt error = mySidPolicy().CheckPolicy(thread);

This has the benefit that the TSecurityPolicy::CheckPolicy methods are configured by the system wide Platform Security configuration. I.e. are capable of emitting diagnostic messages when a check fails and/or the check can be forced to always pass.

Return value

TSecureId

The Secure ID.


VendorId()

IMPORT_C TVendorId VendorId() const;

Description

Return the Vendor ID of the process to which the thread belongs.

If an intended use of this method is to check that the Vendor ID is a given value, then the use of a TSecurityPolicy object should be considered. E.g. Instead of something like:

        RThread& thread;
        TInt error = thread.VendorId()==KRequiredVendorId ? KErrNone : KErrPermissionDenied;

this could be used;

        RThread& thread;
        static _LIT_SECURITY_POLICY_V0(myVidPolicy, KRequiredVendorId);
        TInt error = myVidPolicy().CheckPolicy(thread);

This has the benefit that the TSecurityPolicy::CheckPolicy methods are configured by the system wide Platform Security configuration. I.e. are capable of emitting diagnostic messages when a check fails and/or the check can be forced to always pass.

Return value

TVendorId

The Vendor ID.


HasCapability()

inline TBool HasCapability(TCapability aCapability, const char *aDiagnostic=0) const;

Description

Check if the process to which the thread belongs has a given capability

When a check fails the action taken is determined by the system wide Platform Security configuration. If PlatSecDiagnostics is ON, then a diagnostic message is emitted. If PlatSecEnforcement is OFF, then this function will return ETrue even though the check failed.

Parameters

TCapability aCapability

The capability to test.

const char *aDiagnostic

A string that will be emitted along with any diagnostic message that may be issued if the test finds the capability is not present. This string must be enclosed in the __PLATSEC_DIAGNOSTIC_STRING macro which enables it to be easily removed from the system.

Return value

TBool

ETrue if the process to which the thread belongs has the capability, EFalse otherwise.


HasCapability()

inline TBool HasCapability(TCapability aCapability1, TCapability aCapability2, const char *aDiagnostic=0) const;

Description

Check if the process to which the thread belongs has both of the given capabilities

When a check fails the action taken is determined by the system wide Platform Security configuration. If PlatSecDiagnostics is ON, then a diagnostic message is emitted. If PlatSecEnforcement is OFF, then this function will return ETrue even though the check failed.

Parameters

TCapability aCapability1

The first capability to test.

TCapability aCapability2

The second capability to test.

const char *aDiagnostic

A string that will be emitted along with any diagnostic message that may be issued if the test finds a capability is not present. This string must be enclosed in the __PLATSEC_DIAGNOSTIC_STRING macro which enables it to be easily removed from the system.

Return value

TBool

ETrue if the process to which the thread belongs has both the capabilities, EFalse otherwise.


Create()

inline TInt Create(const TDesC &aName, TThreadFunction aFunction, TInt aStackSize, TAny *aPtr, RLibrary *aLibrary, RHeap *aHeap, TInt aHeapMinSize, TInt aHeapMaxSize, TOwnerType aType);

Description

Function only temporarily supported to aid migration to process emulation...

Parameters

const TDesC &aName

TThreadFunction aFunction

TInt aStackSize

TAny *aPtr

RLibrary *aLibrary

RHeap *aHeap

TInt aHeapMinSize

TInt aHeapMaxSize

TOwnerType aType

Return value

TInt