![[Index]](../../../stock/btn_index.gif){kind=small}
![[Glossary]](../../../stock/btn_glossary.gif){kind=small}
![[Previous]](../../../stock/btn_prev.gif){kind=small}
![[Next]](../../../stock/btn_next.gif){kind=small}
| |
|
| |
Location:
e32std.h
Link against: euser.lib
RThread
Supported from 5.0
A handle to a thread.
The thread itself is a Kernel object.
|
Defined in RThread:
Context(), Create(), ExceptionHandler(), ExitCategory(), ExitReason(), ExitType(), GetCpuTime(), GetDesLength(), GetDesMaxLength(), GetRamSizes(), HandleCount(), Heap(), Id(), IsExceptionHandled(), Kill(), Logon(), LogonCancel(), ModifyExceptionMask(), Open(), Panic(), Priority(), Process(), ProcessPriority(), Protected(), RThread(), RaiseException(), ReadL(), Rename(), RequestComplete(), RequestCount(), Resume(), SetExceptionHandler(), SetInitialParameter(), SetPriority(), SetProcessPriority(), SetProtected(), Suspend(), WriteL()
Inherited from RHandleBase:
Close(),
Duplicate(),
Handle(),
SetHandle()
RThread();
Constructs this object.
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, defined in e32std.h. In effect, construction
of RThread creates a default thread handle.
|
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.
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.
Note:
A pointer to data can be passed to the thread function after
the thread has been created by calling the
RThread::SetInitialParameter() function.
The heap for this new thread shares the chunk with the program
stack and has type EChunkStack.
|
|
TInt Create(const TDesC& aName,TThreadFunction aFunction,TInt aStackSize,RHeap* aHeap,TAny* aPtr,TOwnerType aType=EOwnerProcess);
Creates a thread belonging to the current process and to open this handle to that thread.
This thread uses the heap whose handle, an RHeap
object, is pointed to by aHeap. 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.
Note that a pointer to data can be passed to the thread
function after the thread has been created by calling the
RThread::SetInitialParameter() function.
|
|
TInt Create(const RProcess& aProcess,const TDesC& aName,TThreadFunction aFunction,TInt aStackSize,TInt aHeapMinSize,TInt aHeapMaxSize,TAny* aPtr,TOwnerType aType=EOwnerProcess);
Withdrawn in 6.0
Creates a thread belonging to the process identified by a process handle, 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.
Note that a pointer to data can be passed to the thread
function after the thread has been created by calling the
RThread::SetInitialParameter() function.
|
|
TInt Create(const TDesC& aName,TThreadFunction aFunction,TInt aStackSize,TAny* aPtr,RLibrary* aLibrary,RProcess* aProcess,RHeap* aHeap, TInt aHeapMinSize,TInt aHeapMaxSize,TOwnerType aType);
Withdrawn in 6.0
Creates a thread where the thread function belongs to a DLL, and opens this handle to that thread.
This thread belongs to the process identified by the handle
aProcess, if aProcess is not NULL,
otherwise the thread belongs to the current process.
If the handle aHeap is NULL, a new
heap is created for this thread, otherwise this thread uses the heap associated
with that handle.
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.
Note that a pointer to data can be passed to the thread
function after the thread has been created by calling the
RThread::SetInitialParameter() function.
|
|
TInt Create(const TDesC& aName,TThreadFunction aFunction,TInt aStackSize,TAny* aPtr,RLibrary* aLibrary,RHeap* aHeap, TInt aHeapMinSize,TInt aHeapMaxSize,TOwnerType aType);
Supported from 6.0
Creates a thread where the thread function belongs to a DLL, and opens this handle to that thread.
This thread belongs to the current process.
If the handle aHeap is NULL, a new
heap is created for this thread, otherwise this thread uses the heap associated
with that handle.
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.
Note that a pointer to data can be passed to the thread
function after the thread has been created by calling the
RThread::SetInitialParameter() function.
|
|
TInt SetInitialParameter(TAny* aPtr);
Sets the initial parameter for this thread's thread-function.
The thread must currently be in a suspended state, otherwise
SetInitialParameter() returns KErrGeneral.
The pointer to the data to be passed to the thread-function is
normally passed on creation of this thread handle (i.e. the
RThread) using one of the Create() member functions
of RThread.
The SetInitialParameter() function allows the
initial parameter to point to a cell within this thread's own heap. The
thread-function can then call User::Free() on that cell.
|
|
|
TInt 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.
|
|
TInt Open(const TFindThread& aFind,TOwnerType aType=EOwnerProcess);
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.
|
|
TInt 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.
|
|
|
TInt 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.
|
|
|
TInt Rename(const TDesC& aName) const;
Assigns a new name to this thread, replacing any existing name
which may have been set by Create() or by an earlier call to
Rename().
Any attempt to rename a thread which is protected and is
different from the thread invoking this function, causes the rename operation
to fail. A thread can call Rename() on itself whether it is
protected or not.
The new name must be a valid name and it must also be such that the thread's new fullname remains unique amongst threads.
|
|
|
TThreadPriority Priority() const;
Gets the priority of this thread.
|
void 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.
|
![[Top]](../../../stock/arrow_up_2.gif){kind=icon}
EPriorityNull is restricted to Symbian OS, and any attempt to
explicitly set this value causes a KERN-EXEC 14 panic to be
raised.
|
TProcessPriority ProcessPriority() const;
Gets the priority of the process which owns this thread.
|
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.
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.
|
|
void 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().
void Suspend() const;
Suspends execution of this thread. The thread is not scheduled
to run until a subsequent call to Resume() is made.
Suspend() on itself whether it is protected or not.void Kill(TInt aReason);
Ends this thread specifying a reason code.
If the thread is waiting on a semaphore or mutex, the wait is cancelled. If the thread is ready to run, it is removed from the list of threads eligible to run. Any mutexes owned by the thread are freed and any remaining resources are freed or cleaned up.
If this is the main thread of a process, then the process is ended.
|
Kill() on itself whether it is protected or not. User::Exit()void 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.
|
Panic() on itself whether it is protected or not. User::Panic().
|
TExitType ExitType() const;
Has the thread ended and, if it has ended, return how it ended.
This information allows the caller to distinguish between normal termination and a panic.
|
TInt 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.
|
TExitCategoryName 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.
|
|
void Logon(TRequestStatus& aStatus) const;
Requests notification when this thread dies, normally or otherwise.
A request for notification is an asynchronous request.
The request completes when the thread terminates or, if an outstanding notification request is
cancelled by a call to this thread's LogonCancel() member
function.
A request for notification requires memory to be allocated; if
this is unavailable, the call to Logon() returns but the
asynchronous request completes immediately with the value
KErrNoMemory.
Call RThread::ExitType() to find out how the thread died.
|
TInt 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().
|
|
|
TInt 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.
|
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.
|
TThreadId Id() const;
Gets the Id of this thread.
|
TInt GetRamSizes(TInt& aHeapSize,TInt& aStackSize);
Gets the size of the heap and the stack for this thread.
|
|
TInt GetCpuTime(TTimeIntervalMicroSeconds& aCpuTime) const;
Supported from 6.1
Gets the CPU usage for this thread.
|
|
TBool Protected() const;
Tests whether this thread is protected.
The protected state prevents any other thread from setting the priority, suspending, ending or panicking this thread.
|
|
void SetProtected(TBool aState) const;
Sets the thread into a protected state.
The protected state prevents any other thread from setting the priority, suspending, ending or panicking this thread.
|
|
void RequestComplete(TRequestStatus*& aStatus,TInt aReason) const;
Signals to 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.
|
|
TInt GetDesLength(const TAny* aPtr) const;
Gets the length of a specified descriptor within the address space in which the thread represented by this handle runs.
Although aPtr is of type TAny*, it is
assumed to point to a valid descriptor, i.e. a TDesC derived
object. If the object at aPtr is not recognised as a valid
descriptor, then the function returns with
KErrBadDescriptor.
|
|
TInt GetDesMaxLength(const TAny* aPtr) const;
Gets the maximum length of a specified modifiable descriptor within the address space in which the thread represented by this thread handle runs.
Although aPtr is of type TAny*, it is
assumed to point to be a modifiable descriptor, i.e. a TDes
derived object (for example a TPtr or a
TBuf<TInt>). If the object at aPtr is not
recognized as a valid descriptor, then the function returns with
KErrBadDescriptor.
|
|
void ReadL(const TAny* aPtr,TDes8& aDes,TInt anOffset) const;
void ReadL(const TAny* aPtr,TDes16 &aDes,TInt anOffset) const;
Copies data from a specified descriptor — within
the address space in which the thread represented by this RThread
handle runs — to a specified descriptor in the current
thread.
Although the source of this copy operation, aPtr,
is of type TAny*, it is assumed to point to a valid descriptor,
i.e. a TDesC8 or TDesC16 derived object. If the
object at aPtr is not recognised as a valid descriptor, then the
function leaves.
Data is copied from position anOffset within the
source descriptor data area. The length of data copied is the length of the
source descriptor minus the value of anOffset.
If the value of anOffset is greater than the
length of the source descriptor, then no data is copied and the length of
aDes, the target descriptor, is set to zero.
The length of data to be copied cannot be greater than the
maximum length of aDes, the target descriptor. If this is the
case, then the length of data copied is limited to the maximum length of
aDes.
|
|
RThread handle and the current thread can belong to the same or to
different processes.void WriteL(const TAny* aPtr,const TDesC8& aDes,TInt anOffset) const;
void WriteL(const TAny* aPtr,const TDesC16& aDes,TInt anOffset) const;
Copies data to a specified modifiable
descriptor — within the address space in which the thread
represented by this RThread handle runs — from a
specified descriptor in the current thread.
Although the target of this copy operation, aPtr,
is of type TAny*, it is assumed to point to a valid modifiable
type descriptor, i.e. a TDes type. If the object at
aPtr is not recognised as a valid descriptor, then the function
leaves.
Data is copied from the source descriptor, aDes,
to position anOffset within the target descriptor data area. The
length of data copied is the length of the source descriptor,
aDes. The length of the target descriptor is set to the length of
the source descriptor plus the value of anOffset (i.e.
aDes.Length() + anOffset).
The target descriptor data area must be big enough to contain
the data; specifically, the maximum length of the target descriptor must be
sufficient to contain data of length (aDes.Length() plus
anOffset), otherwise the function leaves.
|
|
RThread handle and the current thread can belong to the same or to
different processes.
|
RHeap* Heap();
Gets a pointer to the handle to this thread's heap.
|
|
TExceptionHandler* ExceptionHandler() const;
Gets a pointer to this thread's exception handler.
|
TInt SetExceptionHandler(TExceptionHandler* aHandler,TUint32 aMask);
Sets the thread's current exception handler.
|
|
void ModifyExceptionMask(TUint32 aClearMask, TUint32 aSetMask);
Changes the set of exceptions which this thread's exception handler can deal with.
aClearMask is the set of flags defining the set of
exceptions which the exception handler no longer deals with while
aSetMask is the set of flags defining the new set of exceptions to
be set.
Flag clearing is done before flag setting.
|
TInt RaiseException(TExcType aType);
Raises an exception of a specified type on this thread.
If this thread has an exception handler to handle this type of exception, then it is called.
If this thread has no exception handler to handle this type of exception, then the result depends on whether this thread is the same as the current thread or not:
if this thread is the current thread, i.e. the current thread is raising an exception on itself, then the function raises a KERN-EXEC 3 panic.
if this thread is not the current thread, i.e. the current
thread is raising an exception on another thread, then that other thread ends
with reason code KErrDied.
|
|
TBool IsExceptionHandled(TExcType aType);
Tests whether a specified exception type can be handled by this thread.
If the thread has no exception handler, then this function returns false.
If the thread has an exception handler which cannot handle the
type of exception defined by aType, then the function returns
false.
|
|
|
void Context(TDes8& aDes) const;
Gets the register contents of this (sleeping) thread.
|
Copyright ©2002 Symbian Ltd. 6.1-00174 |
|
![[Top]](../../../stock/arrow_up.gif){kind=icon}