But timers have a limit: they still run on the UI thread. If your background work is genuinely heavy (database queries, file I/O, complex calculations), a timer won’t save you. You need actual background processing and that’s where threads come in.

The Core Idea: Threads

A thread is a separate execution path that runs outside the UI thread. While your thread does the heavy lifting, the UI stays responsive to clicks, typing, scrolling. When your thread finishes a chunk of work, it notifies the UI thread via UserInterfaceUpdate, and only that callback runs on the main thread.

The rule is simple: threads cannot touch UI controls directly. If you try, you get a crash. UserInterfaceUpdate is your bridge.

For a deeper dive into how Xojo’s threading model works under the hood, including cooperative vs. preemptive threading, see Cooperative to Preemptive: Weaving New Threads Into Your Apps.

Let’s Code

Prerequisites: Add a StatusLabel (DesktopLabel), a DesktopButton, and a Thread control. Also define:

kCountTo As Integer = 100

The Thread Control

Drag a Thread from the library into your window and name it BackgroundWorker.

The Button (Start the Thread)

Place this in the Pressed event of a button:

Sub Pressed()
  If BackgroundWorker.ThreadState = Thread.ThreadStates.NotRunning Then
    BackgroundWorker.Start
  End If
End Sub

This checks if the thread is already running. If not, start it. This prevents multiple threads from piling up if someone clicks fast.

The Thread.Run Method (Background Work)

Implement the Run method on your Thread:

Sub Run()
  For i As Integer = 0 To kCountTo
    
    ' Do background work here. No UI access allowed.
    ' It can be: database query, file read, API call, pretty much anything that might block "freeze" the UI of the app
    
    ' Prepare a Dictionary payload for the UI
    Var info As New Dictionary
    info.Value("progress") = i
    info.Value("message") = "working"
    Me.AddUserInterfaceUpdate(info)
    
    ' Sleep (optional)
    Thread.SleepCurrent(10)   // Sleep 10 ms
  Next
End Sub

The key line is Me.AddUserInterfaceUpdate(info). This queues data for the UI thread to process. Each call adds one item to a queue, and the UI thread drains it in UserInterfaceUpdate.

The Thread.UserInterfaceUpdate Method (UI Sync)

Implement this event to handle updates from the thread:

Sub UserInterfaceUpdate(data() As Dictionary)
  ' Runs on the main UI thread. Safe to update controls here.
  
  ' Guard against empty or malformed data
  If data = Nil Or data.Count < 0 Then Return
  
  Var d As Dictionary = data(0)
  
  ' Extract the progress value safely
  Var progress As Integer = 0
  If d.HasKey("progress") Then
    progress = d.Value("progress").IntegerValue
  End If
  
  ' Update the UI
  StatusLabel.Text = progress.ToString
  
  ' Mark completion when we hit the target
  If progress >= kCountTo Then
    StatusLabel.Text = "done"
  End If
End Sub

Important notes:

• data() is an array of Dictionaries.
• Always check HasKey before accessing a value to avoid runtime errors.
• Use .IntegerValue (or .StringValue, etc.) to safely extract values.
• This runs on the UI thread, so it is safe to update StatusLabel and any other visual controls.

How It Works

1. Button press: Click the button and the thread starts.
2. Background loop: The thread iterates from 0 to kCountTo, sleeping 10 ms each step. After each step, it queues an update.
3. Responsiveness: While the thread works, you can still interact with the rest of your application. No freezing.

A Note on Thread Safety

Threads are powerful but risky if misused. Here is the boundary:

• Safe in Run(): Anything that doesn’t touch UI controls. File I/O, database queries, calculations, network calls.
• Unsafe in Run(): Reading or writing UI control properties directly. StatusLabel.Text = ... is a no no!
• Safe in UserInterfaceUpdate(): All UI control access. This runs on the main thread.

If you forget this rule and try to update a label from inside Run(), your app will crash with a ThreadAccessingUIException. Instead pass data through AddUserInterfaceUpdate.

When to Use Threads vs. Timers

Use timers for:

• Short, frequent tasks (10-50 ms ticks).
• Simple progress updates.
• Cases where you are just deferring work a bit.

