os::Thread Class Reference

Thread class. More...

Inheritance diagram for os::Thread:

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

Protected Member Functions
void	Delay (uint32 nMicros)
	Temporarily suspend thread execution. More...

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 (henri.nosp@m.k@bo.nosp@m.ing.n.nosp@m.u)

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 (henri.nosp@m.k@bo.nosp@m.ing.n.nosp@m.u)

References Initialize().

Thread::~Thread ( void  )

virtual

References Terminate().

Member Function Documentation

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 (henri.nosp@m.k@bo.nosp@m.ing.n.nosp@m.u)

int Thread::GetPriority

(

)

Description:

Returns priority or throws ThreadException if the thread is invalid.

Author

Henrik Isaksson (henri.nosp@m.k@bo.nosp@m.ing.n.nosp@m.u)

References EINVALIDTHREAD.

proc_id Thread::GetProcessId

(

)

Description:

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

Author

Henrik Isaksson (henri.nosp@m.k@bo.nosp@m.ing.n.nosp@m.u)

thread_id Thread::GetThreadId

(

)

Description:

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

Author

Henrik Isaksson (henri.nosp@m.k@bo.nosp@m.ing.n.nosp@m.u)

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 (henri.nosp@m.k@bo.nosp@m.ing.n.nosp@m.u)

References Terminate().

Referenced by Thread().

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 (henri.nosp@m.k@bo.nosp@m.ing.n.nosp@m.u)

Implemented in MountDialogScanner.

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 (henri.nosp@m.k@bo.nosp@m.ing.n.nosp@m.u)

References EINVALIDTHREAD.

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 (henri.nosp@m.k@bo.nosp@m.ing.n.nosp@m.u)

References EINVALIDTHREAD.

void Thread::Stop

(

void

)

Description:

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

See Also

Start(), Terminate()

Author

Henrik Isaksson (henri.nosp@m.k@bo.nosp@m.ing.n.nosp@m.u)

References EINVALIDTHREAD.

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 (henri.nosp@m.k@bo.nosp@m.ing.n.nosp@m.u)

Referenced by Initialize(), and ~Thread().

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 (henri.nosp@m.k@bo.nosp@m.ing.n.nosp@m.u)