Oracle Coherence for C++ API
Release 3.7.1.0
E22845-01

Thread Class Reference

#include <coherence/lang/Thread.hpp>

Inherits Object, and Runnable.

List of all members.

Detailed Description

An Object representing a thread of execution.

Author:: mf 2007.12.10

Public Types

typedef spec::Handle Handle

Thread Handle definition.

typedef spec::View View

Thread View definition.

typedef spec::Holder Holder

Thread Holder definition.

Public Member Functions

virtual void run ()

Invoke the Runnable.

virtual int64_t getId () const

Return the Thread's unique ID.

virtual State getState () const

Return the Thread's current state.

virtual String::View getName () const

Return the Thread's name.

virtual
ThreadGroup::Handle getThreadGroup ()

Return this thread's group, or NULL if the thread has terminated.

virtual ThreadGroup::View getThreadGroup () const

Return this thread's group, or NULL if the thread has terminated.

virtual void start ()

Begin executing the Thread's runnable on a new system thread.

virtual void interrupt ()

Request that the Thread stop executing.

virtual bool isInterrupted () const

Return true iff the thread is interrupted.

virtual void join () const

Wait for the Thread to reach the state_terminated state.

virtual void join (int64_t cMillis) const

Wait for the Thread to reach the state_terminated state.

virtual void setName (String::View vsName)

Set the Thread's name.

virtual void toStream (std::ostream &out) const

Output a human-readable description of this Object to the given stream.

coherence::lang::operator<<(std::ostream, Object::View) is defined and will call into the toStream method, to output Objects. If a managed String object is desired, the COH_TO_STRING macro can be used to build up a String from streamable contents.

 Object::View vKey   = ...
 Object::View vValue = ...
 std::cout << vKey << " = " << vValue << std::endl;

 String::Handle hs = COH_TO_STRING(vKey << " = " << vValue);

Parameters:

out

the stream used to output the description

Static Public Member Functions

static Thread::Handle currentThread ()

Return the Thread on which the caller is executing.

static
ObjectArray::Handle getStackTrace (size32_t cTrim=0)

Return a stack trace for this thread.

static void outputStackTrace (std::ostream &out, ObjectArray::View vaStack=NULL)

Output a stack trace to the supplied stream.

static void dumpStacks (std::ostream &out, int64_t cMillisTimeout=-1)

Output the stack trace of all known threads to the specified stream.

static bool interrupted ()

Return true iff the caller's thread has been interrupted.

static void sleep (int64_t cMillis)

Pause the current thread for the specified duration.

static void yield ()

Temporarily pause the current thread.

Protected Types

enum Maintenance

Defines various thread maintenance tasks.

Protected Member Functions

virtual void onExit ()

Called automatically on the thread prior to termination.

virtual void scheduleMaintenance (Maintenance nMaintenance) const

Instruct the thread to perform maintenance.

Static Protected Member Functions

static void doGlobalMaintenance (Maintenance nMaintenance)

Instruct all threads to perform maintenance.

Protected Attributes

MemberHandle
< ThreadGroup > m_hGroup

The thread's group.

MemberHandle< Runnable > m_hRunnable

The inner runnable associated with this Thread.

MemberView< String > m_vsName

The thread's name.

FinalView< String > m_vsDescription

The thread's description.

size32_t m_cBytesStack

The configured stack size;.

Volatile< int32_t > m_nState

The current thread state.

int m_nMaintenanceMask

Bit mask identifying required maintenance tasks.

Member Function Documentation

virtual int64_t getId ( ) const [virtual]

Return the Thread's unique ID.

No two live thread's will have the same ID and no thread will have an id of 0.

Returns:: the Thread's unique ID.

virtual State getState ( ) const [virtual]

Return the Thread's current state.

Returns:: the Thread's current state

virtual String::View getName ( ) const [virtual]

Return the Thread's name.

Returns:: the Thread's name

virtual ThreadGroup::Handle getThreadGroup ( ) [virtual]

Return this thread's group, or NULL if the thread has terminated.

Returns:: this thread's group

virtual ThreadGroup::View getThreadGroup ( ) const [virtual]

Return this thread's group, or NULL if the thread has terminated.

Returns:: this thread's group

virtual void start ( ) [virtual]

Begin executing the Thread's runnable on a new system thread.

This method may only be called once per Thread instance.

Exceptions:

IllegalStateException

if a called on a Thread which is not in the state state_initial.

virtual bool isInterrupted ( ) const [virtual]

Return true iff the thread is interrupted.

Returns:: true iff the thread is interrupted

virtual void join ( int64_t cMillis ) const [virtual]

Wait for the Thread to reach the state_terminated state.

Parameters:

cMillis

the maximum duration to wait, or zero for infinite

virtual void setName ( String::View vsName ) [virtual]

Set the Thread's name.

Parameters:

vsName

the Thread's name

virtual void onExit ( ) [protected, virtual]

Called automatically on the thread prior to termination.

Any class extending this Thread and overriding this method much call this implementation to ensure that join() operations complete.

static Thread::Handle currentThread ( ) [static]

Return the Thread on which the caller is executing.

Returns:: the caller's thread

static ObjectArray::Handle getStackTrace ( size32_t cTrim = 0 ) [static]

Return a stack trace for this thread.

Parameters:

cTrim

the number of frames to trim from the top of the stack

Returns:: an array of StackTraceElements describing as much of the thread's stack as can be determined

static void outputStackTrace	(	std::ostream &	out,
		ObjectArray::View	vaStack = `NULL`
	)			`[static]`

Output a stack trace to the supplied stream.

Parameters:

	out	the stream to output to
	vaStack	the array of StackTraceElements to output, or NULL for the stack of the current thread

static void dumpStacks	(	std::ostream &	out,
		int64_t	cMillisTimeout = `-1`
	)			`[static]`

Output the stack trace of all known threads to the specified stream.

This is a blocking operation, while the calling thread waits for all known threads to report their stack.

Note: This operation can also be manually triggered by sending a SIGQUIT signal to the process. This can be done via CTRL+/ on UNIX and CTRL+BREAK on Windows.

Parameters:

	out	the stream to output to
	cMillisTimeout	the maximum amount of time to wait for all threads to report their stacks, or -1 for the system default of twice the interrupt resolution

static bool interrupted ( ) [static]

Return true iff the caller's thread has been interrupted.

The thread's interrupt state is reset as part of this operation.

Returns:: true iff the caller's thread has been interrupted

static void sleep ( int64_t cMillis ) [static]

Pause the current thread for the specified duration.

Parameters:

cMillis

the duration to pause the thread for.

Exceptions:

InterruptedException

if the thread is interrupted while sleeping.

virtual void toStream ( std::ostream & out ) const [virtual]

Output a human-readable description of this Object to the given stream.

 Object::View vKey   = ...
 Object::View vValue = ...
 std::cout << vKey << " = " << vValue << std::endl;

 String::Handle hs = COH_TO_STRING(vKey << " = " << vValue);

Parameters:

out

the stream used to output the description

If the associated Runnable implements the coherence::util::Describable interface that content will be included as well.

Reimplemented from Object.

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

coherence/lang/Thread.hpp