Object

Thread Class

Threads execute code in the background, independent of the user interface.

Events
Run

Properties
Priority
StackSize
State
ThreadID

Methods
Kill
Resume
Run
Sleep
Suspend

# Notes

By default, a REALbasic application runs in the main thread. This thread is not accessible via methods of the Thread class; it is managed internally. All other threads are accessible and share execution time among each other and the main thread.

Threads are managed by REALbasic's Thread Scheduler. Its task is to allocate the CPU's processing cycles among all of the application's threads. The Priority property determines how many or how few processing cycles the thread gets, relative to the main thread and any other threads that you have created.

When the Thread Scheduler decides to stop execution of the current thread and allow another thread to run, it is called a context switch. The amount of time a thread runs is called the time slice for the thread.

Thread class objects are used to execute code that needs to run independently of the user interface. The Thread Scheduler allocates processing cycles between the main thread and any threads you create via this class.

For example, if you were drawing a complex image that takes several minutes to render, this code could be executed in a thread so that the user could continue using the user interface without having to wait for the rendering to finish.

A thread can be used to allow a very time-consuming loop to run in the background. Since unthreaded loops take over the interface, preventing the user from making menu selections or interacting with a window's controls, this is a good way to allow the user to continue working with the application while a lengthy process is taking place.

Threads yield time to other threads and other applications each time they execute a looping construct such as For, While, and Do.

To create a thread, create a new class and make Thread its super class. Add the new class to the Project. Put the code you wish to execute in the thread's Run event handler. To execute the thread, simply create a new instance of this object and call its Run method. You can do this by adding the instance of the Thread class to a window, as shown in the example, or instantiate it in the usual way.

You instead use the Semaphore, CriticalSection, or Mutex classes to manage access to shared resources among multiple threads. For example, if several threads may need to access the same file, you can use a CriticalSection to be sure that two or more threads are not trying to access the same file simultaneously.

Using the DoEvents method of the Application class from a multithreaded application is not supported and will most likely generate extremely hard to track down errors and crashes in your applications.

# Example

To set up this example, first add a new class to the Project called LongProcessThread and set its Super class to Thread. In the Run event, place the following code:

Dim i as Integer
Dim s as String
Const c = 186000
Const bigNum = 100000000
For i = 1 to bigNum
If i / 1000 = i \ 1000 then
//do something really tedious here...anything you want
s = Str(i/c*c*c) + " for " + Str(bigNum)
//just try to update the interface
Window1.ListBox1.AddRow s //add a row to the ListBox
End if
Next
MsgBox "Finished"

Add an instance of the LongProcessThread class to the default window, Window1. Add a ListBox, ListBox1, to the default window and a PushButton to the window with the following Action event handler:

LongProcessThread1.Run

This event handler does the calculations as a new thread. To see how the user-created thread makes a difference, create a second PushButton in the window and use the code in the Thread's Run event as the PushButton's Action event. When this button is clicked, REALbasic will do the same calculations, but in the main thread rather than in the thread you created.

When you do the calculation in its own thread, you will see that REALbasic is able to update the ListBox while the calculation is in progress and allows the user to manipulate interface items, such as scroll the ListBox and choose menu items. However, when you do the calculation inside the main thread, the interface is locked up until the calculation is finished.

# See Also

Application, CriticalSection, Mutex, Semaphore classes; #Pragma directives; ThreadAlreadyRunningException.