A handle to a thread. More...

#include <e32std.h>

Inheritance diagram for RThread:

Public Member Functions
	RThread ()
	Default constructor.

IMPORT_C TInt	Create (const TDesC &aName, TThreadFunction aFunction, TInt aStackSize, TInt aHeapMinSize, TInt aHeapMaxSize, TAny *aPtr, TOwnerType aType=EOwnerProcess)
	Creates a thread belonging to the current process, and opens this handle to that thread.

IMPORT_C TInt	Create (const TDesC &aName, TThreadFunction aFunction, TInt aStackSize, RAllocator aHeap, TAny aPtr, TOwnerType aType=EOwnerProcess)
	Creates a thread belonging to the current process, and opens this handle to that thread.

IMPORT_C TInt	Create (const TThreadCreateInfo &aCreateInfo)
	Creates a thread belonging to the current process, and opens this handle to that thread.

IMPORT_C TInt	Open (const TDesC &aFullName, TOwnerType aType=EOwnerProcess)
	Opens a handle to specifically named thread.

IMPORT_C TInt	Open (TThreadId aID, TOwnerType aType=EOwnerProcess)
	Opens a handle to the thread with a specific thread Id.

IMPORT_C TThreadId	Id () const
	Gets the Id of this thread.

IMPORT_C void	Resume () const
	Makes the thread eligible for execution.

IMPORT_C void	Suspend () const
	Suspends execution of this thread.

IMPORT_C void	Kill (TInt aReason)
	Ends the thread, specifying a reason code.

IMPORT_C void	Terminate (TInt aReason)
	Ends the thread, specifying a reason code.

IMPORT_C void	Panic (const TDesC &aCategory, TInt aReason)
	Panics this thread, specifying the panic category name and reason.

IMPORT_C TInt	Process (RProcess &aProcess) const
	Opens a process-relative handle to the process which owns this thread.

IMPORT_C TThreadPriority	Priority () const
	Gets the priority of this thread.

IMPORT_C void	SetPriority (TThreadPriority aPriority) const
	Sets the priority of the thread to one of the values defined by the TThreadPriority enumeration.

IMPORT_C TProcessPriority	ProcessPriority () const
	Gets the priority of the process which owns this thread.

IMPORT_C void	SetProcessPriority (TProcessPriority aPriority) const
	Sets the priority of the process which owns this thread to one of the values defined by the TProcessPriority enumeration.

IMPORT_C TInt	RequestCount () const
	Gets this thread's request semaphore count.

IMPORT_C TExitType	ExitType () const
	Tests whether the thread has ended and, if it has ended, return how it ended.

IMPORT_C TInt	ExitReason () const
	Gets the specific reason associated with the end of this thread.

IMPORT_C TExitCategoryName	ExitCategory () const
	Gets the name of the category associated with the end of the thread.

IMPORT_C void	RequestComplete (TRequestStatus *&aStatus, TInt aReason) const
	Signals this thread that an asynchronous request originating from this thread, is complete.

IMPORT_C void	RequestSignal () const
	Signal this threads request semaphore.

IMPORT_C void	Logon (TRequestStatus &aStatus) const
	Requests notification when this thread dies, normally or otherwise.

IMPORT_C TInt	LogonCancel (TRequestStatus &aStatus) const
	Cancels an outstanding request for notification of the death of this thread.

IMPORT_C void	HandleCount (TInt &aProcessHandleCount, TInt &aThreadHandleCount) const
	Gets the number of handles open in this thread, and the number of handles open in the process which owns this thread.

IMPORT_C void	Context (TDes8 &aDes) const
	Gets the register contents of this thread.

IMPORT_C TInt	StackInfo (TThreadStackInfo &aInfo) const
	Gets information about a thread's user mode stack.

IMPORT_C TInt	GetCpuTime (TTimeIntervalMicroSeconds &aCpuTime) const
	Gets the CPU usage for this thread.

TInt	Open (const TFindThread &aFind, TOwnerType aType=EOwnerProcess)
	Opens a handle to the thread found by pattern matching a name.

IMPORT_C void	Rendezvous (TRequestStatus &aStatus) const
	Creates a Rendezvous request with the thread.

IMPORT_C TInt	RendezvousCancel (TRequestStatus &aStatus) const
	Cancels a previously requested Rendezvous with the thread.

IMPORT_C TSecureId	SecureId () const

IMPORT_C TVendorId	VendorId () const

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

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

