Class webdriver.promise.ControlFlow
code »webdriver.EventEmitter
└ webdriver.promise.ControlFlow
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
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 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
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
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.
Constructor
Parameters |
---|
|
Enumerations
|
Type Definitions
Instance Methods
Defined in webdriver.promise.ControlFlow
code »abortFrame_ ( error )Aborts the current frame. The frame, and all of the tasks scheduled within it
will be discarded. If this instance does not have an active frame, it will
immediately terminate all execution.
Parameters |
---|
|
Aborts this flow, abandoning all remaining tasks. If there are
listeners registered, an UNCAUGHT_EXCEPTION
will be emitted with the
offending error
, otherwise, the error
will be rethrown to the
global error handler.
UNCAUGHT_EXCEPTION
will be emitted with the
offending error
, otherwise, the error
will be rethrown to the
global error handler.Parameters |
---|
|
code »annotateError ( e ) ⇒ !(Error|goog.testing.JsUnitException)
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.
!(Error|goog.testing.JsUnitException)
Parameters |
---|
|
Returns |
|
code »await ( promise ) ⇒ !webdriver.promise.Promise
Schedules a task that will wait for another promise to resolve. The resolved
promise's value will be returned as the task result.
!webdriver.promise.Promise
Parameters |
---|
|
Returns |
|
Cancels the event loop, if necessary.
Cancels the shutdown sequence if it is currently scheduled.
Clears this instance's task history.
Commences the shutdown sequence for this instance. After one turn of the
event loop, this object will emit the
webdriver.promise.ControlFlow.EventType.IDLE
event to signal
listeners that it has completed. During this wait, if another task is
scheduled, the shutdown will be aborted.
webdriver.promise.ControlFlow.EventType.IDLE
event to signal
listeners that it has completed. During this wait, if another task is
scheduled, the shutdown will be aborted.code »execute ( fn, opt_description ) ⇒ !webdriver.promise.Promise
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.
!webdriver.promise.Promise
Parameters |
---|
|
Returns |
|
code »getHistory ( ) ⇒ !Array.<string>
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>
Returns |
---|
|
Returns |
---|
null if a frame was resolved. |
code »getSchedule ( ) ⇒ string
string
Returns |
---|
|
code »resolveFrame_ ( frame )
Parameters |
---|
|
Executes the next task for the current frame. If the current frame has no
more tasks, the frame's result will be resolved, returning control to the
frame's creator. This will terminate the flow if the completed frame was at
the top of the stack.
code »runInNewFrame_ ( fn, callback, errback, opt_activate )Executes a function in a new frame. If the function does not schedule any new
tasks, the frame will be discarded and the function's result returned
immediately. Otherwise, a promise will be returned. This promise will be
resolved with the function's result once all of the tasks scheduled within
the function have been completed. If the function's frame is aborted, the
returned promise will be rejected.
Parameters |
---|
Schedules the interval for this instance's event loop, if necessary.
code »timeout ( ms, opt_description ) ⇒ !webdriver.promise.Promise
Inserts a setTimeout
into the command queue. This is equivalent to
a thread sleep in a synchronous programming language.
!webdriver.promise.Promise
setTimeout
into the command queue. This is equivalent to
a thread sleep in a synchronous programming language.Removes a completed task from this instance's history record. If any
tasks remain from aborted frames, those will be removed as well.
code »wait ( condition, timeout, opt_message ) ⇒ !webdriver.promise.Promise
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.
!webdriver.promise.Promise
Parameters |
---|
Returns |
|
Defined in webdriver.EventEmitter
code »addListener ( type, listenerFn, opt_scope ) ⇒ !webdriver.EventEmitter
Registers a listener.
!webdriver.EventEmitter
code »addListener_ ( type, listenerFn, opt_scope, opt_oneshot ) ⇒ !webdriver.EventEmitter
Registers a listener.
!webdriver.EventEmitter
Parameters |
---|
Returns |
|
code »on ( type, listenerFn, opt_scope ) ⇒ !webdriver.EventEmitter
An alias for #addListener()
.
!webdriver.EventEmitter
#addListener()
.code »once ( type, listenerFn, opt_scope ) ⇒ !webdriver.EventEmitter
Registers a one-time listener which will be called only the first time an
event is emitted, after which it will be removed.
!webdriver.EventEmitter
code »removeAllListeners ( opt_type ) ⇒ !webdriver.EventEmitter
Removes all listeners for a specific type of event. If no event is
specified, all listeners across all types will be removed.
!webdriver.EventEmitter
Parameters |
---|
|
Returns |
|
code »removeListener ( type, listenerFn ) ⇒ !webdriver.EventEmitter
Removes a previously registered event listener.
!webdriver.EventEmitter
Instance Properties
Defined in webdriver.promise.ControlFlow
Tracks the active execution frame for this instance. Lazily initialized
when the first task is scheduled.
Interval ID for this instance's event loop.
The number of aborted frames since the last time a task was executed or a
frame completed successfully.
The number of "pending" promise rejections.
Each time a promise is rejected and is not handled by a listener, it will
schedule a 0-based timeout to check if it is still unrejected in the next
turn of the JS-event loop. This allows listeners to attach to, and handle,
the rejected promise at any point in same turn of the event loop that the
promise was rejected.
When this flow's own event loop triggers, it will not run if there
are any outstanding promise rejections. This allows unhandled promises to
be reported before a new task is started, ensuring the error is reported to
the current task queue.
A reference to the frame in which new tasks should be scheduled. If
null
, tasks will be scheduled within the active frame. When forcing
a function to run in the context of a new frame, this pointer is used to
ensure tasks are scheduled within the newly created frame, even though it
won't be active yet.
null
, tasks will be scheduled within the active frame. When forcing
a function to run in the context of a new frame, this pointer is used to
ensure tasks are scheduled within the newly created frame, even though it
won't be active yet.Timeout ID set when the flow is about to shutdown without any errors
being detected. Upon shutting down, the flow will emit an
webdriver.promise.ControlFlow.EventType.IDLE
event. Idle events
always follow a brief timeout in order to catch latent errors from the last
completed task. If this task had a callback registered, but no errback, and
the task fails, the unhandled failure would not be reported by the promise
system until the next turn of the event loop:
// Schedule 1 task that fails.
var result = webriver.promise.controlFlow().schedule('example',
function() { return webdriver.promise.rejected('failed'); });
// Set a callback on the result. This delays reporting the unhandled
// failure for 1 turn of the event loop.
result.then(goog.nullFunction);
webdriver.promise.ControlFlow.EventType.IDLE
event. Idle events
always follow a brief timeout in order to catch latent errors from the last
completed task. If this task had a callback registered, but no errback, and
the task fails, the unhandled failure would not be reported by the promise
system until the next turn of the event loop:
// Schedule 1 task that fails.
var result = webriver.promise.controlFlow().schedule('example',
function() { return webdriver.promise.rejected('failed'); });
// Set a callback on the result. This delays reporting the unhandled
// failure for 1 turn of the event loop.
result.then(goog.nullFunction);The timer used by this instance.
Defined in webdriver.EventEmitter
Static Properties
Property used to track whether an error has been annotated by
webdriver.promise.ControlFlow#annotateError
.
webdriver.promise.ControlFlow#annotateError
.