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

#include <wefts_os_base.h>

Inheritance diagram for Wefts::OSThreadBase:

[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:

• wefts_os_base.h

---