fTHREAD

Quick Data

Header file:thread.h
Object name:fTHREAD
Object index:1 of 1 Object

General Description

The fTHREAD is a class to spawn and manage a thread. A thread is an extra task that works alongside another task. It can be a long task, or a short task - or just something that runs alongside something else.

Threads can be handy - but use them wisely, as two threads running side-by-side will slow down both threads (although depending on what each thread does, it might be negligable).

For information on exactly how to create a thread, please see the examples section at the end.

Thread Priorities

These values are used when getting or setting a thread's priority.

Name Description Value
tpHighest This is the highest standard thread priority. THREAD_PRIORITY_HIGHEST
tpHigh This is a high standard thread priority. THREAD_PRIORITY_ABOVE_NORMAL
tpNormal This is the normal thread priority. THREAD_PRIORITY_NORMAL
tpLow This is a slightly lower than normal thread priority. THREAD_PRIORITY_BELOW_NORMAL
tpLowest This is the lowest standard thread priority. THREAD_PRIORITY_LOWEST
tpIdle This is the lowest possible thread priority. It does not allow the thread much CPU time - it could be useful for something quiet that you want to run in the background - like a timer that is waiting for something. THREAD_PRIORITY_IDLE
tpRealTime This is the absolute highest priority that you can assign to a thread. Use this one with caution - as it will virtually roll you system to a halt (except for the thread with this priority!). Microsoft recommends only using this priority for a few seconds at a time - and that is a good idea! THREAD_PRIORITY_TIME_CRITICAL

Methods

Prototype Description
bool Create(LPTHREAD_START_ROUTINE ThreadFunction, void* Argument, bool StartAutomatically); This function creates and optionally starts the thread. The first parameter is the function to act as a thread (it has a special prototype - see the examples section). The second argument is a pointer to anything that is data to pass along to the thread. The third argument specifies whether or not to actually start the thread immediately. If you choose not to, the thread will be paused when it is created.
void Pause(void);
void Resume(void); 		I don't think that these need too much explaining...
bool IsFinished(void); This function returns TRUE if the thread is finished, or FALSE otherwise.
DWORD GetReturnCode(void); When a thread exits, it can return a code, or a code can be returned automatically (which will then depend on how it quit). You can then read that value with this function - but, if you are going to read this value, be sure to read this code before calling the Close() function, as documented below.
bool Close(void); This function closes the thread. It does not stop the thread if it is still running - it just closes the thread handle - in other words, some basic internal housekeeping. If the thread is still running, this function returns FALSE.
void Kill(void); This function ends the thread - regardless of what it is doing or how far it is. It is not recommended to stop the thread this way - as any allocated memory will not be cleaned up.
void SetPriority(int Priority);
int GetPriority(void); 		These functions deal with the priority - the first function sets the priority, and the second function returns the priority. Both of these functions use values from the table at the top of the document.

Sample Code

The following snippet gives a basic idea of how to use this component.


//Create an instance of the thread object...
fTHREAD Thread;

//Now the thread function has a prototype like this:
DWORD WINAPI ThreadFunction(void* Arguments);
//Arguments is a void pointer that you can use to pass
//data along to the thread. Let's demonstrate with an
//example...

int NumberToPass = 10;

//The thread function...
DWORD WINAPI ThreadFunction(void* Data)
    {
    if (*((int*)Data) == 10) //Check the passed data...
       { 
       MessageBox(NULL, "This is a message from within "
                  "the thread!", "TheThread", 0);
       }
    }

//Now the code to create the thread.
Thread.Create(ThreadFunction, (void*)(&NumberToPass), TRUE);

//Now do something interesting...
MessageBox(NULL, "This is the rest of the program calling.",
           "TheProgram", 0);

//Now if you ran that code, you would see two message boxes appear
//on the screen at once. Neat, huh?

//Just remember the WINAPI in the declaration and the function -
//if you don't have it, you will end up with some weird errors.

//Now, the only other thing that you might wish to do is to make
//a thread exit without killing it. Just create a global variable,
//make it a bool variable, and set it to FALSE to start off with.
//Then make your thread regularly check it. When you want to stop
//the thread, make the variable TRUE, and the thread should then
//exit (provided that you coded it properly). I would not worry 
//about changing the variable whilst it's being read - only one
//peice of code can be executed at once - so it will either be
//the thread or the program running at any one given time. I can't
//think of any way that the thread and the program can read the
//same location at the same time... except with more than 1 CPU.
Back to indexThe FreeFoote Foundation Classes Documentation