Home C-Bits Package Documentation Project Page

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

RunnablegetTarget () 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
doxygen
Hosted by
SourceForge