SWG EMU: ZThread::Thread Class Reference

A thread is started simply by constructing a thread object and giving it a task to perform. The thread will continue to run its task, even after the Thread object used to launch the thread has gone out of scope.

 #include "zthread/Thread.h"
 #include <iostream>

 using namespace ZThread;

 class aRunnable : public Runnable {

   void run() {

     Thread::sleep(1000);
     std::cout << "Hello from another thread" << std::endl;

   }

 };

 int main() {

   try {
     
     // Implictly constructs a Task
     Thread t(new aRunnable);

   } catch(Synchronization_Exception& e) { 
     std::cerr << e.what() << std::endl; 
   }

   std::cout << "Hello from the main thread" << std::endl;

   // Output:

   // Hello from the main thread
   // Hello from another thread

   return 0;

 }

Waiting for a task

A user can exercise some simple synchronization by waiting for a thread to complete running its task.

 #include "zthread/Thread.h"
 #include <iostream>

 using namespace ZThread;

 class aRunnable : public Runnable {
 public:

   void run() {

     Thread::sleep(1000);
     std::cout << "Hello from another thread" << std::endl;

   }

 };

 int main() {

   try {
     
     // Implictly constructs a Task
     Thread t(new aRunnable);
     t.wait();

   } catch(Synchronization_Exception& e) { 
     std::cerr << e.what() << std::endl; 
   }

   std::cout << "Hello from the main thread" << std::endl;

   // Output:

   // Hello from another thread
   // Hello from the main thread

   return 0;

 }

Sharing a task

The same task can be shared by more than one thread. A Task is constructed from a Runnable, and that Task object is copied by value and handed off to each thread.

 #include "zthread/Thread.h"
 #include <iostream>

 using namespace ZThread;

 class aRunnable : public Runnable {

   void run() {

     Thread::sleep(1000);
     std::cout << "Hello from another thread" << std::endl;

   }

 };

 int main() {

   try {
     
     // Explictly constructs a Task
     Task task(new aRunnable);

     // Two threads created to run the same Task
     Thread t1(task);
     Thread t2(task);

   } catch(Synchronization_Exception& e) { 
     std::cerr << e.what() << std::endl; 
   }

   std::cout << "Hello from the main thread" << std::endl;

   // Output:

   // Hello from the main thread
   // Hello from another thread
   // Hello from another thread

   return 0;

 }

Constructor & Destructor Documentation

ZThread::Thread::Thread ( )

Create a Thread that represents the current thread. Using the static members of Thread should be preferred over using this constructor

ZThread::Thread::Thread	(	const Task &	,
		bool	autoCancel = `false`
	)

Create a Thread that spawns a new thread to run the given task.

Parameters:

	task	Task to be run by a thread managed by this executor
	autoCancel	flag to requestion automatic cancellation

Postcondition:: if the autoCancel flag was true, this thread will automatically be canceled when main() goes out of scope.

Member Function Documentation

void ZThread::Thread::cancel ( ) [virtual]

Interrupt and cancel this thread in a single operation. The thread will return true whenever its cancelation status is tested in the future.

Exceptions:

InvalidOp_Exception

thrown if a thread attempts to cancel itself

See also:: Thread::interrupt()
Cancelable::cancel()

Implements ZThread::Cancelable.

bool ZThread::Thread::canceled ( ) [static]

Tests whether the current Thread has been canceled, and clears the interrupted status.

Returns:: bool true only if the Thread::cancel() has been invoked.

Priority ZThread::Thread::getPriority ( )

Get the priority of this Thread.

Returns:: Priority

bool ZThread::Thread::interrupt ( )

Interrupts this thread, setting the interrupted status of the thread. This status is cleared by one of three methods.

If this thread is blocked when this method is called, the thread will abort that blocking operation with an Interrupted_Exception.

The first is by attempting an operation on a synchronization object that would normally block the calling thread; Instead of blocking the calling the calling thread, the function that would normally block will thrown an Interrupted_Exception and clear the interrupted status of the thread.

The second is by calling Thread::interrupted().

The third is by calling Thread::canceled().

Threads already blocked by an operation on a synchronization object will abort that operation with an Interrupted_Exception, clearing the threads interrupted status as in the first case described above.

Interrupting a thread that is no longer running will have no effect.

Returns:

true if the thread was interrupted while not blocked by a wait on a synchronization object.
false othewise.

bool ZThread::Thread::interrupted ( ) [static]

Tests whether the current Thread has been interrupt()ed, clearing its interruption status.

Returns:

true if the Thread was interrupted.
false otherwise.

Postcondition:: The interrupted status of the current thread will be cleared, allowing it to perform a blocking operation on a synchronization object without throwing an exception.

bool ZThread::Thread::isCanceled ( ) [virtual]

Tests whether this thread has been canceled. If called from the context of this thread, the interrupted status is cleared.

Returns:

true if the Thread was canceled.
false otherwise.

See also:: Cancelable::isCanceled()

Implements ZThread::Cancelable.

void ZThread::Thread::setPriority ( Priority p )

Change the priority of this Thread. This will change the actual priority of the thread when the OS supports it.

If there is no real priority support, it's simulated.

Parameters:

- new Priority

void ZThread::Thread::sleep ( unsigned long timeout ) [static]

Put the currently executing thread to sleep for a given amount of time.

Parameters:

timeout

maximum amount of time (milliseconds) this method could block

Exceptions:

Interrupted_Exception

thrown if the threads sleep is interrupted before timeout milliseconds expire.

bool ZThread::Thread::wait ( unsigned long timeout ) [virtual]

Wait for the thread represented by this object to complete its task. The calling thread is blocked until the thread represented by this object exits, or until the timeout expires.

Parameters:

timeout

maximum amount of time (milliseconds) this method could block the calling thread.

Returns:

true if the thread task complete before timeout milliseconds elapse.
false othewise.

Exceptions:

	Deadlock_Exception	thrown if thread attempts to join itself
	InvalidOp_Exception	thrown if the thread cannot be joined
	Interrupted_Exception	thrown if the joining thread has been interrupt()ed

Implements ZThread::Waitable.

void ZThread::Thread::wait ( ) [virtual]

Wait for the thread represented by this object to complete its task. The calling thread is blocked until the thread represented by this object exits.

Exceptions:

	Deadlock_Exception	thrown if thread attempts to join itself
	InvalidOp_Exception	thrown if the thread cannot be joined
	Interrupted_Exception	thrown if the joining thread has been interrupt()ed

Implements ZThread::Waitable.

void ZThread::Thread::yield ( ) [static]

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


Public Member Functions
	Thread ()
	Thread (const Task &, bool autoCancel=false)
	~Thread ()
	Destroy the Thread.
bool	operator== (const Thread &t) const
	Comparison operator.
bool	operator!= (const Thread &t) const
	Comparison operator.
void	wait ()
bool	wait (unsigned long timeout)
void	setPriority (Priority p)
Priority	getPriority ()
bool	interrupt ()
virtual bool	isCanceled ()
virtual void	cancel ()
Static Public Member Functions
static bool	interrupted ()
static bool	canceled ()
static void	sleep (unsigned long timeout)
static void	yield ()

ZThread::Thread Class Reference

Public Member Functions

Static Public Member Functions

Detailed Description

Examples

Launching a task

Waiting for a task

Sharing a task

Constructor & Destructor Documentation

Member Function Documentation