Home

C-Bits Package Documentation

Main Page Namespace List Class Hierarchy Compound List File List Compound Members File Members

cbits::Thread Class Reference

Portable OO thread abstraction. More...

#include <Thread.h>

Inheritance diagram for cbits::Thread:

[legend]Collaboration diagram for cbits::Thread:[legend]List of all members.

Public Types
enum	State { READY = 1, ALIVE = 2, DEAD = 3 }
	Thread states. More...
enum	Priority { PRIORITY_1 = 1, PRIORITY_2 = 2, PRIORITY_3 = 3, PRIORITY_4 = 4, PRIORITY_5 = 5, PRIORITY_6 = 6, PRIORITY_7 = 7, PRIORITY_8 = 8, PRIORITY_9 = 9, MIN_PRIORITY = PRIORITY_1, DEFAULT_PRIORITY = PRIORITY_5, MAX_PRIORITY = PRIORITY_9 }
	Thread scheduling priorities. More...
Public Methods
void	start ()
	Start the thread. More...
const long	getThreadID () const
	Get Thread's ID. More...
void	interrupt ()
	Send a event to the thread. More...
const bool	join (const long msec=0)
	Wait for this thread to terminate. More...
const State	getState (const bool lockit=true) const
	Get this thread's run state. More...
void	setData (void *) const
	Associate user data with this thread. More...
void *	getData () const
	Retrieve user data that has been associated with this thread (if any). More...
virtual	~Thread ()
	Destructor. More...
Static Public Methods
Thread *	create (Runnable *r, const Priority p=DEFAULT_PRIORITY)
	Factory method for creating thread objects. More...
Thread *	getCurrent ()
	Get reference to the current thread of execution. More...
void	yield ()
	Give up the processor. More...
const bool	isInterrupted ()
	Check the interrupt status of the current thread. More...
void	sleep (const long msec)
	Put current thread to sleep. More...
Protected Methods
	Thread (Priority p=DEFAULT_PRIORITY)
	Default constructor. More...
	Thread (Runnable *r, Priority p=DEFAULT_PRIORITY)
	Constructor. More...
Runnable *	getTarget () const
	Get a reference to the user-supplied execution object. More...
const State	setState (State, const bool lockit=true)
	Set the state of the thread. More...
void	setError (const char *e) const
	Set the error string that describes the most recent error. More...
const std::string &	getError () const
	Get the an explanation of the last error that occurred (if any). More...
const Priority	getPriority () const
	Get the thread's scheduling priority. More...
virtual const bool	impl_create_thread (const Priority)=0
	Create a platform-specific thread. More...
virtual const bool	impl_start_thread ()=0
	Start the platform-specific thread. More...
virtual const long	impl_get_threadid () const=0
	Get thread's ID. More...
virtual void	impl_lock_obj () const=0
	Lock this thread object. More...
virtual void	impl_unlock_obj () const=0
	Unlock this thread object. More...
virtual void	impl_interrupt ()=0
	Send an 'interrupt' event to the platform-specific thread implementation. More...
virtual const bool	impl_join (const long msec)=0
	Wait for the platform thread to terminate. More...
virtual void	impl_sleep (const long msec)=0
	Put the current thread to sleep. More...
Private Attributes
std::string	_error
	Description of most recent error. More...
Runnable *	_target
	User-supplied execution object. More...
Priority	_priority
	Thread's Scheduling priority. More...
State	_state
	Current state of the thread. More...
void *	_data
	Pointer to user-supplied opaque data object. More...
bool	_interrupted
	interrupt status of the thread. More...

Detailed Description

Portable OO thread abstraction.

A cbits::Thread object represents an independent thread of execution through user supplied code.

To use cbits::Thread, do the following:

1. Subclass cbits::Runnable and implement cbits::Runnable::run() to carry out the thread's processing.

2. use cbits::Thread::create( Runnable* ) to create a thread instance, passing in the Runnable instance from step (1).

3. Invoke the 'start()' on the Thread instance created in step (2).

The thread should now be performing the actions implemented in the Runnable instance's run() method.

