MCThread Class Reference

Provides support for multiple concurrent threads of control in an application. More...

#include <mcllib/MCThread.h>

Inheritance diagram for MCThread:

List of all members.

Public Types
enum	EPriority { THRPRILOW, THRPRINORMAL, THRPRIHIGH, THRPRIURGENT }
	Thread priority. More...
enum	EScope { THRSCOPELOCAL, THRSCOPEGLOBAL, THRSCOPEBOUND }
	Thread scope. More...
enum	EState { THRSTATEJOIN, THRSTATENOJOIN }
	Thread state. More...
enum	EType { THRTYPEUSER, THRTYPESYS }
	Thread type. More...
Public Member Functions
mcthreadid_t	getId () const
	Get the unique id of the thread.
const MCString &	getName () const
	Get the name of the thread as specified at construction time.
void	join ()
	Wait until this thread has finished working.
	MCThread (const MCString &name)
	Construct a named thread object.
	MCThread ()
	Construct an unamed thread object.
void	setInterrupt ()
	Interrupt the thread if it is interruptable.
void	setPriority (EPriority pri)
	Set the priority of thread.
void	start (MCRunnable *pRunnable, EType type=THRTYPEUSER, EScope scope=THRSCOPELOCAL, EState state=THRSTATEJOIN, EPriority pri=THRPRINORMAL, mcstacksize_t sz=0)
	Start a thread running.
Static Public Member Functions
void	clearInterrupt ()
	Clear any pending interrupt on the current thread.
MCThread	getCurrentThread ()
	Obtain an MCThread object for the calling thread.
MCRefPtr< MCThreadData >	getData (mcthreaddatakey_t index)
	Get the thread data stored for an index.
mcthreaddatakey_t	getDataIndex (const MCString &key)
	Get a thread data index.
void	setData (mcthreaddatakey_t index, MCThreadData *pData)
	Set (store) the thread data for an index.
void	setDataAll (mcthreaddatakey_t index, MCThreadData *pData)
	Set (store) the thread data for an index for the current thread and all future threads.
void	sleep (mcinterval_t interval)
	Sleep for a number of milliseconds.
void	yield ()
	Yield (give up the CPU) to another thread.

---

Detailed Description

Provides support for multiple concurrent threads of control in an application.

Threads are used in conjunction with runnables. A runnable provides a run function which is called by the thread object. The runnable is a light-weight interface. The same thread object can be used (at different times) to run different runnables.

---

Member Enumeration Documentation

enum EPriority

Thread priority. Enumeration values: THRPRILOW  Low priority thread. THRPRINORMAL  Normal priority thread. THRPRIHIGH  High priority thread. THRPRIURGENT  Urgent priority thread.

enum EScope

Thread scope. Enumeration values: THRSCOPELOCAL  Local scoped thread. THRSCOPEGLOBAL  Global scoped thread. THRSCOPEBOUND  Bound thread.

enum EState

Thread state. Enumeration values: THRSTATEJOIN  Thread can be join()ed. THRSTATENOJOIN  Thread cannot be join()ed.

enum EType

Thread type. Enumeration values: THRTYPEUSER  User thread. THRTYPESYS  System thread.

---

Constructor & Destructor Documentation

MCThread (   )

Construct an unamed thread object. The name is set to [UNKNOWN]

MCThread (  const MCString &  name  )

Construct a named thread object. Parameters: name  the name of the thread for diagnostic purposes.

---

Member Function Documentation

void clearInterrupt (   )  [static]

Clear any pending interrupt on the current thread. If the current thread is marked as interrupted, clear the interrupt

MCThread getCurrentThread (   )  [static]

Obtain an MCThread object for the calling thread. Returns: a thread object which represents the calling thread.

MCRefPtr<MCThreadData> getData (  mcthreaddatakey_t  index  )  [static]

Get the thread data stored for an index. Parameters: index  a valid thread data index obtained via a call to getDataIndex(). If the index is not valid an exception is thrown. Returns: a reference to the MCThreadData stored at the index or null if no data has been stored at the index.

mcthreaddatakey_t getDataIndex (  const MCString &  key  )  [static]

Get a thread data index. Parameters: key  string key for which an index is required. All calls for the same key return the same index on any thread. It is recommended that the following form be used for key names - key.domain (e.g. key.my.com). Do not use the domain miba.co.uk. Note that the index returned for a given key may change between application invocations. Do not serialize mcthreaddatakey_t values and attempt to reuse them between application invocations. Returns: an mcthreaddatakey_t for the string key

mcthreadid_t getId (   )  const

Get the unique id of the thread. Each thread has an id which is unique within the process in which it is running, whilst it continues to run and references exist to it. Once a thread has terminated and no references exist to it, the thread id may be re-used by another thread. Returns: the unique id of the thread.

const MCString& getName (   )  const

Get the name of the thread as specified at construction time. If no name was specified a system default name will be supplied. This is useful when debugging multi-threaded applications. Returns: the name of the thread specified at construction time, or a system default name if no name was specified.

void join (   )

Wait until this thread has finished working. Has no effect if the thread has not been start()ed. An exception will be thrown if the thread cannot be joined.

void setData (  mcthreaddatakey_t  index, MCThreadData *  pData )  [static]

Set (store) the thread data for an index. Parameters: index  a valid thread data index obtained via a call to getDataIndex(). If the index is not valid an exception is thrown. pData  an MCThreadData derived object. MCThreadData::attach() is called after the thread data has been attached to the thread. When the thread terminates, MCThreadData::detach() is called.

void setDataAll (  mcthreaddatakey_t  index, MCThreadData *  pData )  [static]

Set (store) the thread data for an index for the current thread and all future threads. Parameters: index  a valid thread data index obtained via a call to getDataIndex(). If the index is not valid an exception is thrown. pData  an MCThreadData derived object. MCThreadData::attach() is called after the thread data has been attached to the thread. When the thread terminates, MCThreadData::detach() is called. When new threads are created, MCThreadData::attach() is called before the MCRunnable::run() method starts.

void setInterrupt (   )

Interrupt the thread if it is interruptable. Has no effect if the thread has not been start()ed. An exception will be thrown if the thread cannot be interrupted.

void setPriority (  EPriority  pri  )

Set the priority of thread. Has no effect if the thread has not been start()ed. Parameters: pri  the new priority for the thread

void sleep (  mcinterval_t  interval  )  [static]

Sleep for a number of milliseconds. The current thread (the one calling sleep) is put to sleep. Parameters: interval  the number of milliseconds to sleep for.

void start (  MCRunnable *  pRunnable, EType  type = THRTYPEUSER, EScope  scope = THRSCOPELOCAL, EState  state = THRSTATEJOIN, EPriority  pri = THRPRINORMAL, mcstacksize_t  sz = 0 )

Start a thread running. The start function returns once the thread has been started. If a thread cannot be started an exception is thrown. The run() function of the runnable will run concurrently with the thread that called the start function. Note that the run() function may not have been called before start returns although a thread will have been created and the run() function scheduled to begin. Parameters: pRunnable  must point to an MCRunnable derived object. type  the type of thread to start scope  the thread scope state  the thread state. Indicates whether the thread can be joined or not. pri  the thread priority. Higher priority threads get more CPU time than lower priority threads. sz  the size of the thread stack. Zero indicates that a default stack size should be used.

void yield (   )  [static]

Yield (give up the CPU) to another thread. The current thread (the one calling yield) yields to some other thread

---