TInt	Create (const TDesC &aName, TThreadFunction aFunction, TInt aStackSize, TAny aPtr, RLibrary aLibrary, RHeap *aHeap, TInt aHeapMinSize, TInt aHeapMaxSize, TOwnerType aType)
	Function only temporarily supported to aid migration to process emulation...

Public Member Functions inherited from RHandleBase
	RHandleBase ()
	Default constructor.

TInt	Handle () const
	Retrieves the handle-number of the object associated with this handle.

void	SetHandle (TInt aHandle)
	Sets the handle-number of this handle to the specified value.

TInt	SetReturnedHandle (TInt aHandleOrError)
	Sets the handle-number of this handle to the specified value.

IMPORT_C void	Close ()
	Closes the handle.

IMPORT_C TName	Name () const
	Gets the name of the handle.

IMPORT_C TFullName	FullName () const
	Gets the full name of the handle.

IMPORT_C void	FullName (TDes &aName) const
	Gets the full name of the handle.

IMPORT_C void	SetHandleNC (TInt aHandle)
	Sets the handle-number of this handle to the specified value, and marks it as not closable.

IMPORT_C TInt	Duplicate (const RThread &aSrc, TOwnerType aType=EOwnerProcess)
	Creates a valid handle to the kernel object for which the specified thread already has a handle.

IMPORT_C void	HandleInfo (THandleInfo *anInfo)
	Gets information about the handle.

IMPORT_C TUint	Attributes () const

IMPORT_C TInt	BTraceId () const
	Returns a unique object identifier for use with BTrace.

IMPORT_C void	NotifyDestruction (TRequestStatus &aStatus)
	Internal technology API.

Static Public Member Functions
static TInt	RenameMe (const TDesC &aName)

static IMPORT_C void	Rendezvous (TInt aReason)
	Completes all Rendezvous' with the current thread.

Static Public Member Functions inherited from RHandleBase
static void	DoExtendedClose ()

Additional Inherited Members
Public Types inherited from RHandleBase
enum	TAttributes { EReadAccess =0x1 , EWriteAccess =0x2 , EDirectReadAccess =0x4 , EDirectWriteAccess =0x8 }
	Read/Write attributes for the handle. More...

Protected Member Functions inherited from RHandleBase
	RHandleBase (TInt aHandle)
	Copy constructor.

IMPORT_C TInt	Open (const TFindHandleBase &aHandle, TOwnerType aType)
	Opens a handle to a kernel side object found using a find-handle object.

TInt	OpenByName (const TDesC &aName, TOwnerType aOwnerType, TInt aObjectType)
	Implementation for RXxxxx::Open/OpenGlocbal(const TDesC &aName,,TOwnerType aType) functions.

Static Protected Member Functions inherited from RHandleBase
static TInt	SetReturnedHandle (TInt aHandleOrError, RHandleBase &aHandle)

Protected Attributes inherited from RHandleBase
TInt	iHandle

Detailed Description

A handle to a thread.

The thread itself is a kernel object.

API status: Published to all clients. Released API.

Definition at line 4090 of file e32std.h.

Constructor & Destructor Documentation

◆ RThread()

RThread::RThread ( )

inline

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.

(generated from Symbian Developer Library)

Member Function Documentation

◆ Context()

IMPORT_C void RThread::Context ( TDes8 & aDes ) const

Gets the register contents of this thread.

Parameters

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

(generated from Symbian Developer Library)

◆ Create() [1/4]

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

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.

If KNullDesC is specified for the name, then an anonymous thread will be created. Anonymous threads are not global, and cannot be opened by other processes.

Parameters

aName	The name to be assigned to this thread. KNullDesC, to create an anonymous thread.
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.
aStackSize	The size of the new thread's stack. This must be at least 512 bytes, otherwise this method will fail with KErrArgument.
aHeap	A pointer to the handle of the heap belonging to another thread which this thread is to use.
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. It must be ensured that the memory pointed to by this pointer is still valid when accessed by the new thread, e.g. if aPtr points to data on the stack.
aType	An enumeration whose enumerators define the ownership of this thread handle. If not explicitly specified, EOwnerProcess is taken as default.

Panic condition: USER 109 if aStackSize is negative.

(generated from Symbian Developer Library)

◆ Create() [2/4]

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

inline

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

Deprecated:: Use process emulation instead

API status: Published to all clients.

Deprecated:

API status: Published to all clients.

Definition at line 4293 of file e32std.h.

◆ Create() [3/4]

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

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.

If KNullDesC is specified for the name, then an anonymous thread will be created. Anonymous threads are not global, and cannot be opened by other processes.

Parameters

