Runner

Cross-platform thread management utility for executing code on main and background threads.

Runner provides a simple interface for thread management in Ceramic, supporting both platforms with native threading (C++/C#) and single-threaded environments (JS/Web). It ensures safe execution of code on the main thread from background threads and vice versa.

Key features:

• Main thread callback execution from background threads
• Background thread creation on supported platforms
• Graceful fallback to deferred execution on single-threaded platforms
• Thread-safe queue for main thread callbacks

Platform behavior:

• C++/C#: Full threading support with real background threads
• JS/Web: Emulates background execution using immediate callbacks

Usage example:

// Initialize on app start (main thread)
Runner.init();

// In your main loop
Runner.tick();

// Run heavy computation in background
Runner.runInBackground(() -> {
    var result = performHeavyCalculation();
    // Update UI on main thread
    Runner.runInMain(() -> {
        updateUI(result);
    });
});

Static Members #

Checks if the current thread is the main thread.

This method is useful for determining execution context and ensuring thread-safe operations. On single-threaded platforms, this always returns true.

Checks if background execution is emulated on the current platform.

Some platforms (like JavaScript/Web) don't support true threading, so background execution is emulated using deferred callbacks on the main thread. This method helps code adapt to platform capabilities.

Schedules a function to run on the main thread.

This method queues the given function for execution on the main thread. The function will be executed during the next tick() call. This is particularly useful for updating UI or accessing main-thread-only resources from background threads.

The call is non-blocking and doesn't wait for the function to complete.

Example:

Runner.runInMain(() -> {
    myVisual.alpha = 0.5; // Safe UI update
});

Executes a function on a background thread.

On platforms with threading support (C++/C#), this creates a new thread to execute the function. On single-threaded platforms (JS/Web), the function is scheduled for deferred execution on the main thread.

This is useful for offloading heavy computations or I/O operations without blocking the main thread.

Example:

Runner.runInBackground(() -> {
    // Heavy computation
    var data = processLargeDataset();
    // Return result to main thread
    Runner.runInMain(() -> {
        handleProcessedData(data);
    });
});

Private Members #

Reference to the main thread. Set during initialization to identify the primary thread for callback execution.

Thread-safe queue for storing callbacks to be executed on the main thread. Background threads push callbacks here, and the main thread processes them during tick().