Use threads for:

• Long-running operations (seconds, minutes, hours).
• Genuinely blocking work (I/O, network, heavy calculations).
• Multiple independent background tasks.

In this series, we moved from blocking the UI to using timers on the UI thread, then to actual background threads. Each approach solves a different problem.

Wrapping Up

Threads are the heavy artillery of responsive design. They run independent of the UI and communicate safely via UserInterfaceUpdate. Once you grasp the boundary between thread code and UI code, you can build applications that never freeze, no matter how much work is happening behind the scenes.

See the Thread documentation for more details on priority, stack size, and advanced patterns.

Until then, happy threading!

Gabriel is a digital marketing enthusiast who loves coding with Xojo to create cool software tools for any platform. He is always eager to learn and share new ideas!

• Facebook
• X
• LinkedIn
• GitHub
• YouTube

Optimizing Code Series:

• Optimizing Xojo Code, Part 1: Getting Started
• Optimizing Xojo Code, Part 2: Using a Timer to Keep the UI Responsive
• Optimizing Xojo Code, Part 3: Programmatic Timers and AddHandler
• Optimizing Xojo Code, Part 4: Timer.CallLater
• Optimizing Xojo Code, Part 5: Threads and UserInterfaceUpdate

In The Beginning

Threads have been a part of of the Xojo language for a long time, and by now experienced users know the basics: subclass a Thread, fill in the Run event, then call Start. The code in Run will execute independently from the rest of your code leaving your app responsive while it does work in the background.

Mostly.

See, until now, a Thread was only “cooperative”, meaning it ran alongside your main code with the framework deciding when to switch between them and how long each should execute. While the main code was running, the Thread code was paused, and while the Thread was running, the main code was paused.

Think of it like standing before two devices that perform different functions when cranked, but only having one crank available. You run the first machine for a bit, then the other, then back to the first, until they are done. And you do it really, really fast.

This worked pretty well when your goal was, say, to keep your user interface responsive. You could spin long-running code into a Thread, then present the results once it finished.

But it was inadequate if your objective was to speed up some intense process, or the code in your Thread did not present logical places to yield time back to your main code. In the former scenario, you were better off not using a Thread, or perhaps using Worker (a severely limited earlier attempt at allowing simultaneous processing), while in the latter you would have to manually yield back processing time, leading to even slower operation.

In The Now

Cooperative threads are fine for many tasks, but when you need something that truly runs independently within your app, a “preemptive” thread is required.

A preemptive thread spins off onto another core in your machine, which probably has at least four, and runs there entirely isolated from other threads. It’s like launching a separate, mini-app that you can share information with.

The limitations that apply to cooperative threads drop away. Since it runs on a different core, it cannot slow down or interfere with your main code, and will run as fast as its core will allow.

Challenging Times

This sounds almost too good to be true, but it’s not without its challenges. While cooperative threads were rather easy to work with, preemptive threads require an extra layer of thought and awareness for Xojo users.

When a cooperative thread’s code is running, you know nothing else is, so you don’t have to worry about, say, updating a Dictionary or removing an element from an array. But with preemptive threads, code runs simultaneously with other code so you cannot just update that Dictionary if there is a chance that the main code, or another preemptive thread, might be doing it too.

Consider this example.

// In our thread
If MyArray.Count = 0 And FinishUp Then
  Exit
Else
  Process MyArray.Pop
End If

//////////////////////////////

// In the main code
FinishUp = True
MyArray.Add 1

You might think the thread is going to process the last element and then exit its loop because FinishUp was set to True, but with preemptive threads we have to be aware of race conditions where the order of actions is unpredictable. Here, the main code could set FinishUp to True, and the thread could see that MyArray was empty and exit before the main code could add the last element. Conditions can change at literally any instant, even in the middle of a single line of code.

Fortunately, there are ways to protect against this and you must use them to ensure orderly operation and avoid surprises.

Know Your Type