aName	The name to be assigned to this thread. KNullDesC, to create an anonymous thread.
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.
aStackSize	The size of the new thread's stack. This must be at least 512 bytes, otherwise this method will fail with KErrArgument.
aHeapMinSize	The minimum size for the new thread's heap.
aHeapMaxSize	The maximum size for the new thread's heap.
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. It must be ensured that the memory pointed to by this pointer is still valid when accessed by the new thread, e.g. if aPtr points to data on the stack.
aType	An enumeration whose enumerators define the ownership of this thread handle. If not explicitly specified, EOwnerProcess is taken as default.

Panic condition: USER 109 if aStackSize is negative.

Panic condition: USER 110 if aHeapMinSize is less than KMinHeapSize.

Panic condition: USER 111 if aHeapMaxSize is less than aHeapMinSize.

(generated from Symbian Developer Library)

◆ Create() [4/4]

IMPORT_C TInt RThread::Create ( const TThreadCreateInfo & aCreateInfo )

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

The thread will have the properties as defined by the parameter aCreateInfo.

Parameters

aCreateInfo A reference to a TThreadCreateInfo object specifying the properties of thread to create.

Panic condition: USER 109 if the stack size specified for the thread is negative.

Panic condition: USER 110 if the specified minimum heap size is less than KMinHeapSize.

Panic condition: USER 111 if the specified maximum heap size is less than the specified minimum heap size.

(generated from Symbian Developer Library)

◆ ExitCategory()

IMPORT_C TExitCategoryName RThread::ExitCategory ( ) const

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.

TBuf

(generated from Symbian Developer Library)

◆ ExitReason()

IMPORT_C TInt RThread::ExitReason ( ) const

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.

(generated from Symbian Developer Library)

◆ ExitType()

IMPORT_C TExitType RThread::ExitType ( ) const

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.

(generated from Symbian Developer Library)

◆ GetCpuTime()

IMPORT_C TInt RThread::GetCpuTime ( TTimeIntervalMicroSeconds & aCpuTime ) const

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

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

(generated from Symbian Developer Library)

◆ HandleCount()

IMPORT_C void RThread::HandleCount	(	TInt &	aProcessHandleCount,
		TInt &	aThreadHandleCount
	)		const

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

Parameters

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

(generated from Symbian Developer Library)

◆ HasCapability() [1/2]

TBool RThread::HasCapability	(	TCapability	aCapability,
		const char *	aDiagnostic = `0`
	)		const

inline

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.

@param aCapability The capability to test.
@param 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 ETrue if the process to which the thread belongs has the capability, EFalse otherwise.

API status: Published to all clients. Released API.

Parameters

aCapability	The capability to test.
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.

(generated from Symbian Developer Library)

◆ HasCapability() [2/2]

TBool RThread::HasCapability	(	TCapability	aCapability1,
		TCapability	aCapability2,
		const char *	aDiagnostic = `0`
	)		const

inline

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.

@param aCapability1 The first capability to test.
@param aCapability2 The second capability to test.
@param 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 ETrue if the process to which the thread belongs has both the capabilities, EFalse otherwise.

API status: Published to all clients. Released API.

Parameters

aCapability1	The first capability to test.
aCapability2	The second capability to test.
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.

(generated from Symbian Developer Library)

◆ Id()

IMPORT_C TThreadId RThread::Id ( ) const

Gets the Id of this thread.

(generated from Symbian Developer Library)

◆ Kill()

IMPORT_C void RThread::Kill ( TInt aReason )

Ends the thread, specifying a reason code.

This function is dangerous and should be used only in cases where the target thread cannot end itself via the normal methods of calling User::Exit() or completing its thread function. A hypothetical example might be where a thread gets 'stuck' in a third-party DLL.

The target thread gets no opportunity to execute any clean-up code, therefore incautious use of this function may lead to memory leaks.

It is functionally identical to RThread::Terminate(), the only difference between the two is a legacy distinction between a 'normal' reason for exiting (use Kill) and an 'abnormal' reason (use Terminate). The choice of function is reflected in the return value of RThread::ExitType().

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

If the thread is process permanent, or the thread is the last thread in the process, then the process is also killed. If the thread is system permanent, the entire system is rebooted.

WARNING: If the target thread uses a shared heap then use of this function will cause an internal array used for thread-local storage (TLS) to be leaked. This leak is specific to ARM platforms which implement the CP15 feature and will not occur on other platforms.

User::Exit() User::SetCritical() User::Critical() RThread::Terminate() RThread::ExitType()

Parameters

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

