TH · Threading & Concurrency

The engine has several long-lived threads plus per-task workers. Putting code on the wrong thread causes UI hitches (long blocking work on main), torn data (unsynchronised cross-thread access), or silent failures (ImGui calls off-main). This page lists every thread context, what's allowed on it, and how to bounce between them.

Quick reference

Detection helpers

• Application::IsMainThread() — global check. Use in HZ_CORE_ASSERT(Application::IsMainThread()) to enforce a function is main-thread only, or HZ_CORE_ASSERT(!Application::IsMainThread()) to enforce it isn't (the worker family uses this).
• MainThreadDispatcher::IsMainThread() — equivalent for editor code in LuckyEditor/src/Agent/MainThreadDispatcher.h.

Both record the main thread's std::thread::id at startup. If neither has been initialised yet, the check returns false — so don't rely on these before the engine has booted.

Main thread

Owns: GLFW / OS window, NVRHI device + command lists, ImGui context, the active Scene, the active Project, the asset registry. Runs Application::Run, which pumps OS events, calls each layer's OnUpdate / OnImGuiRender / OnEvent, drives TimeManager::Tick, and presents the frame.

Symptoms of a violation: UI freezes during the operation, glfwSwapBuffers reports late frames, the editor stops responding to input until the work finishes.

Editor vs. runtime threading

Renderer::Submit(lambda) in either mode pushes the lambda into the global RenderCommandQueue. The queue is drained on whichever thread plays the "render thread" role for that mode:

• In the editor (SingleThreaded), the main thread itself drains the queue at the end of the application frame, before swap. The lambda runs synchronously, just deferred until the queue-drain point.
• In the runtime (MultiThreaded), the dedicated render thread drains the queue during its WaitAndRender cycle while the main thread starts on the next simulation tick.

When you genuinely need the render-thread-vs-main distinction (i.e. you're writing code that ships in the runtime and needs correctness guarantees there), use Renderer::Submit for the GPU work and use main-thread state synchronisation only for the runtime build. The editor will run the same code correctly because submission collapses to a same-thread deferral.

TimeManager runners

The engine's deterministic execution model. Header: Hazel/src/Hazel/Core/TimeManager.h. Five fixed phases (executed in order at each runner's frequency) + two free phases (refresh-rate-based).

Modes

TimeManager::Mode — three execution policies:

• RealtimeNonDeterministic — keep wall-clock pace; drop ticks if overloaded. UI / sim default during interactive editing.
• LowPerformanceDeterministic — never drop ticks; may run slower than real time when overloaded; capped at 1× speed.
• HighPerformanceDeterministic — never drop ticks; run as fast as the hardware permits. The headless / training mode.

The mode determines whether long work in a runner is acceptable: in RealtimeNonDeterministic, a slow Physics runner causes dropped ticks; in HighPerformanceDeterministic, the whole simulation just slows down.

Registration

• Fixed-rate work: TimeManager::RegisterWithRunner(registration) or RegisterWithRunnerID(registration). Pick a phase from the table above; pick a frequency that matches the work (typically 500 Hz physics, 100 Hz control, 30 Hz recording — never assume 60 Hz).
• Free-rate work: TimeManager::RegisterFreeUpdate(callback, FreePhaseID::PostExport) (or PreAcquisition).

Thread placement

In the current implementation, TimeManager::Tick runs on the main thread (called from Application::Run). Runners therefore execute on the main thread, in serial within a tick. This is an implementation detail that can change — write runners as if they may run on a dedicated thread later:

• Don't touch ImGui from a runner.
• Don't assume you can read Scene mutations made by another runner in the same phase; cross-runner data flow goes through the StepContext or explicit shared state with synchronisation.
• Allocate per-tick budget; don't accumulate work in a runner that grows unbounded across ticks.

std::jthread workers — one-shot bg jobs

Pattern: a class owns a std::jthread m_Worker declared last (so the destructor joins before other members are destroyed). The worker calls into a private RunBackground(std::stop_token st) method. State is exchanged via atomics / a shared_ptr<Progress> protected by a mutex.

Existing instances — don't add new bespoke threading patterns; extend or copy these:

• ImportProjectJob — extracts a project zip, renames, patches identity. LuckyEditor/src/Utilities/Content/ImportProjectJob.{h,cpp}.
• ExportProjectJob — zips a project, applies export filters.
• CreateProjectFromTemplateJob — downloads a vault project, instantiates as new project, optionally installs a robot pack.
• SaveProjectAsJob — copies a project to a new location with patched identity.
• EpisodeReportStreamer — streams episode reports to LuckyHub.
• ContentVaultSystem — heavy-op slot guarded by HeavyOpGuard; only one bg vault job at a time.
• EditorAssetSystem — async asset import worker.

gRPC server thread

The gRPC server (configured in LuckyEditor/src/Panels/GrpcPanel and friends) runs its handlers on gRPC's own pool — a different thread from the engine main loop.

• RPC handlers don't directly mutate Scene or EditorAssetManager. They go through the GrpcStepSystem / GrpcCapturePool which marshals work to the engine's main loop at safe checkpoints (typically the Acquisition or Validation phase).
• gRPC handlers may capture state from a recent simulation tick (e.g. via GrpcStepCapture) but must not block waiting for a future tick under the main thread.

If you're adding a new RPC: don't reach into engine state from the handler. Add a marshalling step and read from the capture / snapshot the engine produces per tick. See gRPC / Cross-System for the full service surface.

File watchers

m_ScriptFileWatcher in EditorLayer.cpp uses filewatch::FileWatch<WatcherString> to detect script-DLL rebuilds. The watcher callback runs on filewatch's own thread.

• The callback only sets a flag (m_ShouldReloadCSharp = true) — it does not perform the reload.
• The reload happens in OnUpdate on the main thread, after observing the flag.

When adding a new file watcher: follow the same pattern. Watcher thread sets a flag; main thread polls and acts.

AuthService

Hazel::AuthService (singleton, Hazel/src/Hazel/Auth/AuthService.{h,cpp}) handles the OAuth login flow. The browser callback comes back to a local HTTP listener running on a worker thread. The main thread observes auth state via AuthService::Get().GetState() (AuthState::PendingCallback, Authenticated, etc.).

• UI code (SimpleUXWelcome's Login button) reads state on the main thread.
• The login worker writes state under the service's internal mutex.
• When auth completes, the worker sets the new state and the main thread picks it up next frame.

Bouncing between threads

Background → main: MainThreadDispatcher

Header: LuckyEditor/src/Agent/MainThreadDispatcher.h.

// From a background thread, run something on the main thread and wait for the result.
std::string result = MainThreadDispatcher::Execute([]() {
    return DoMainThreadOnlyWork();
});

// From a background thread, fire-and-forget a main-thread operation.
MainThreadDispatcher::ExecuteAsync([]() {
    MutateSomething();
});

MainThreadDispatcher::ProcessPendingOperations() drains the queue. It's already wired into EditorLayer::OnUpdate — don't call it from anywhere else.

Background → main: scoped pattern (preferred for jobs)

Workers that have a clear completion event don't need MainThreadDispatcher. They:

1. Compute results on the worker thread.
2. Set m_Done (release) when finished.
3. Main thread polls IsDone() each frame in OnUpdate.
4. Main thread calls TakeResult() and acts on the outcome.

This is what CreateProjectFromTemplateFlow::OnUpdate does — see LuckyEditor/src/Popups/CreateProjectFromTemplateFlow.cpp.

Main → background: just spawn a job

Use the *Job::Start(...) static factory pattern. The job allocates itself, validates inputs synchronously, launches the jthread, and returns a Scope<...> the main thread owns. Don't manually create std::thread / std::jthread for one-off work — use the job pattern.

Synchronisation primitives

• std::atomic<T> for single-value flags / counters where no other state needs to be coordinated.
• std::mutex + std::scoped_lock for compound state. Don't roll your own spinlock.
• std::shared_mutex if read-heavy and contention matters.
• std::stop_token / std::stop_source for cancellation. Don't use a custom bool flag.

Locks should be held for the minimum time. If you find yourself holding a lock across an I/O call, restructure: copy the data out under the lock, do the I/O unlocked, then re-acquire to write back.

When you're not sure

If you can't figure out which thread a piece of code runs on, walk up the call graph until you hit one of:

• Application::Run / OnUpdate / OnImGuiRender / OnEvent → main thread.
• A std::jthread constructor or Job::Start → that worker.
• TimeManager::Tick → currently main, but treat as if it could move.
• A gRPC handler entry point → gRPC pool.
• A filewatch::FileWatch callback → file watcher thread.

If you still can't tell, add HZ_CORE_ASSERT(Application::IsMainThread()) (or !IsMainThread) and run the editor — the assert tells you on the first frame.