Archon::Utilities::Thread Struct Reference

A thread of execution (aka light weight proccess or LWP) represented as an object. More...

#include <archon/util/thread.H>

Inheritance diagram for Archon::Utilities::Thread:

[legend]Collaboration diagram for Archon::Utilities::Thread:

[legend]List of all members.

Public Member Functions
void	wait () throw (NotStartedException, UnexpectedException)
	Wait for this thread to stop.
void	terminate ()
	Issue a termination request for this thread.
Static Public Member Functions
template<typename T>
static Ref< Thread >	run (Ref< T >, void(T::*)(), bool start=true)
	Let a new thread invoke a method of your choise on a reference counted object of your choise.
template<typename T, typename U>
static Ref< Thread >	run (Ref< T >, void(T::*)(U), U, bool start=true)
	Like Thread::run(Ref<T>, void (T::*)()) except that it invokes a method taking one argument, and you must specify that extra argument when calling this method.
template<typename T>
static Ref< Thread >	run (void(*)(T), T, bool start=true)
	Let a new thread invoke a static 1-argument-function of your choise.
static Ref< Thread >	run (void(*)(), bool start=true)
	Let a new thread invoke a static void-function of your choise.
static void	start (Ref< Thread >) throw (AlreadyStartedException)
	Let a new thread invoke the virtual main method of the specified Thread object.
static Ref< Thread >	self ()
	Return a reference to the Thread object associated with the thread that calls this method.
static void	sleep (const Time &period) throw (UnexpectedException)
	Make the calling thread sleep for the specified amount of time.
static void	sleepUntil (const Time &timeout) throw (UnexpectedException)
	Make the calling thread sleep until the specified point in time has been reached.
static void	acceptTermination () throw (UnexpectedException)
	This method should be called by a thread if it is executing lengthy computations without any calls to Condition::wait, Condition::timedWait or Thread::sleep.
static void	selfResurrect ()
	Recover from termination.
static void	mainExitWait ()
	When called by the main thread it suspends the main thread until all other threads have terminated.
Protected Member Functions
virtual void	main ()=0
	This is the method that will be run as the new thread.
	Thread ()
	Does not start the thread.
virtual	~Thread ()
Classes
struct	AlreadyStartedException
struct	NotStartedException
struct	SelfThread
struct	ThreadException

---

Detailed Description

A thread of execution (aka light weight proccess or LWP) represented as an object.

You may think of it as an object with a will of its own or an animated object. Just as in the case of humans, going from one to two or more threads of execution opens up a whole new realm of wonders and disasters. So, prepare yourself.

This class supports safe cancelation/termination of threads. The problem of thread cancelation usually is that it is hard to guarantee proper cleanup of allocated memory and other resources. This is especially true in C++ programs where it is crucial that the stack is noramlly unwinded ensuring that class detructors gets called. So what we really need is to allow one thread to provoke an exception in another thread. This is exactly what this thread class supports. If a thread gets a terminate request, then any current or future calls to any of the following methods will raise a TerminatedException.

Semaphore::down Condition::wait, Condition::timedWait, Condition::select, Thread::wait, Thread::sleep, Thread::acceptTermination,

Todo:

Implement thread priority.

Todo:

The following is probably not safe: 'volatile bool terminateRequest;'.

Should use Atomic instead.

Todo:

One should considder adding a certain feature to the Thread class which would lead to simpler implementations in cases where threads are to run as a service for as long as the servicing object is referenced by outside parties such as a server object.

In any case it is important that a Thread object is kept alive while the thread is running. This is currently done by holding one extra (forward) reference count during execution. This is most suitable in scenarios where a thread is intended to run for a short while and then end, probably because it has a certain limited job to do. Often, though, we use threads in a servicing scenario where there is no intrinsic condition limiting the running time. This leads, as you can see, to a situation where the object will keep itself alive indefinitely unless the thread is explicitely terminated. This is most often an unwanted effect. In cases like this, we would rather like an automated trigger terminating the thread execution when all outside reference are released. To simulate this, one can employ a tandem object sollution where one object, A, is referenced by the ouside. And the Thread object, B, is reference only by A. Now, when all outside references are abandoned, A's destructor gets called and from here we can explicitly terminate the thread in B. This keeps working even if we add a backwards reference (BackRef) from B to A except now we must terminate the thread from the forwardDestroyed method of A instead. So, why not add a feature to Thread that supports this behaviour directly?