(generated from Symbian Developer Library)

◆ Logon()

IMPORT_C void RThread::Logon ( TRequestStatus & aStatus ) const

Requests notification when this thread dies, normally or otherwise.

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

when the thread terminates
if the outstanding request is cancelled by a call to RThread::LogonCancel().

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.

RThread::LogonCancel() RThread::ExitReason() RThread::Create()

Parameters

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.

(generated from Symbian Developer Library)

◆ LogonCancel()

IMPORT_C TInt RThread::LogonCancel ( TRequestStatus & aStatus ) const

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

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

(generated from Symbian Developer Library)

◆ Open() [1/3]

IMPORT_C TInt RThread::Open	(	const TDesC &	aFullName,
		TOwnerType	aType = `EOwnerProcess`
	)

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

aFullName	A reference to the descriptor containing the full name of the thread that is already running.
aType	An enumeration whose enumerators define the ownership of this thread handle. If not explicitly specified, EOwnerProcess is taken as default.

(generated from Symbian Developer Library)

◆ Open() [2/3]

TInt RThread::Open	(	const TFindThread &	aFind,
		TOwnerType	aType = `EOwnerProcess`
	)

inline

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

A TFindThread 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

aFind	A reference to the TFindThread object used to find the thread.
aType	An enumeration whose enumerators define the ownership of this thread handle. If not explicitly specified, EOwnerProcess is taken as default.

(generated from Symbian Developer Library)

◆ Open() [3/3]

IMPORT_C TInt RThread::Open	(	TThreadId	aID,
		TOwnerType	aType = `EOwnerProcess`
	)

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

aID	The thread Id used to find the thread.
aType	An enumeration whose enumerators define the ownership of this thread handle. If not explicitly specified, EOwnerProcess is taken as default.

(generated from Symbian Developer Library)

◆ Panic()

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

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

aCategory	A reference to the descriptor containing the text which defines the category name for this panic.
aReason	The panic number.

Panic condition: KERN-EXEC 46 if this target thread's process is not the same as the calling thread's process.

(generated from Symbian Developer Library)

◆ Priority()

IMPORT_C TThreadPriority RThread::Priority ( ) const

Gets the priority of this thread.

(generated from Symbian Developer Library)

◆ Process()

IMPORT_C TInt RThread::Process ( RProcess & aProcess ) const

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

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.

(generated from Symbian Developer Library)

◆ ProcessPriority()

IMPORT_C TProcessPriority RThread::ProcessPriority ( ) const

Gets the priority of the process which owns this thread.

(generated from Symbian Developer Library)

◆ RenameMe()

static TInt RThread::RenameMe ( const TDesC & aName )

inlinestatic

@deprecated Use User::RenameThread() instead

API status: Published to all clients.

◆ Rendezvous() [1/2]

static IMPORT_C void RThread::Rendezvous ( TInt aReason )

static

Completes all Rendezvous' with the current thread.

RThread::Rendezvous(TRequestStatus& aStatus)

Parameters

aReason The reason code used to complete all rendezvous requests

(generated from Symbian Developer Library)

◆ Rendezvous() [2/2]

IMPORT_C void RThread::Rendezvous ( TRequestStatus & aStatus ) const

Creates a Rendezvous request with the thread.

The request is an asynchronous request, and completes:

when the thread next calls RThread::Rendezvous(TInt aReason)
if the outstanding request is cancelled by a call to RThread::RendezvousCancel()
if the thread exits
if the thread panics.

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.

RThread::Rendezvous(TInt aReason) RThread::RendezvousCancel(TRequestStatus& aStatus)

Parameters

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.

(generated from Symbian Developer Library)

◆ RendezvousCancel()

IMPORT_C TInt RThread::RendezvousCancel ( TRequestStatus & aStatus ) const

Cancels a previously requested Rendezvous with the thread.

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

RThread::Rendezvous(TRequestStatus& aStatus)

Parameters

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

(generated from Symbian Developer Library)

◆ RequestComplete()

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

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

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.
aReason	The completion code of this request.

(generated from Symbian Developer Library)

◆ RequestCount()

IMPORT_C TInt RThread::RequestCount ( ) const

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.

(generated from Symbian Developer Library)

◆ RequestSignal()

IMPORT_C void RThread::RequestSignal ( ) const

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 condition: KERN-EXEC 46 if the thread is not in the same process as the callers

(generated from Symbian Developer Library)

◆ Resume()

IMPORT_C void RThread::Resume ( ) const

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().

(generated from Symbian Developer Library)

◆ SecureId()

