If you can read this text, it means you are not experiencing this website at its best. This website is designed for used with a standards-compliant browser.
Current version: 2.3.1
ZThreads
A platform-independent, multi-threading and synchronization library for C++
Home Documentation Downloads CVS Contact

# Thread Class Reference

`#include <Thread.h>`

Inheritance diagram for Thread:

List of all members.

## 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
bool | interrupted ()
bool | canceled ()
void | sleep (unsigned long timeout)
void | yield ()

## Detailed Description

Author:
  Eric Crahen <http://www.code-foo.com>

Date:
  <2003-07-27T11:17:59-0400>

Version:
  2.3.0

See also:
  Task

  Executor

## Examples

- Launching a task
- Waiting for a task
- Sharing a task

## Launching a task

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

Thread | ( |  | ) |

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

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

virtual void 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 Cancelable.

bool 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 getPriority | ( |  | ) |

| Get the priority of this Thread. Returns: Priority

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

virtual bool 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 Cancelable.

void 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:
  p | - new Priority

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

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

void yield | ( |  | ) | `[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:

- Thread.h