Definition at line 98 of file thread.H.

---

Constructor & Destructor Documentation

Archon::Utilities::Thread::Thread (   )  [protected]

Does not start the thread. You must use Thread::start to do that - BUT NOT WITHIN THE COSTRUCTOR! Definition at line 181 of file thread.C.

---

Member Function Documentation

void Archon::Utilities::Thread::acceptTermination (   )  throw (UnexpectedException) [static]

This method should be called by a thread if it is executing lengthy computations without any calls to Condition::wait, Condition::timedWait or Thread::sleep. This is to ensure a fair response time to a termination request by another thread. Note, the more frequent this method is called the shorter the response to a tremination request will be. Note: This method is re-entrant/thread safe. Definition at line 304 of file thread.C.

virtual void Archon::Utilities::Thread::main (   )  [protected, pure virtual]

This is the method that will be run as the new thread. You should override this method. Implemented in T, Producer, Consumer, Archon::Utilities::Stream::Connector< C >, Archon::Utilities::Thread::SelfThread, Archon::Utilities::MethodVoidRunner< T >, Archon::Utilities::MethodArgRunner< T, U >, Archon::Utilities::FuncVoidRunner, Archon::Utilities::FuncArgRunner< T >, Archon::X3D::SAI::ApplicationSceneReaper, and Archon::X3D::SAI::Session::ExternalEventQueue.

void Archon::Utilities::Thread::mainExitWait (   )  [static]

When called by the main thread it suspends the main thread until all other threads have terminated. The intention is that you should call this method just before returning from the main function of your program. The intended purpose of this method is enforce proper deallocation of all resources by ensuring that all stacks are unwinded completely before your program exits. It makes no sence to call this method for any other thread than the main thread, since when the main thread terminates it will imadiately annihilate all other threads, preventing them from proper stack unwinding. Theads which are not created by one of the methods in this Thread class and which have never called the Thread::self method are unknown to this method, and will therefore not be waited for. Definition at line 309 of file thread.C. References self(). Referenced by Archon::Console3d::main().

Ref< Thread > Archon::Utilities::Thread::run (  void(*)()  , bool  start = true )  [inline, static]

Let a new thread invoke a static void-function of your choise. Note: This method is re-entrant/thread safe. You must not considder global data to be acccessible. They may be destroyed. Definition at line 430 of file thread.H. References start().

template<typename T> Ref< Thread > Archon::Utilities::Thread::run (  void(*)(T)  , T  , bool  start = true )  [static]

Let a new thread invoke a static 1-argument-function of your choise. Note: This method is re-entrant/thread safe. Be sure to not use an aliased types '&' for the method argument, since copying is essential to thread safty. You must not considder global data to be acccessible. They may be destroyed. Definition at line 455 of file thread.H. References start().

template<typename T, typename U> Ref< Thread > Archon::Utilities::Thread::run (  Ref< T >  , void(T::*)(U)  , U  , bool  start = true )  [static]

Like Thread::run(Ref<T>, void (T::*)()) except that it invokes a method taking one argument, and you must specify that extra argument when calling this method. Note: Be sure to not use an aliased types '&' for the method argument, since copying is essential to thread safty. Definition at line 414 of file thread.H. References start().

template<typename T> Ref< Thread > Archon::Utilities::Thread::run (  Ref< T >  , void(T::*)()  , bool  start = true )  [static]

Let a new thread invoke a method of your choise on a reference counted object of your choise. An extra reference count is held during the execution of the specified method, and it is released afterwards. Note: This method is re-entrant/thread safe. The idea behind this method is that you have guaranteed access to the data of the object passed as argument. That is, the occupied memory is not deallocated while your method is running. You cannot safely access anything else unles it is also a dynamically allocated object. Definition at line 385 of file thread.H. References start(). Referenced by Archon::Utilities::Job::Queue::add(), and Archon::Utilities::Web::DefaultClient::request().

