os::Thread Class Reference
[Various utillity classes.]

Thread class. More...

Inheritance diagram for os::Thread:

List of all members.

Public Member Functions
	Thread (const char *pzName, int nPriority=NORMAL_PRIORITY, int nStackSize=0)
	Constructor.
virtual	~Thread ()
void	Start ()
	Begin/Resume execution.
void	Stop ()
	Suspend execution.
void	WaitFor ()
	Wait for thread.
void	Terminate ()
	Kill thread unconditionally.
void	Initialize (const char *pzName, int nPriority=NORMAL_PRIORITY, int nStackSize=0)
	Reset thread.
void	SetPriority (int nPriority=IDLE_PRIORITY)
	Set priority.
int	GetPriority ()
	Get priority.
thread_id	GetThreadId ()
	Get thread ID.
proc_id	GetProcessId ()
	Get process ID.
virtual int32	Run (void)=0
	Thread code.
Protected Member Functions
void	Delay (uint32 nMicros)
	Temporarily suspend thread execution.

---

Detailed Description

Description:

This class is a wrapper class for Syllable threads, meant to simplify the use of threads.

To use it, you create a subclass of Thread, and override the Run() method with the code you want to run in the thread. Then simply instansiate your new class, and call Start() on it.

Example:

 #include <util/thread.h>
 #include <stdio.h>     // printf()
 #include <unistd.h>    // sleep()

 using namespace os;

 class MyThread : public Thread {
        public:
        MyThread() : Thread( "MyThread" ) {}

        int32 Run() {
                for( int i = 0; i < 10000; i++ ) {
                        Delay( 1000000 );
                        printf( "In the loop: %d\n", i );
                }
                return 0;
        }
 };

 int main(void)
 {
        MyThread thread;
        thread.Start();
        printf( "The thread is running now!\n");
        sleep( 10 );    // Let it run for 10 secs
        thread.Terminate();
        return 0;
 }

See also:

Run(), Start(), Terminate()

Author:

Henrik Isaksson ([email protected])

---

Constructor & Destructor Documentation

Thread::Thread	(	const char *	pzName,
		int	nPriority = NORMAL_PRIORITY,
		int	nStackSize = 0
	)

Description:

Create a new thread.

Parameters:

	pzName	Name of the thread.
	nPriority	Thread priority (IDLE_PRIORITY, LOW_PRIORITY, NORMAL_PRIORITY, DISPLAY_PRIORITY, URGENT_DISPLAY_PRIORITY or REALTIME_PRIORITY).

Note:

Threads are created in a suspended state. To start a thread's execution, call Start().

See also:

Start()

Author:

Henrik Isaksson ([email protected])

Thread::~Thread

(

)

[virtual]

---

Member Function Documentation

void Thread::Start

(

void

)

Description:

Resume execution of a previously stopped thread. The thread will continue to run from where it were when it was stopped. New threads defaults to suspended state, so a newly created thread must be started with Start().

See also:

Stop()

Author:

Henrik Isaksson ([email protected])

void Thread::Stop

(

void

)

Description:

Suspends thread execution so that it can be resumed using Start().

See also:

Start(), Terminate()

Author:

Henrik Isaksson ([email protected])

void Thread::WaitFor

(

void

)

Description:

Wait for the thread to finish. This function will not return until the thread has finished executing.

Note:

Do not call this method from the thread's own code.

Author:

Henrik Isaksson ([email protected])

void Thread::Terminate

(

void

)

Description:

Send a KILL signal to the thread and terminate it immediately. A terminated thread cannot resume execution, but it can be reset and restarted.

See also:

Stop(), Initialize()

Note:

The thread will be invalid after calling this method. The only valid operation on the object will be deleting it or calling Initialize() to reset the thread.

Author:

Henrik Isaksson ([email protected])

void Thread::Initialize	(	const char *	pzName,
		int	nPriority = NORMAL_PRIORITY,
		int	nStackSize = 0
	)

Description:

Re-initializes a thread and prepares it for execution, after it has been terminated with Terminate(). If the thread has not been terminated prior to this call, it will be terminated and then initialized.

Parameters:

	pzName	Name of the thread.
	nPriority	Thread priority (IDLE_PRIORITY, LOW_PRIORITY, NORMAL_PRIORITY, DISPLAY_PRIORITY, URGENT_DISPLAY_PRIORITY or REALTIME_PRIORITY).
	nStackSize	Stack size, 0 means default (currently 128k). Minimum stack size is currently 32k.

See also:

Terminate()

Note:

The thread is reset to a suspended state. To start a thread's execution, call Start().

Author:

Henrik Isaksson ([email protected])

void Thread::SetPriority

(

int

nPriority = IDLE_PRIORITY

)

Description:

Set thread priority. Throws ThreadException if the thread is invalid.

Parameters:

nPriority

Thread priority (IDLE_PRIORITY, LOW_PRIORITY, NORMAL_PRIORITY, DISPLAY_PRIORITY, URGENT_DISPLAY_PRIORITY or REALTIME_PRIORITY).

Author:

Henrik Isaksson ([email protected])

int Thread::GetPriority

(

)

Description:

Returns priority or throws ThreadException if the thread is invalid.

Author:

Henrik Isaksson ([email protected])

thread_id Thread::GetThreadId

(

)

Description:

Returns thread ID or -1 if the thread is invalid.

Author:

Henrik Isaksson ([email protected])

proc_id Thread::GetProcessId

(

)

Description:

Returns process ID or -1 if the thread is invalid.

Author:

Henrik Isaksson ([email protected])

virtual int32 os::Thread::Run

(

void

)

[pure virtual]

Description:

The code that is executed by the thread. This method must be overridden and implemented in a subclass.

Author:

Henrik Isaksson ([email protected])

Implemented in MountDialogScanner.

void Thread::Delay

(

uint32

nMicros

)

[protected]

Description:

Temporarily suspend thread execution. This method is only intended for use from the thread's own code.

Parameters:

nMicros

Delay time in microseconds.

Note:

Although the time is specified in microseconds, you can't expect that kind of precision. The actual delay time depends on how the kernel's timer interrupts are configured.

Author:

Henrik Isaksson ([email protected])

---