BackgroundQueue

View source
Entity → ceramic.BackgroundQueue (Class)

A thread-safe queue for executing functions serially in a background thread.

BackgroundQueue provides a mechanism to offload work from the main thread while ensuring that queued functions execute one at a time in the order they were scheduled. This is useful for operations that should not block the main thread but need to maintain sequential execution order.

Features

  • Serial Execution: Functions are executed one after another, never in parallel
  • Thread Safety: Safe to schedule functions from any thread
  • Platform Adaptive: Falls back to main thread execution on platforms without threading
  • Automatic Cleanup: Stops background thread when destroyed

Usage Example 

var queue = new BackgroundQueue();

// Schedule work to run in background
queue.schedule(() -> {
    // Perform expensive computation
    var result = processLargeDataSet();
    // Post result back to main thread
    app.onceImmediate(() -> {
        updateUI(result);
    });
});

// Multiple operations execute in order
queue.schedule(() -> loadFile("data1.json"));
queue.schedule(() -> loadFile("data2.json"));
queue.schedule(() -> processAllData());

Platform Support

  • C++/C#: Uses native threading with mutex synchronization
  • JavaScript/Other: Falls back to immediate execution on main thread
See: Runner

Instance Members

checkInterval: Float

Time interval between each checks to see if there is something to run. Lower values provide more responsive execution at the cost of higher CPU usage.

Default: 0.1 seconds (100ms)

schedule(fn: Function): Void

Schedules a function to be executed in the background queue.

Functions are executed in the order they are scheduled, with each function completing before the next one starts. On platforms without threading, the function is executed immediately on the main thread.

Name Type Description
fn Function The function to execute in the background * haxe queue.schedule(() -> { // This runs in background thread var data = loadLargeFile(); processData(data); });
destroy(): Void

Destroys the background queue and stops its thread.

Sets the stop flag which causes the background thread to exit its main loop. Any pending functions that have not yet started will not be executed.

new(?checkInterval: Float = 0.1): Void

Creates a new background queue.

On platforms with threading support (C++/C#), starts a background thread that polls for work at the specified interval.

Name Type Default Description
checkInterval Float 0.1 Time in seconds between queue checks (default: 0.1)

Private Members

runsInBackground: Bool

Whether this queue is running functions in a background thread. False on platforms without threading support.

stop: Bool

Flag to signal the background thread to stop. Set to true when destroy() is called.

pending: Array<Function>

Queue of functions waiting to be executed. Protected by mutex on threaded platforms.

Mutex for thread-safe access to the pending queue. Only available on platforms with threading support.

internalRunInBackground(): Void

The main loop of the background thread.

Continuously checks for pending functions and executes them serially. Sleeps for checkInterval when no work is available to reduce CPU usage.

Platform-specific initialization:

  • Android: Attaches thread to JNI for Java calls
  • C#: Sets thread culture for consistent formatting

Metadata

Name Parameters
:build ceramic.macros.EntityMacro.buildForCompletion()
:autoBuild ceramic.macros.EntityMacro.buildForCompletion()
:build tracker.macros.EventsMacro.build()
:autoBuild tracker.macros.EventsMacro.build()