Wefts::OSThreadBase Class Reference
[OS Threading Level Abstraction.]

#include <wefts_os_base.h>

Inheritance diagram for Wefts::OSThreadBase:

Inheritance graph
[legend]
List of all members.

Detailed Description

Thread OS layer abstraction This class can be rewritten in other header files to implement different os specific threading system.

See also:
OS Threading Abstraction (and Independence) Layer


Public Member Functions

virtual bool priority (OSPriority prio_class, int boost=0)=0
 Sets thread priority.

virtual bool start (void *(*func)(void *), void *data)=0
 Starts OS specific thread OS dependant implementation must provide a valid function to execute the thread; Thread.cpp has already some valid ones.

virtual bool stop ()=0
 Stop this OS specific thread.

virtual void * join ()=0
 Joins this OS Specific threads.

virtual int enableCancel ()=0
 Enables cancellation: This function returns the old status on success, that can be later reset with setCancelStatus.

virtual int disableCancel ()=0
 Disables cancellation.

virtual bool setCancelState (int state)=0
 Raw function to set the cancel type.

virtual void testCancel ()=0
 Kill the thread on OS level cancellation.

virtual void setCancelDeferred ()=0
 Tells the thread that it must use deferred cancellation.

virtual void detach ()=0
 Detach thread.

virtual void emuDeferredStart ()
 Starts emulated deferred cancellation.

virtual void emuDeferredEnd ()
 End emulated deferred cancellation.

virtual void * osRun (void *(*func)(void *), void *data, void(*cleanup)(void *))=0
 Executes a procedure under the hood of a cleanup procedure This method requires the underlying OS threading system to set up a single cleanup procedure, execute the procedure "func" and then call the cleanup procedure; if the thread is canceled, os system must provide.

virtual bool same () const =0
 Returns true if the currently running thread and this objects are the same.

virtual bool equal (const OSThreadBase &th) const =0
 Returns true if this object is equal (on OS opinion) to the parameter.

virtual bool setCurrent ()=0
 Change this thread object to the current OS dependant thread.

virtual void invalidate ()=0
virtual bool operator== (OSThreadBase &th)
 Pass the test to equal().

virtual bool operator!= (OSThreadBase &th)
 Pass the test to ! equal().


Protected Member Functions

 OSThreadBase ()
 Newly created thread.

 OSThreadBase (bool)
 Already running thread.

virtual void exit (void *data)=0
 Exit the thread.


Constructor & Destructor Documentation

Wefts::OSThreadBase::OSThreadBase  )  [inline, protected]
 

Newly created thread.

Subclassess must calll invalidate() member to specify that the current thread is still not running.

Wefts::OSThreadBase::OSThreadBase bool   )  [inline, protected]
 

Already running thread.

Call this constructor if you need to have a reference to the thread that is currently running; this will set the OSThreadBase internal data as if a start were called at some point.


Member Function Documentation

virtual void Wefts::OSThreadBase::detach  )  [pure virtual]
 

Detach thread.

Note:
Wefts detaching differs from pthread detaching; a wefts detached thread is just a thread whose class data will be automatically destroyed on termination (and that can't be joined).
See also:
Thread::detach()

Implemented in Wefts::OSThreadPthread, and Wefts::OSThreadWindows.

virtual int Wefts::OSThreadBase::disableCancel  )  [pure virtual]
 

Disables cancellation.

Wokrs like enableCancel.

See also:
enableCancel()

Implemented in Wefts::OSThreadPthread, and Wefts::OSThreadWindows.

virtual void Wefts::OSThreadBase::emuDeferredEnd  )  [inline, virtual]
 

End emulated deferred cancellation.

In base class, it does nothing. If the os does support natively the deferred cancellation scheme, this function is useless.

See also:
Cancellation Issues

virtual void Wefts::OSThreadBase::emuDeferredStart  )  [inline, virtual]
 

Starts emulated deferred cancellation.

In base class, it does nothing. If the os does support natively the deferred cancellation scheme, this function is useless.

See also:
Cancellation Issues

virtual int Wefts::OSThreadBase::enableCancel  )  [pure virtual]
 

Enables cancellation: This function returns the old status on success, that can be later reset with setCancelStatus.

On error, return type is undefined.

Note:
a candidate for exception rising.
Todo:
write a low-level exception system.

Implemented in Wefts::OSThreadPthread, and Wefts::OSThreadWindows.

virtual bool Wefts::OSThreadBase::equal const OSThreadBase th  )  const [pure virtual]
 

Returns true if this object is equal (on OS opinion) to the parameter.

Implemented in Wefts::OSThreadPthread, and Wefts::OSThreadWindows.

virtual void Wefts::OSThreadBase::exit void *  data  )  [protected, pure virtual]
 

Exit the thread.

Run() can call this method instead of retunring a void *; the effect is the same.

Implemented in Wefts::OSThreadPthread, and Wefts::OSThreadWindows.

virtual void Wefts::OSThreadBase::invalidate  )  [pure virtual]
 

Implemented in Wefts::OSThreadPthread, and Wefts::OSThreadWindows.

virtual void* Wefts::OSThreadBase::join  )  [pure virtual]
 

Joins this OS Specific threads.

Implemented in Wefts::OSThreadPthread, and Wefts::OSThreadWindows.

virtual bool Wefts::OSThreadBase::operator!= OSThreadBase th  )  [inline, virtual]
 