After the thread has started, the Thread::interrupt method should be used to tell the thread to stop. However, the logic encoded in the Runnable instance supplied to the Thread::create in step (2) above must be sensitive to the 'interrupt' status of the thread by periodically checking it using

Thread::getCurrent()->isInterrupted().

The Thread::join method can be used to 'wait' until the thread instance has exited.

For instance, the following code fragment creates a thread object, waits for a few seconds, interrupts the thread, and then waits for the thread to exit (The Runnable implementation is not shown):

	Runnable* r = new ..;
	Thread*   t = Thread::create( r );
	t->start();
	Thread::sleep( 5000 ); // milliseconds
	t->interrupt();
	if( ! t->join( 60000  ); // wait up to 60 seconds
	{
		std::cerr << "Thread is unresponsive." << std::endl;
	}
	// ...

Implementation note:

A platform-specific derived class must be implemented for each platform that this class is ported to. The platform-specific derived class must inherit from this class and implement the protected and pure virtual impl_XXX methods (see below).

This class is influenced by the interface to Java's java.lang.Thread class.

Member Enumeration Documentation

enum cbits::Thread::Priority

Thread scheduling priorities.

Enumeration values:

PRIORITY_1

PRIORITY_2

PRIORITY_3

PRIORITY_4

PRIORITY_5

PRIORITY_6

PRIORITY_7

PRIORITY_8

PRIORITY_9

MIN_PRIORITY

DEFAULT_PRIORITY

MAX_PRIORITY

enum cbits::Thread::State

Thread states.

Enumeration values:

READY

ALIVE Thread is read to execute.

DEAD Thread is executing.

Constructor & Destructor Documentation

Thread::~Thread ( ) [virtual]

Destructor.

Thread::Thread ( Priority p = DEFAULT_PRIORITY ) [protected]

Default constructor.

Parameters:

p Thread scheduling priority

Thread::Thread ( Runnable * r,

Priority p = DEFAULT_PRIORITY

) [protected]

Constructor.

Parameters:

r User-supplied execution object

p Thread scheduling priority

Member Function Documentation

Thread * Thread::create ( Runnable * r,

const Priority p = DEFAULT_PRIORITY

) [static]

Factory method for creating thread objects.

Returns:
pointer to new thread object in the READY state.
Parameters:

p User supplied object to execute Thread priority

Thread * Thread::getCurrent ( ) [static]

Get reference to the current thread of execution.

Returns:
pointer to current thread, or 0 if the current thread was not created as an instance of Thread.

void * Thread::getData ( ) const

Retrieve user data that has been associated with this thread (if any).

Returns:
pointer to opaque user supplied data object.

const std::string& cbits::Thread::getError ( ) const [inline, protected]

Get the an explanation of the last error that occurred (if any).
This method is only available to the implementation-specific derived class.

Returns:
reference to a string that contains a message that describes the last error that occurred. If no errors have occurred, then the string may be empty.

const Priority cbits::Thread::getPriority ( ) const [inline, protected]

Get the thread's scheduling priority.
This method is only available to the implementation-specific derived class.

Returns:
a element of the Priority ennumeration.

const Thread::State Thread::getState ( const bool lockit = true ) const

Get this thread's run state.

Runnable* cbits::Thread::getTarget ( ) const [inline, protected]

Get a reference to the user-supplied execution object.

Returns:
pointer to user-supplied Runnable instance.

const long Thread::getThreadID ( ) const

Get Thread's ID.

Returns:
long integer representing thread's ID.

virtual const bool cbits::Thread::impl_create_thread ( const Priority ) [protected, pure virtual]

Create a platform-specific thread.
This method must be implemented by the platform-specific derived class.

Returns:
true if successful; otherwise false is returned and getError() must return a description of the error that occured.

Implemented in cbits::Thread_PTHREAD.

virtual const long cbits::Thread::impl_get_threadid ( ) const [protected, pure virtual]

Get thread's ID.
This method is called internally to prevent access to the thread object while it is modifying its internal state.

Returns:
long

Implemented in cbits::Thread_PTHREAD.

virtual void cbits::Thread::impl_interrupt ( ) [protected, pure virtual]

Send an 'interrupt' event to the platform-specific thread implementation.
This method must be implemented by the platform-specific derived class.
Implemented in cbits::Thread_PTHREAD.

virtual const bool cbits::Thread::impl_join ( const long msec ) [protected, pure virtual]

Wait for the platform thread to terminate.
This method must be implemented by the platform-specific derived class.

Returns:
true if the platform thread has exited. If an error occurs during the 'join', false is returned and getError() must return a description of the error that occured.

Implemented in cbits::Thread_PTHREAD.

virtual void cbits::Thread::impl_lock_obj ( ) const [protected, pure virtual]

Lock this thread object.
This method is called internally to prevent access to the thread object while it is modifying its internal state.
This method must be implemented by the platform-specific derived class.
Implemented in cbits::Thread_PTHREAD.

virtual void cbits::Thread::impl_sleep ( const long msec ) [protected, pure virtual]

Put the current thread to sleep.
This method must be implemented by the platform-specific derived class.
Implemented in cbits::Thread_PTHREAD.

virtual const bool cbits::Thread::impl_start_thread ( ) [protected, pure virtual]

Start the platform-specific thread.
This method must be implemented by the platform-specific derived class.

Returns:
true if successful; otherwise false is returned and getError() must return a description of the error that occured.

Implemented in cbits::Thread_PTHREAD.

virtual void cbits::Thread::impl_unlock_obj ( ) const [protected, pure virtual]

Unlock this thread object.
This method is called internally to release the lock that may have been set to prevent access to the thread object while it is modifying its internal state.
This method must be implemented by the platform-specific derived class.
Implemented in cbits::Thread_PTHREAD.

void Thread::interrupt ( )

Send a event to the thread.
It is intended that the Runnable code must be written in such a way that it is sensitive to the interrupt status of the thread. It may check the interrupt status by calling the 'isInterrupted' method.

const bool Thread::isInterrupted ( ) [static]

Check the interrupt status of the current thread.
The interrupt state is reset after every call to this method.

Returns:
'true' if another thread has previously called the 'interrupt' method on this thread instance. otherwise, false is returned.

const bool Thread::join ( const long msec = 0 )

Wait for this thread to terminate.
FIXME Thread.h 'msec' argument is ignored by 'join' method.
Parameters:

msec maximum number of milliseconds to wait for the thread to end. 'msec' <= 0 is interpreted as 'wait forever'.

void Thread::setData ( void * ) const

Associate user data with this thread.

Parameters:

d pointer to opaque user-supplied data object

void cbits::Thread::setError ( const char * e ) const [inline, protected]

Set the error string that describes the most recent error.
This method is only available to the implementation-specific derived class.
Parameters:

e An explanation of the last error

const Thread::State Thread::setState ( State ,

const bool lockit = true

) [protected]

Set the state of the thread.
This method is only available to the implementation specific derived class.

Returns:
the old state.
Parameters:

lockit true if object should be locked before changing state.

void Thread::sleep ( const long msec ) [static]

Put current thread to sleep.

Parameters:

msec Number of milliseconds to sleep. The process may wake up before the full interval has elapsed.

void Thread::start ( )

Start the thread.
The Thread object's state changes from READY to ALIVE.
@raises ThreadException if :

the thread is in the DEAD state.
The platform thread cannot be started.

void Thread::yield ( ) [static]

Give up the processor.
If no other threads are eligible to execute, the thread that yielded will be immediately rescheduled.
Reimplemented in cbits::Thread_PTHREAD.

Member Data Documentation

void* cbits::Thread::_data [private]

Pointer to user-supplied opaque data object.

std::string cbits::Thread::_error [private]

Description of most recent error.

bool cbits::Thread::_interrupted [private]

interrupt status of the thread.

Priority cbits::Thread::_priority [private]

Thread's Scheduling priority.

State cbits::Thread::_state [private]

Current state of the thread.

Runnable* cbits::Thread::_target [private]

User-supplied execution object.

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

Generated by

Hosted by

cbits::Thread Class Reference

Public Types

Public Methods

Static Public Methods

Protected Methods

Private Attributes

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation