Main Page   Namespace List   Class Hierarchy   Compound List   Compound Members  

ZThread::Thread Class Reference

#include <Thread.h>

Inheritance diagram for ZThread::Thread::

ZThread::Runnable ZThread::TimerThread ZThread::Worker List of all members.

Public Types

enum  PRIORITY { PRI_NORMAL, PRI_HIGH, PRI_LOW }
 Priorities.


Public Methods

 Thread () throw (Synchronization_Exception)
virtual ~Thread () throw ()
Thread* operator-> ()
bool equals (const Thread &t) const
bool operator== (const Thread &t) const
virtual void kill () throw (Synchronization_Exception)
void join () throw (Synchronization_Exception)
virtual void run () throw ()
void start () throw (Synchronization_Exception)
void run (Runnable *target) throw (Synchronization_Exception)
void interrupt () throw (Synchronization_Exception)
void setPriority (Thread::PRIORITY) throw (Synchronization_Exception)
Thread::PRIORITY getPriority () throw (Synchronization_Exception)
bool isInterrupted () throw ()
virtual bool isKilled () throw ()
bool isDaemon () throw ()
void setDaemon (bool flag) throw (Synchronization_Exception)
void setNotify (bool flag) throw (Synchronization_Exception)
bool wantNotify () throw ()

Static Public Methods

void sleep (unsigned long) throw (Synchronization_Exception)
void yield () throw ()
Thread current () throw (Synchronization_Exception)
const FastThreadLocal<void*>& interruptKey () throw ()

Detailed Description

Author:
Eric Crahen
Version:
1.3.4
Date:
04-22-2001

A special Runnable object that reflects each thread of execution in a flexible way. Thread objects provided an excellent abstraction for mutlithreading. They also provided the underlying mechanics to allow the synchronization objects to be interruptable. This is very important because that is a key factor in this framework

A Thread can run a task in another thread of execution

 class Task : public Runnable { ... }
...
 Task z;
 Thread t;
 t.run(&z);
...

Or it can be extended to have its task built in

 class ThreadEx : public Thread {
 ...
 virtual void run() {
 // do something
 }
 ...
 };

 ThreadEx t; 
 t.start();
Interrupting:

Threads can be interrupted - any synchronization object can examine a threads state while waiting and throw an Interrupted_Exception instead of blocking indefinitely. This is not a permanent state. Once it has been checked, it is reset to not being interrupted so it can continue to perform other tasks


Constructor & Destructor Documentation

Thread ( ) throw (Synchronization_Exception)
 

Create a new thread object that can execute tasks in another thread of execution

Exceptions:
Initialization_Exception   - thrown if there are not enough resources to do this

~Thread ( ) throw () [virtual]
 

Destroy this Thread object


Member Function Documentation

Thread current ( ) throw (Synchronization_Exception) [static]
 

Get a reference to the currently executing thread. You can not use this reference to execute tasks.

Exceptions:
Synchronization_Exception   - thrown if zthreads shutdown before your calling this. Only happens if you use alot of static objects that attempt to invoke zthreads methods after zthreads objects have gone out of scope when the program is terminating.

You can handle this situation by trying to catch an InvalidOp_Exception around any code you suspect may be in this situation and then respond accordingly.

bool equals ( const Thread & t ) const [inline]
 

Compare two threads for equivalence

Parameters:
t  

Thread::PRIORITY getPriority ( ) throw (Synchronization_Exception)
 

Get the priority of this Thread.

void interrupt ( ) throw (Synchronization_Exception)
 

Interrupt a wait this thread may be blocking on. If it is not currently blocked the next time the thread starts an interruptable wait it will throw an exception and reset the state of the thread.

A Thread can interrupt() it self - however, this will only reset its interrupted status. This allows for the creation of more elegant extended Thread classes (like the Timer)

const FastThreadLocal< void *> & interruptKey ( ) throw () [inline, static]
 

Get a reference to a default ThreadLocal key. This key will always contain some information that is specific to a particular platform.

This is used to develop software that wants to react to a Thread::interrupt() invocation.

WIN32 details:

The Win32 system provides a rich set of function that work with event handles. Because there are so many ways to use these handles creatively to handle various situation, the interruptKey() on a Win32 system will contain the value of a HANDLE. This handle can be used with functions like WaitForMutlipleObjects() or WSAEventSelect(), it will be notified with SetEvent() as a thread was interrupted.

POSIX details:

SIG_ALRM will be generated and should interrupt any i/o that is in progress. Most POSIX functions will return EINTR in such a situation. Example:

 char buf[64];
 size_t sz = 64;
 
 do {
 
   ssize_t n = read(fd, buf, sz);

   if(n < 0 && errno == EINTR && Thread::current()->isInterrupted()) {
     // Take some action
     throw SomeKindOfInterruptedException();
   }

 } while(n < 0 && errno == EINTR);

To write some piece of code that can be notified of a Thread::interrupt() if it is performing some action that does not return EINTR another method is provided. The interruptKey() will contain the address of a sigjmp_buf. If the user sets this value to something other than null, the Thread::interrupt() will use a siglongjmp after invoking the signal The threads interrupt() method will also clear this address after it has been used so that double notifications do not occur. Example:

  // Implement for a function that ignores EINTR
  sigjmp_buf timeout_jmp;
  if(sigsetjmp(timeout_jmp, 1) != 0) {
    // Take some action
    throw SomeKindOfInterruptedException();
  }

  // Enable the timeout
  ZThread::Thread::interruptKey().set(&timeout_jmp);

  // Do some lengthy operation.

  // Disable the timeout
  ZThread::Thread::interruptKey().set(NULL);

Returns:
const FastThreadLocal&

bool isDaemon ( ) throw ()
 

Check the state of this thread to determine weather or not it has been marked as a daemon thread.

Returns:
bool - result

bool isInterrupted ( ) throw ()
 

Check the state of the thread. This will always reset the state to not interrupted so the appropriate action should be taken

Returns:
bool - true was interrupted, false was not interrupted

bool isKilled ( ) throw () [virtual]
 

Check the state of the thread.

Returns:
bool - true was killed, false was not killed

Reimplemented in ZThread::Worker.

void join ( ) throw (Synchronization_Exception)
 

Wait for the thread represented by this object to exit. Only one thread can wait on any other thread. A join() is not interruptable

Exceptions:
InvalidOp_Exception   - thrown if you attempt to join the currently executing thread. Or if you have already joined this thread with another

void kill ( ) throw (Synchronization_Exception) [virtual]
 

Killing a thread prevents it from blocking any more and will unblock it immeditaley if it is blocked. Synchronziation objects will throw exceptions if you attempt to use them after a thread has been killed. This lets you respond to a thread being killed and exit as fast as possible as safely as possible.

This method is virtual to allow for more specific behavior in subclasses. The Worker class, for instance, is a simple example of how this feature is used.

Exceptions:
InvalidOp_Exception   - thrown if you attempt to kill a reference thread or previously killed thread

Postcondition:
Killing a thread does not affect how it needs to be join()ed. It simply makes the thread exit more quickly.

Reimplemented in ZThread::Worker.

Thread * operator-> ( ) [inline]
 

Function provided mainly for convenience. Just another way to get a reference to the Thread from a Thread object

Returns:
Thread* for self;

bool operator== ( const Thread & t ) const [inline]
 

Compare two threads for equivalence

Parameters:
t  

void run ( Runnable * target ) throw (Synchronization_Exception)
 

Run a given task. Each thread can execute one task

Exceptions:
InvalidOp_Exception   - thrown if a thread has already been assigned a task - or if you attempt to run tasks with a thread you did not create
Synchronization_Exception   - thrown if there is an error starting the thread
Parameters:
target  

void run ( ) throw () [virtual]
 

This can be implemented by subclasses to create a thread with a built in task.

This should never throw exceptions

Reimplemented from ZThread::Runnable.

Reimplemented in ZThread::TimerThread, and ZThread::Worker.

void setDaemon ( bool flag ) throw (Synchronization_Exception)
 

Change the status of this thread so that is now treated as a daemon thread. A daemon thread should not be joined, it will execute normally and its destructor can safely be invoked without first join()ing it. It will be join()ed by ZThreads when the program exits.

This address some of the static destruction problems that can occur. See the README for details

Two important things happen to daemon threads:

This thread will be joined *before* static destructors execute. This is automatic, the daemon thread should not be joined explicitly

This thread will recieve an interrupt() before it is joined if the setNotify() method is also invoked.

Parameters:
bool   - flag, set to daemon if true, otherwise set back to a normal user thread that can be joined.

Returns:
bool - success of operation
Parameters:
flag  

void setNotify ( bool flag ) throw (Synchronization_Exception)
 

Indicate this thread should recieve a notification, via interrupt(), if this thread is marked as a daemon thread and the system is preparing to exit - but has not yet deconstructed static objects.

The system will wait for daemon threads to exit before this is done. For some types of daemon threads running a lone task, for instance, perodic polling or something similar, it is appropriate for them to be interrupt()ed. In other cases, Executor worker threads for example, the Exectuor is in control of the threads, those threads may not need or want that interrupt() since they are already working with another object to determine when they should exit.

The default is false, a thread must ask to get this notification

Parameters:
bool   - if true, thread should be notified if it is a daemon and the system is waiting to exit

Returns:
bool - success of operation
Parameters:
flag  

void setPriority ( Thread::PRIORITY ) throw (Synchronization_Exception)
 

Change the priority of this Thread.

void sleep ( unsigned long ) throw (Synchronization_Exception) [static]
 

Put the currently executing thread to sleep for a given amount of time. This is an interruptable wait.

Parameters:
unsigned   long - amount of time to wait
Exceptions:
Interrupted_Exception   - thrown if this wait was interrupted
Parameters:
long  

void start ( ) throw (Synchronization_Exception)
 

Runs the built-in task ( the run method) is any. The default built-in task will exit immediately. This should not be used unless the thread has been extended as shown above

Exceptions:
Synchronization_Exception   - thrown if there is an error starting the thread

bool wantNotify ( ) throw ()
 

Check to see if this thread is asking to be notified of the system exiting.

See also:
setNotfiy()
Parameters:
bool   - notify status

void yield ( ) throw () [static]
 

Cause the currently executing thread to yield, allowing the scheduler to assign some execution time to another thread


The documentation for this class was generated from the following file:
Generated at Fri Aug 31 09:08:02 2001 for ZThread by doxygen1.2.8 written by Dimitri van Heesch, © 1997-2001