IMPORT_C TSecureId RThread::SecureId ( ) const

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:

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

this could be used;

@code
RThread & thread;
static _LIT_SECURITY_POLICY_S0(mySidPolicy, KRequiredSecureId);
TBool pass = mySidPolicy().CheckPolicy(thread);
@endcode

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.

@see TSecurityPolicy::CheckPolicy(RThread aThread, const char* aDiagnostic) const
@see _LIT_SECURITY_POLICY_S0

@return The Secure ID.

API status: Published to all clients. Released API.

◆ SetPriority()

IMPORT_C void RThread::SetPriority ( TThreadPriority aPriority ) const

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

aPriority The priority value.

capability: ProtServ if aPriority is EPriorityAbsoluteRealTime1 or higher

Panic condition: KERN-EXEC 14, if aPriority is invalid or set to EPriorityNull

Panic condition: KERN-EXEC 46, if aPriority is EPriorityAbsoluteRealTime1 or higher and calling process does not have ProtServ capability

(generated from Symbian Developer Library)

◆ SetProcessPriority()

IMPORT_C void RThread::SetProcessPriority ( TProcessPriority aPriority ) const

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.

Not allowed on threads in a different process. Replace with RProcess::SetPriority or RMessagePtr2::SetProcessPriority

Parameters

aPriority The priority value.

(generated from Symbian Developer Library)

◆ StackInfo()

IMPORT_C TInt RThread::StackInfo ( TThreadStackInfo & aInfo ) const

Gets information about a thread's user mode stack.

TThreadStackInfo

Parameters

aInfo The TThreadStackInfo object to write the stack infomation to.

(generated from Symbian Developer Library)

◆ Suspend()

IMPORT_C void RThread::Suspend ( ) const

Suspends execution of this thread.

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

(generated from Symbian Developer Library)

◆ Terminate()

IMPORT_C void RThread::Terminate ( TInt aReason )

Ends the thread, specifying a reason code.

This function is dangerous and should be used only in cases where the target thread cannot end itself via the normal methods of calling User::Exit() or completing its thread function. A hypothetical example might be where a thread gets 'stuck' in a third-party DLL.

The target thread gets no opportunity to execute any clean-up code, therefore incautious use of this function may lead to memory leaks.

It is functionally identical to RThread::Kill(), the only difference between the two is a legacy distinction between a 'normal' reason for exiting (use Kill) and an 'abnormal' reason (use Terminate). The choice of function is reflected in the return value of RThread::ExitType().

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

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

WARNING: If the target thread uses a shared heap then use of this function will cause an internal array used for thread-local storage (TLS) to be leaked. This leak is specific to ARM platforms which implement the CP15 feature and will not occur on other platforms.

User::Exit() User::SetCritical() User::Critical() RThread::Kill() RThread::ExitType()

Parameters

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

(generated from Symbian Developer Library)

◆ VendorId()

IMPORT_C TVendorId RThread::VendorId ( ) const

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:

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

this could be used;

@code
RThread & thread;
static _LIT_SECURITY_POLICY_V0(myVidPolicy, KRequiredVendorId);
TBool pass = myVidPolicy().CheckPolicy(thread);
@endcode

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.

@see TSecurityPolicy::CheckPolicy(RThread aThread, const char* aDiagnostic) const
@see _LIT_SECURITY_POLICY_V0

@return The Vendor ID.

API status: Published to all clients. Released API.

The documentation for this class was generated from the following files:

Public Member Functions

Static Public Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ RThread()

Member Function Documentation

◆ Context()

◆ Create() [1/4]

◆ Create() [2/4]

◆ Create() [3/4]

◆ Create() [4/4]

◆ ExitCategory()

◆ ExitReason()

◆ ExitType()

◆ GetCpuTime()

◆ HandleCount()

◆ HasCapability() [1/2]

◆ HasCapability() [2/2]

◆ Id()

◆ Kill()

◆ Logon()

◆ LogonCancel()

◆ Open() [1/3]

◆ Open() [2/3]

◆ Open() [3/3]

◆ Panic()

◆ Priority()

◆ Process()

◆ ProcessPriority()

◆ RenameMe()

◆ Rendezvous() [1/2]

◆ Rendezvous() [2/2]

◆ RendezvousCancel()

◆ RequestComplete()

◆ RequestCount()

◆ RequestSignal()

◆ Resume()

◆ SecureId()

◆ SetPriority()

◆ SetProcessPriority()

◆ StackInfo()

◆ Suspend()

◆ Terminate()

◆ VendorId()