Claude-Tools-for-Delphi: Skill for Claude Code

Delphi threading — reference

Load before writing or reviewing any code that runs off the main thread. Threading is RTL/PPL territory — LightSaber has no multithreading helpers, so do not go looking for one.

Units: TThread — System.Classes · TTask/TParallel/IFuture<T> — System.Threading · TCriticalSection/TEvent/TInterlocked/TLightweightMREW — System.SyncObjs · TThreadList<T>/TThreadedQueue<T> — System.Generics.Collections · TMonitor — System (no uses entry needed).

The one rule that is never optional

A worker thread must never touch a visual control or the UI directly. This holds on VCL and on FMX (Android/iOS included). Marshal every UI update back to the main thread with TThread.Synchronize (blocking) or TThread.Queue (non-blocking).

// WRONG - crash or corruption
TThread.CreateAnonymousThread(procedure begin lblStatus.Text := 'Working'; end).Start;

// RIGHT
TThread.CreateAnonymousThread(
  procedure
  begin
    TThread.Queue(nil, procedure begin lblStatus.Text := 'Working'; end);
  end).Start;

Lifetime — VCL & FMX: a queued/synchronized closure runs later on the main thread; if the form or control it touches was freed meanwhile, you get a dangling access. This is not mobile-only — a VCL form closed while a worker still runs hits it too. It just fires far more often on mobile, where the OS backgrounds the app and tears down views on its own. Assigned does not save you: a freed object is still non-nil, so Assigned(Form) returns True and you crash anyway. Fixes, in order:

1. Stop the worker before its target is freed. In the form's OnClose/destructor just Free the thread: TThread.Destroy itself calls Terminate, waits for Execute to finish, then purges the thread's pending queued closures via RemoveQueuedEvents(Self) (System.Classes.pas, ShutdownThread). Calling WaitFor/Free from the main thread cannot deadlock on a worker sitting in Synchronize — main-thread WaitFor pumps the synchronize queue while it waits (TThread.WaitFor, both Windows and POSIX branches). Requires FreeOnTerminate = False (see pitfall below).
2. Queue against the thread instance, not nil, when the target's lifetime is uncertain. Inside a TThread subclass simply call the instance Queue(...) — it forwards to Queue(Self, ...). Destroying that thread then purges its pending closures; TThread.Queue(nil, ...) has no such safety net. nil is fine only when the closure touches nothing that can die before it runs.