The first step is creating a preemptive thread, and Xojo’s implementation is pretty straightforward. Rather than introducing a unique class, you can continue to work with the existing Thread by setting its new Type property to Thread.Types.Preemptive. The Type can be set when instantiating the Thread or from within its running code. You can even switch types at will, although once running, the Type can only be changed from within the Thread.

Example:

// A subclass of Thread called PThread

MyThread = New PThread
PThread.Type = Thread.Types.Preemptive
PThread.Start

Or within the Run event, you could do this:

Me.Type = Thread.Types.Preemptive

You can also set Type through the Inspector after dragging a Thread to a window.

Protect Yourself

Now that you have a preemptive thread ready to go, you have to think about how to protect common resources. Xojo has done a good job of making a lot of the framework safe, but that just means your app shouldn’t crash if, say, the Thread tries to manipulate a variable at the same time as other code. It’s up to you to make sure one area of your app doesn’t clobber the changes made by another.

Consider this code that maintains a Dictionary of Integer arrays.

// Thread code
Var arr() As Integer

If MyDictionary.HasKey(x) Then
  arr = MyDictionary.Value(x)
Else
  MyDictionary.Value(x) = arr
End If

arr.Add 1

//////////////////////////////

// Main code
If Not MyDictionary.HasKey(x) Then
  Var arr() As Integer
  MyDictionary.Value(x) = arr
End If

Run this long enough and you’re going to wonder why some data got lost. Why? Because both the Thread and main code might be checking for the key at the exact same instant and filling it in when it’s not found. If the Thread does it first, the main code will almost instantly replace it with an empty array.

Instead, you should use a Semaphore or CriticalSection to make sure code is protected.

You’d first instantiate one of these in a common property like a Window or Module. (I’m using Semaphore here, but it works the same for CriticalSection.)

MySemaphore = New Semaphore
MySemaphore.Type = Thread.Types.Preemptive

Notice the new Type property? It must match the one in Thread and can be used between the main code and a Thread or between same-typed threads. (This is one of the limitations of Xojo’s implementation: you cannot share a Semaphore or CriticalSection between preemptive and cooperative threads.)

The example can be updated like this:

// Thread code
Var arr() As Integer

MySemaphore.Signal

If MyDictionary.HasKey(x) Then
  arr = MyDictionary.Value(x)
Else
  MyDictionary.Value(x) = arr
End If

MySemaphore.Release

arr.Add 1

//////////////////////////////

// Main code
MySemaphore.Signal

If Not MyDictionary.HasKey(x) Then
  Var arr() As Integer
  MyDictionary.Value(x) = arr
End If

MySemaphore.Release

This will force either the main code or Thread to wait for the other to complete before continuing, ensuring proper order and avoiding the race condition.

Limitations

Using preemptive threads comes with certain restrictions. The biggest one is the aforementioned inability to share a Semaphore or CriticalSection with a cooperative thread. The other is the same as in a cooperative thread: you cannot update a user interface component directly instead relying on the UserInterfaceUpdate mechanism (more on that below).

If you are setting up multiple threads to work on different parts of some object, that may crash hard depending on the type of object. For example, writing to the same file or different parts of a MemoryBlock is fine, but updating a Picture may not be. In those cases, you will have to get creative.

What’s It Good For?

Choosing preemptive threads over cooperative means that you either have some code that needs to truly run in the background that would otherwise interfere with you user interface, or you have some large task that can be logically processed in parts.

Window Service

In the former case, the easiest technique might be to drag a Thread to your window, set its Type, and implement the Run event. It can be started from within the window either through a manual process like a pressing a button, or automatically when the window opens.

Just like with a cooperative thread, you can send data back to your window using the AddUserInterfaceUpdate method and implementing the UserInterfaceUpdate event.

Splitting It Up

If your task involves something that can be split up into logical chunks, I encourage you to look at my ThreadPool module, accessible through the Xojo Examples or my GitHub page. (The latter has a README with more details.)

The ideal usage for ThreadPool is when you have some data that can be processed in sections. For example, suppose you wanted to count the vowels in a large file. You could subclass ThreadPool and implement its Process event to count one block. You would then send the file into your subclass in chunks of, say, 256k each and gather the results.

