Handles the execution of scheduled tasks, each of which may be an asynchronous operation. The control flow will ensure tasks are executed in the ordered scheduled, starting each task only once those before it have completed.
Each task scheduled within this flow may return a {@link webdriver.promise.Promise} to indicate it is an asynchronous operation. The ControlFlow will wait for such promises to be resolved before marking the task as completed.
Tasks and each callback registered on a {@link webdriver.promise.Deferred} will be run in their own ControlFlow frame. Any tasks scheduled within a frame will have priority over previously scheduled tasks. Furthermore, if any of the tasks in the frame fails, the remainder of the tasks in that frame will be discarded and the failure will be propagated to the user through the callback/task's promised result.
Each time a ControlFlow empties its task queue, it will fire an {@link webdriver.promise.ControlFlow.EventType.IDLE} event. Conversely, whenever the flow terminates due to an unhandled error, it will remove all remaining tasks in its queue and fire an {@link webdriver.promise.ControlFlow.EventType.UNCAUGHT_EXCEPTION} event. If there are no listeners registered with the flow, the error will be rethrown to the global error handler.
The timer object to use. Should only be set for testing.
How often, in milliseconds, the event loop should run.
Events that may be emitted by an {@link webdriver.promise.ControlFlow}.
Emitted when all tasks have been successfully executed.
Emitted whenever a new task has been scheduled.
Emitted whenever a control flow aborts due to an unhandled promise rejection. This event will be emitted along with the offending rejection reason. Upon emitting this event, the control flow will empty its task queue and revert to its initial state.
The default timer object, which uses the global timer functions.
The timer used by this instance.
Registers a listener.
The type of event to listen for.
The function to invoke when the event is fired.
The object in whose scope to invoke the listener.
A self reference.
Appends a summary of this instance's recent task history to the given error's stack trace. This function will also ensure the error's stack trace is in canonical form.
The error to annotate.
any
The annotated error.
Schedules a task that will wait for another promise to resolve. The resolved promise's value will be returned as the task result.
The promise to wait on.
A promise that will resolve when the task has completed.
Clears this instance's task history.
Fires an event and calls all listeners.
The type of event to emit.
Any arguments to pass to each listener.
Schedules a task for execution. If there is nothing currently in the queue, the task will be executed in the next turn of the event loop.
The function to call to start the task. If the function returns a {@link webdriver.promise.Promise}, this instance will wait for it to be resolved before starting the next task.
A description of the task.
A promise that will be resolved with the result of the action.
Returns a summary of the recent task activity for this instance. This includes the most recently completed task, as well as any parent tasks. In the returned summary, the task at index N is considered a sub-task of the task at index N+1.
Array<string>
A summary of this instance's recent task activity.
string
The scheduled tasks still pending with this instance.
Returns a mutable list of listeners for a specific type of event.
The type of event to retrieve the listeners for.
Array<{ fn: any; oneshot: boolean; scope: any; }>
{!Array.<{fn: !Function, oneshot: boolean, scope: (Object|undefined)}>} The registered listeners for the given event type.
An alias for {@code #addListener()}.
The type of event to listen for.
The function to invoke when the event is fired.
The object in whose scope to invoke the listener.
A self reference.
Registers a one-time listener which will be called only the first time an event is emitted, after which it will be removed.
The type of event to listen for.
The function to invoke when the event is fired.
The object in whose scope to invoke the listener.
A self reference.
Removes all listeners for a specific type of event. If no event is specified, all listeners across all types will be removed.
The type of event to remove listeners from.
A self reference.
Removes a previously registered event listener.
The type of event to unregister.
The handler function to remove.
A self reference.
Resets this instance, clearing its queue and removing all event listeners.
Inserts a {@code setTimeout} into the command queue. This is equivalent to a thread sleep in a synchronous programming language.
The timeout delay, in milliseconds.
A description to accompany the timeout.
A promise that will be resolved with the result of the action.
Schedules a task that shall wait for a condition to hold. Each condition function may return any value, but it will always be evaluated as a boolean.
Condition functions may schedule sub-tasks with this instance, however, their execution time will be factored into whether a wait has timed out.
In the event a condition returns a Promise, the polling loop will wait for it to be resolved before evaluating whether the condition has been satisfied. The resolution time for a promise is factored into whether a wait has timed out.
If the condition function throws, or returns a rejected promise, the wait task will fail.
The condition function to poll.
How long to wait, in milliseconds, for the condition to hold before timing out.
An optional error message to include if the wait times out; defaults to the empty string.
A promise that will be resolved when the condition has been satisified. The promise shall be rejected if the wait times out waiting for the condition.