JSDoc: Class: module:caplin/core/scheduler/ThreadScheduler

Class: module:caplin/core/scheduler/ThreadScheduler

module:caplin/core/scheduler/ThreadScheduler

Constructor

new module:caplin/core/scheduler/ThreadScheduler()

Class used to improve the behaviour of applications on highly saturated machines.

When the browser becomes over saturated due to the rate of updates it receives, two problems can appear which are detrimental to the use of the browser as a real-time trading platform. These are:

It's possible for UI events to get queued behind timer & interval events, decreasing the responsiveness of the application to user input.
It's possible that the screen is not immediately refreshed when new updates are written to it — this can not happen until all pending JavaScript has been executed.

Members

UI_EVENT_YIELD_TIME

The time soon after which the thread scheduler will yield control so that any pending UI events can be processed.

Methods

addThreadQueueListener(oListener)

Add a listener to be informed of updates to the current number of pending and due threads awaiting processing

Parameters:

Name	Type	Description
`oListener`	module:caplin/core/scheduler/ThreadQueueListener	The object that will receive the call-back events.

clearInterval(nIntervalId)

A replacement for the native window.clearInterval() method.

This method replaces, and has the same API as window.clearInterval() — i.e. invoking window.clearInterval() actually causes this method to be invoked.

Parameters:

Name	Type	Description
`nIntervalId`	int	The id of the previously registered interval you wish to cancel.

clearTimeout(nTimeoutId)

A replacement for the native window.clearTimeout() method.

This method replaces, and has the same API as window.clearTimeout() — i.e. invoking window.clearTimeout() actually causes this method to be invoked.

Parameters:

Name	Type	Description
`nTimeoutId`	int	The id of the previously registered timeout you wish to cancel.

preventTimerExecutionAfterThread(sThreadId, nTimeout)

Prevent execution of all timeouts and intervals, for the specified period of time, after a thread with the given id is executed.

The primary purpose of this method (and module:caplin/core/scheduler/ThreadScheduler#preventTimerExecutionFor) are to ensure that JavaScript execution pauses for enough time to allow the browser to update the screen. Typically, this will only need to occur after the execution of any display updating threads, for example 'display throttle' and 'SL4B update batcher'.

By default, ThreadScheduler does not control the execution of UI events, and so is unable to ensure screen refreshes occur if any long running UI events are running at the same time. It is therefore the responsibility of application developers to ensure that any long running UI events defer their operation using window.setTimeout(), also bringing these threads under the control of ThreadScheduler.

Parameters:

Name	Type	Description
`sThreadId`	String	The name of the thread after which timer execution should be prevented.
`nTimeout`	int	The number of milliseconds timer execution will be prevented for.

preventTimerExecutionFor(nTimeout)

Prevent execution of all timeouts and intervals for the specified period of time.

Parameters:

Name	Type	Description
`nTimeout`	int	The number of milliseconds for which timer execution will be prevented.

See:

preventTimerExecutionAfterThread

setInterval(fCallback, nInterval, sThreadIdopt) → {int}

A replacement for the native window.setInterval() method.

This method has the same API as window.setInterval(), except that it supports an optional sThreadId parameter that helps developers visualise thread usage, and is a pre-requisite for the use of the module:caplin/core/scheduler/ThreadScheduler#preventTimerExecutionAfterThread method. You do not need to call caplin.core.scheduler.ThreadScheduler.setInterval() directly as it also replaces the native window.setInterval() method.

Parameters:

Name	Type	Attributes	Description
`fCallback`	function		The function that will be invoked each time the the interval elapses.
`nInterval`	int		The number of milliseconds between each invocation of the call-back.
`sThreadId`	String	<optional>	A logical name for the thread that is being invoked.

Returns:

A unique identifier that can be used to cancel this interval using module:caplin/core/scheduler/ThreadScheduler#clearInterval.

Type: int

setThreadPriorities(pThreadIds)

Define the priorities with which threads will be scheduled.

The following example prioritises two named threads, while another thread is explicitly de-prioritised:

caplin.core.scheduler.ThreadScheduler.setThreadPriorities([
	 "highest-priority-thread",
	 "high-priority-thread",
	 "*",
	 "lowest-priority-thread"]);

Parameters:

Name	Type	Description
`pThreadIds`	Array	A list of thread identifiers, in priority order — a wildcard thread identifier (i.e. '*') can be used to explicitly de-prioritize any threads specified after that point.

setTimeout(fCallback, nTimeout, sThreadIdopt) → {int}

A replacement for the native window.setTimeout() method.

This method has the same API as window.setTimeout(), except that it supports an optional sThreadId parameter that helps developers visualise thread usage, and is a pre-requisite for the use of the module:caplin/core/scheduler/ThreadScheduler#preventTimerExecutionAfterThread method. You do not need to call caplin.core.scheduler.ThreadScheduler.setTimeout() directly as it also replaces the native window.setTimeout() method.

Parameters:

Name	Type	Attributes	Description
`fCallback`	function		The function that will be invoked once the timeout period has elapsed.
`nTimeout`	int		The number of milliseconds until the call-back will be invoked.
`sThreadId`	String	<optional>	A logical name for the thread that is being invoked.

Returns:

A unique identifier that can be used to cancel this timer using module:caplin/core/scheduler/ThreadScheduler#clearTimeout.

Type: int