The benefit of ThreadPool, among other things, is that it will handle the coordination for you so the dangers of using preemptive threads are minimized. You still have to consider how to send your results back to your main code safely, perhaps using Semaphore/CriticalSection or the AddUserInterfaceUpdate method, but each block can be considered independently of the others.

(A big thanks to MVP Anthony Cyphers for writing the example included with Xojo.)

Juggling Chainsaws

The power of preemptive threads is clear, but the potential pitfalls can be serious. Unless you’re very careful, you can easily create bugs that may not be readily apparent, and may take hours or even days to track down. (I say this from unfortunate experience.) Unless you have a compelling reason to take on that challenge, don’t bother.

What I’m trying to say is, if a cooperate thread does the job adequately, there is no need to introduce the headache that preemptive threads can bring.

But if you do have a legitimate need, like a long-running process that needs to run quickly without blocking your UI, go for it, just be careful.

In any case, it’s great that we finally have that option.

Kem Tekinay is a Mac consultant and programmer who has been using Xojo since its first release to create custom solutions for clients. He is the author of the popular utilities TFTP Client and RegExRX (both written with Xojo) and lives in Connecticut with his wife Lisa, and their cat.

Need More Information? Read more about preemptive threads in the Xojo Documentation and Blog. Or read about Semaphore and CriticalSection, also on the Xojo Blog.

Threading Models

Cooperative Threads: This is the threading model that Xojo has traditionally supported and continues to offer. In this model, threads must voluntarily yield control at specific points that we define. This ensures that most operations in Xojo code are thread-safe, as we manage access to MemoryBlocks, Arrays, etc. However, this approach can lead to inefficiencies if a thread fails to yield, potentially blocking UI, and because only one thread runs at a time, it doesn’t fully utilize multiple cores or truly run in parallel.

Preemptive Threads: Introduced in Xojo 2024r3, this new thread type allows threads to be interrupted at any point, enhancing responsiveness and fully utilizing multiple cores. While this model provides significant performance improvements, it also introduces new challenges. Because threads can be interrupted at any time, you’ll need to be more diligent about locking resources, such as MemoryBlocks and Arrays, to avoid potential race conditions.

Using Preemptive Threads

We’ve added a new Thread.Type property that allows you to switch your threads to the new preemptive thread model, here’s how you can start one up:

Thread1.Type = Threads.Types.Preemptive
Thread1.Start

You can set this property either before starting your thread or while the thread is running. However, if changing it while the thread is active, it must be done safely from within the running thread itself, and not externally.

Event Window1.Opening
  // Start the thread and setup the type in the Run event instead
  Thread1.Start
End Event

Sub Thread1.Run
  Me.Type = Threads.Types.Preemptive
  // Run a very long process preemptively.
  newMemBlock = memBlock.Compress
  
  Me.Type = Threads.Types.Cooperative
  // Switching to cooperative mode and modifying a shared array safely.
  mySharedArray.Add("New item")
End Sub

Concurrency and Synchronization

As mentioned earlier, cooperative threads avoid many of the issues that arise with preemptive threads, since we control when thread switching occurs. With preemptive threads, however, you can no longer safely modify things, like shared arrays, the same way you could before with cooperative threads. To manage this, you’ll need to use tools like CriticalSections and Semaphores more frequently to protect your shared resources.

The challenge lies in efficiently supporting both threading models while enabling the main thread to synchronize with either type. To address this, we’ve added a new Type property to CriticalSection and Semaphores, which must match the thread type you’re using to protect shared resources.

// Imagine the main thread and two additional threads all trying to access a Dictionary simultaneously.
Sub RunTest
  Thread1.Type = Thread.Types.Preemptive
  Thread2.Type = Thread.Types.Preemptive

  CSLock = New CriticalSection
  // Since we are using this CriticalSection in preemptive threads,
  // the synchronization type must be compatible.
  CSLock.Type = Thread1.Type

  Thread1.Start
  Thread2.Start

  Do
    CSLock.Enter
    MyDictionary.RemoveAll
    CSLock.Leave
  Loop
End Sub

Sub Thread1.Run
  Do
    CSLock.Enter
    MyDictionary.Value("Random1") = Rnd
    CSLock.Leave
  Loop