Pass the test to ! equal().

virtual bool Wefts::OSThreadBase::operator== OSThreadBase th  )  [inline, virtual]
 

Pass the test to equal().

virtual void* Wefts::OSThreadBase::osRun void *(*  func)(void *),
void *  data,
void(*  cleanup)(void *)
[pure virtual]
 

Executes a procedure under the hood of a cleanup procedure This method requires the underlying OS threading system to set up a single cleanup procedure, execute the procedure "func" and then call the cleanup procedure; if the thread is canceled, os system must provide.

"data" to the cleanup procedure and exit cleanly.

Paramere data is actually a Thread or derived class isntance, but it must be considered opaque to os layer.

The parameter for clanup, that must be called inside this method, is must be a ThreadAndReturn structure, which contains a pointer to a Wefts::Thread or derived object, and the return value of the func parameter. Derived classes are responsible to fill correctly this structrue: the thread member of ThreadAndReturn must be set to the data parameter; before func is called, the runReturn element of the ThreadAndReturn structure must be set to zero, and then it must be set to func call return value.

Currently func() is only a wrapper to call data->run(), but this may change in the future.

Parameters:
func a wrapper that calls data->run() and returns its value.
data a pointer to a Thread class or Thread derived class instance
cleanup a pointer to a cleanup routine, accepting ThreadAndReturn structure pointer as a parameter

Implemented in Wefts::OSThreadPthread, and Wefts::OSThreadWindows.

virtual bool Wefts::OSThreadBase::priority OSPriority  prio_class,
int  boost = 0
[pure virtual]
 

Sets thread priority.

Thread priority is defined by a class and a boost throttle. System may implement this differently, or even ignore it, if there isn't any low level mean to determine thread priority; wefts itself does not enforce any priority, but it tries to get the OS to act as near as possible to the required class and thread boost. The thread class defines how the thread is rescheduled after a wait, or after a swap; the boost level is a value that tells the system scheduler to prefer some thread with respect to the others in the same thread class. The higher is the boost level, the better are the chance of the thread to be rescheduled before the same threads with lower boost. Boost value can also be negative, meaning that the thread may be scheduled less often than other threads in the same class having boost 0.

Wefts will try to arrange the theoretical model of Wefts priorities (OSPriority ) into the available threading model and OS capabilties.

Note:
Often, OS have a concept of priority that works the other way round; i.e. the "nice" level of a process in unix is so that the higher, the worst, the lower (even negative), the better. Do not confuse this with wefts boost number.
Boost levels may be any positive or negative number; wefts will try to fit the boost level into the underlying OS and threading scheme; usually a value ranging from -20 to 20 is the maximum range that you may proficiently used. If you give a boost level that wefts cannot request to the underlying system, this will be truncated to the maximum or minimum available.

The method returns ture if the priority may be set, or false otherwise; on some systems, the request to set a priority may fail due the need for higher system privilege to do so.

Implemented in Wefts::OSThreadPthread, and Wefts::OSThreadWindows.

virtual bool Wefts::OSThreadBase::same  )  const [pure virtual]
 

Returns true if the currently running thread and this objects are the same.

Implemented in Wefts::OSThreadPthread, and Wefts::OSThreadWindows.

virtual void Wefts::OSThreadBase::setCancelDeferred  )  [pure virtual]
 

Tells the thread that it must use deferred cancellation.

The OS may provide deferred cancellation schemes natively, or not. In the latter case, deferred cancellation must be emulated; See Cancellation Issues. When OS does not provides inbound deferred cancellation, this routine must do nothing.

Implemented in Wefts::OSThreadPthread, and Wefts::OSThreadWindows.

virtual bool Wefts::OSThreadBase::setCancelState int  state  )  [pure virtual]
 

Raw function to set the cancel type.

This function should be used only with the integer returned by enableCancel() and disableCancel(), as no assumption can be made about what the meaning of the parameter could be in different environments.

Parameters:
state system dependant (that is to say: don't touch it).
Returns:
true on success

Implemented in Wefts::OSThreadPthread, and Wefts::OSThreadWindows.

virtual bool Wefts::OSThreadBase::setCurrent  )  [pure virtual]
 

Change this thread object to the current OS dependant thread.

It makes so that all the internal variables are set to reflect this current thread. In some implementation, updating of some variables my be deferred to a later moment; the important thing is to change the thread type.

Implemented in Wefts::OSThreadPthread, and Wefts::OSThreadWindows.

virtual bool Wefts::OSThreadBase::start void *(*  func)(void *),
void *  data
[pure virtual]
 

Starts OS specific thread OS dependant implementation must provide a valid function to execute the thread; Thread.cpp has already some valid ones.

Parameters:
func the function to be executed in parallel thread.
data the data to be passed to os-level thread function

Implemented in Wefts::OSThreadPthread, and Wefts::OSThreadWindows.

virtual bool Wefts::OSThreadBase::stop  )  [pure virtual]
 

Stop this OS specific thread.

Implemented in Wefts::OSThreadPthread, and Wefts::OSThreadWindows.

virtual void Wefts::OSThreadBase::testCancel  )  [pure virtual]
 

Kill the thread on OS level cancellation.

Implemented in Wefts::OSThreadPthread, and Wefts::OSThreadWindows.


The documentation for this class was generated from the following file:
Generated on Tue Oct 5 14:57:02 2004 for Wefts by doxygen 1.3.7