Immediate

A utility class for scheduling callbacks to be executed in a batch.

Immediate provides a simple queuing mechanism where callbacks can be scheduled with push() and then all executed at once with flush(). This pattern is useful for deferring work until a specific point in the application lifecycle, such as at the end of a frame or after a batch of operations.

Key features:

• Efficient callback storage with pre-allocated capacity
• Safe execution that allows new callbacks to be added during flush
• Memory pooling to avoid allocations during flush operations
• Null callback protection

Common use cases:

• Deferring expensive operations until after critical path execution
• Batching multiple updates to avoid redundant calculations
• Implementing a simple event loop or task queue
• Ensuring callbacks run after the current call stack completes

Example usage:

var immediate = new Immediate();

// Schedule some callbacks
immediate.push(() -> trace("First callback"));
immediate.push(() -> trace("Second callback"));

// Later, execute all callbacks
if (immediate.flush()) {
    trace("Callbacks were executed");
}

// Callbacks can add more callbacks during execution
immediate.push(() -> {
    trace("This callback adds another");
    immediate.push(() -> trace("Added during flush"));
});
immediate.flush(); // Both callbacks will execute

Instance Members #

Schedules a callback to be executed when flush() is called.

The callback will be added to the queue and executed in the order it was added (FIFO - First In, First Out). Multiple callbacks can be queued before flushing.

The implementation uses a pre-allocated array that grows as needed, avoiding unnecessary allocations for typical usage patterns.

Executes all queued callbacks and clears the queue.

This method will execute callbacks in the order they were added. If any callback adds new callbacks to the queue (by calling push()), those new callbacks will also be executed in the same flush operation. This continues until no more callbacks remain in the queue.

The implementation uses a temporary array from the pool to safely iterate through callbacks while allowing the queue to be modified during execution.

Creates a new Immediate instance with an empty callback queue.

Private Members #

Array storing the queued callbacks. Pre-allocated for efficiency.

The current allocated capacity of the callbacks array. Used to track when the array needs to grow.

The number of callbacks currently queued. This may be less than the array capacity.