End Sub

Sub Thread2.Run
  Do
    CSLock.Enter
    MyDictionary.Value("Random2") = Rnd
    CSLock.Leave
  Loop
End Sub

What things are thread-safe?

We’ve updated our framework to safeguard areas that were previously not preemptive thread-safe. For the most part, our entire framework is now safe for concurrent use with preemptive threads, with a few exceptions like XojoScript and Runtime.IterateObjects. When sharing resources such as MemoryBlocks, Dictionaries, or Arrays among threads, you may need to use CriticalSections or Semaphores to ensure safe access. However, if you’re only reading from these resources without modifying them, synchronization is not required. You’ll be happy to know that calling Thread.AddUserInterfaceUpdate from a preemptive thread is also safe.

Performance Considerations

With the ability to switch your threads to preemptive, there are some performance factors to consider. While running 100 threads at once might seem appealing, it often leads to over-utilizing your system’s resources. For optimal efficiency, it’s best to limit the number of threads to match the number of available cores. To assist with this, we’ve introduced the new System.CoreCount, which helps you determine the number of cores on your system.

While Xojo’s framework doesn’t shield you from every potential issue, we do handle synchronization for key operations like object creation and destruction. However, you may notice these actions are slower in preemptive threads due to the extra synchronization required.

Usage and Examples

There’s no question that preemptive threads offer significant advantages, and when used correctly, they can greatly enhance your app’s performance. Check out our threading example projects included with the 2024r3 release to see preemptive threads in action and enjoy weaving these new threads into your future apps!

A special thanks to our MVPs for their invaluable help in refining and testing this new feature! Be sure to check out the new ThreadPool example for some practical, real-world use cases and read MVP Kem Tekinay’s blog post Preemptive Threads Are Here and They Are …. Pretty Good.

Need More Information? Read more about preemptive threads in the Xojo Documentation and Blog. Or read about Semaphore and CriticalSection.

William Yu grew up in Canada learning to program BASIC on a Vic-20. He is Xojo’s resident Windows and Linux engineer, among his many other skills. Some may say he has joined the dark side here in the USA, but he will always be a Canadian at heart.

• Facebook
• X
• LinkedIn
• GitHub
• YouTube

Threading is a great solution to these situations. Threading ensures that the code of operations with long working duration keeps doing its job while acting on the UI still possible: it could be clicking on some buttons, writing some text in a textfield or even opening a file dialogue. 

Typically we also need to think about a way to show users that something is working in the background. A common way to do this is filling a progress bar. Or maybe changing the text of a label that shows the current status. Of course, there are other possibilities depending of the creativity of the developer. 

As we know, using multiple threads allows running a few tasks on the same program. In Xojo, your code runs in default on the main thread. So if you want to run other code in a second thread, you need to drag and drop the thread class to your project just like any other class from the library to create a new instance of it. 

There you have two events: The Run event helps to run the task which could take some time to finish. The UserInterfaceUpdate event is like the name says, responsible for any change on the users interface. Both events work hand in hand since for any update we usually need some values delivered from our code under the run Event. The connecting point between both events is the method AddUserInterfaceUpdate. It helps us to prepare key:value pairs which we could need for any sort of interaction with a user or with our self when we catch exceptions.

The Event UserInterfaceUpdate receives all those pairs as an array of dictionaries. It makes looping over the data and fetching the desired value with the right key much simpler and adaptable to any kind of logic. 

Watch this video to watch me implement a thread to output to a log file:

Now I hope you have a basic understanding of how threads work in Xojo and how they could be useful for your projects in the future.

Mohamed Braham is 34 years old and works as an IT Developer. He specializes in developing desktop applications with Xojo and solving issues in the commercial field. Originally an automotive engineer with many years experience of industrial projects, he discovered a passion for programming in 2020 and is self-taught. In his freetime he likes making videos on his YouTube Channel: Braham Creation 2 go where he publishes tutorial videos about Xojo. As a self-taught programmer, he values finding good help online for free and wants to give a little back and share his knowledge with the Xojo community.