Ref< Thread > Archon::Utilities::Thread::self (   )  [static]

Return a reference to the Thread object associated with the thread that calls this method. This also works for the main thread and any other thread created in the context of the pthead library. Note: This method is re-entrant/thread safe. Definition at line 250 of file thread.C. Referenced by mainExitWait(), Archon::Utilities::Condition::select(), Archon::Utilities::Condition::timedWait(), and Archon::Utilities::Condition::wait().

void Archon::Utilities::Thread::selfResurrect (   )  [static]

Recover from termination. That is, you are allowed to catch the TerminatedException in your thread if you do not want your thread to terminate completely. But note that this may be in conflict with the intent of some other thread calling terminate on this thread. Note: This method is re-entrant/thread safe. Definition at line 274 of file thread.C.

void Archon::Utilities::Thread::sleep (  const Time &  period  )  throw (UnexpectedException) [static]

Make the calling thread sleep for the specified amount of time. See also: Time Note: This method is re-entrant/thread safe. Definition at line 286 of file thread.C. References Archon::SaiTestApps::Filebrowser::mutex, Archon::Utilities::Time::now(), and Archon::Utilities::Condition::timedWait(). Referenced by Archon::SaiTestApps::Spot::main(), Archon::SaiTestApps::Simple::main(), Archon::SaiTestApps::Molecule::main(), Archon::SaiTestApps::Cylinders::main(), Archon::SaiTestApps::Clock::main(), Archon::Raytracer::Engine::render(), Archon::Raytracer::viewScene(), and Archon::Console3d::viewScene().

void Archon::Utilities::Thread::sleepUntil (  const Time &  timeout  )  throw (UnexpectedException) [static]

Make the calling thread sleep until the specified point in time has been reached. See also: Time Note: This method is re-entrant/thread safe. Definition at line 296 of file thread.C. References Archon::SaiTestApps::Filebrowser::mutex, and Archon::Utilities::Condition::timedWait(). Referenced by Archon::Render::Test::main(), and Archon::Display::Test::main().

void Archon::Utilities::Thread::start (  Ref< Thread >   )  throw (AlreadyStartedException) [static]

Let a new thread invoke the virtual main method of the specified Thread object. To be of any use, you must derive your own class from the Thread object. An extra reference count is held on the thread object during the execution of the specified method, and it is released when execution ends. Note: It is strongly recomended that you dont use this method in the constructor specifying 'this' as argument. If you do, you might get back (from the constructor) an object which has already been deleted. See also: Ref<T> Note: This method is re-entrant/thread safe. NEVER do a Thread::start(this) in a constructor! The idea behind this method is that you have guaranteed access to the data of the object passed as argument. That is, the occupied memory is not deallocated while your method is running. You cannot safely access anything else unles it is also a dynamically allocated object. Definition at line 208 of file thread.C. Referenced by Archon::Render::Conductor::addPipe(), and run().

void Archon::Utilities::Thread::terminate (   )

Issue a termination request for this thread. This causes any present or furure calls to Semaphore::down Condition::wait, Condition::timedWait, Condition::select, Thread::wait, Thread::sleep, Thread::acceptTermination, by this thread to imediately throw a TerminatedException. This method will normally be called by some other thread in the intent to bring the execution of this thread to an end. Note: This method is re-entrant/thread safe. Definition at line 262 of file thread.C. References Archon::Utilities::Condition::mutex, Archon::Utilities::Condition::notifyAll(), and Archon::Utilities::Mutex::Lock::release().

void Archon::Utilities::Thread::wait (   )  throw (NotStartedException, UnexpectedException)

Wait for this thread to stop. Note: This method is re-entrant/thread safe. That is, any number of threads may wait simultaniously. Definition at line 279 of file thread.C. References Archon::Utilities::Condition::wait(). Referenced by T::~T().

---

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

• archon/util/thread.H
• archon/util/thread.C

---