scheduling-utilities

Set of packages for scheduling tasks (debounced or otherwise) in a specific order during a frame.

Use

Scheduler

import { Scheduler } from '@gov.nasa.jpl.honeycomb/scheduling-utilities';

Scheduler.schedule( () => console.log('end of frame!'), 1000 );

Scheduler.scheduleNextFrame( () => console.log('end of next frame!'), 1000 );

Debouncer

import { Debouncer } from '@gov.nasa.jpl.honeycomb/scheduling-utilities';

const debouncer = new Debouncer();
for ( let i = 0; i < 100; i ++ ) {

    debouncer.run( 'task', () => console.log( 'runs once!' ) );

}

// "runs once!" is logged once

JobRunner

API

Constants

BEFORE_ALL_PRIORITY = -Infinity
MOUSE_EVENT_PRIORITY = 1000
RENDER_PRIORITY = 2000
UI_UPDATE_PRIORITY = 3000
AFTER_ALL_PRIORITY = Infinity

Functions

enqueueMicrotask

enqueueMicrotask( func : Function ) : void

Enqueues a function to be run after everything this frame but before the start of the next frame using Promise.resolve.

See this document on microtasks.

Debouncer

Reusable class instance for defining, tracking, and flushing tasks that are debounced to run at the end of frame. Uses Scheduler to schedule tasks.

run

run( name : String, func : Function, priority : Number = 0 ) : void

Creates a task to be run at the end of frame with the unique key name. If a task with the given name is already scheduled it will be cancelled in favor of the new one.

Priority corresponds to the priority concept used in Scheduler.

flush

flush( name : String ) : Boolean

Flushes the task with the given name and runs it now.

Returns true of the task existed.

flushAll

flushAll(  ) : void

Flushes every scheduled task.

cancel

cancel( name : String ) : Boolean

Cancels the task with the given name.

Returns true of the task existed.

cancelAll

cancelAll(  ) : void

Cancels every scheduled task.

JobRunner

Utility for enqueing an optionally cancelable, asynchronous task that you only want to perform a few of at a time, such as file reads, http requests, etc. Only a certain number of jobs will be actively running at once. Once a job completes more will start.

maxJobs

maxJobs : Number = 10

The maximum number of jobs that can be run at once.

run

run( func : Function, cancel : Function = null ) : Promise

Enqueues a task to be run. If there are fewer then maxJobs running then the task will be run immediately. The returned promise includes a cancel function on it which can be used to remove the task from the job queue. If a task is cancelled then the cancel callback passed into the function will be called only if the task has already begun running.

Coroutine

Class for running a coroutine over multiple frames using a generator.

running

running : Boolean

Getter indicating whether or not the coroutine is currently running.

priority

priority : Number = 0

Field indicating the order to run the task with in the scheduler. Smaller numbers are run first.

constructor

constructor( task : Generator, cancel : Function | null = null ) : void

Takes a generator function "task" to run over multiple frames and an optional "cancel" function which will run if the coroutine is cancelled mid run.

run

run( args : ...any ) : void

Runs the coroutine. Any arguments passed to this function are passed into the task function. Throws an error if a task is already runninig.

cancel

cancel(  ) : Boolean

Cancels the current running task if there is one and returns true if a task was running.

CancellablePromiseTask

cancel

cancel : Function

Cancel the current ask and remove it from the queue so it's not run.

flush

flush : Function

Run the task now and remove it from the queue.

Scheduler

Class for scheduling events with a priority order before the end of the frame. If the queue of events has already been run this frame they are scheduled for the next frame. A singleton of this class is exported as Scheduler from the package.

The Scheduler runs a consistent loop in the background that runs tasks every frame or every 500ms, which ever comes first.

flush

flush(  ) : void

Run all tasks in the queue.

schedule

schedule( func : Function, priority : Number = 0 ) : CancellablePromiseTask

Schedules a task to be run when the next flush of tasks is scheduled to run, which is often at the end of the current frame. If they cannot be run at the end of the current frame or the queue of tasks has already been flushed then the task will be run next frame.

Priority indicates the order in which functions will get run. So a task with a priority of 0 will get run first while one with a priority of 100 will get run last. If a called task adds a callback to the queue it will get added and run to the queue that is currently being flushed, meaning it will get called before the current frame ends.

scheduleNextFrame

scheduleNextFrame( func : Function, priority : Number = 0 ) : CancellablePromiseTask

Like schedule but queues a task to get run next frame along with other tasks that need to get run.