Namespace: webdriver.promise
View Source

# class ControlFlow

    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.Promise` will be run in their own ControlFlow frame. Any tasks scheduled within a frame will take priority over previously scheduled tasks. Furthermore, if any of the tasks in the frame fail, 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 `IDLE` event. Conversely, whenever the flow terminates due to an unhandled error, it will remove all remaining tasks in its queue and fire an `UNCAUGHT_EXCEPTION` event. If there are no listeners registered with the flow, the error will be rethrown to the global error handler.

Refer to the `webdriver.promise` module documentation for a detailed explanation of how the ControlFlow coordinates task execution.

### new ControlFlow()

Parameters

  None.

## Instance Methods

### addListener(type, listenerFn, opt_scope)code »

Registers a listener.

Defined by: webdriver.EventEmitter

Parameters

type`string`

  The type of event to listen for.

listenerFn`Function`

  The function to invoke when the event is fired.

opt_scope`?Object=`

  The object in whose scope to invoke the listener.

Returns

`webdriver.EventEmitter`

  A self reference.

### async(fn, opt_self, var_args)code »

Executes a function in the next available turn of the JavaScript event loop. This ensures the function runs with its own task queue and any scheduled tasks will run in "parallel" to those scheduled in the current function.

    flow.execute(() => console.log('a'));
    flow.execute(() => console.log('b'));
    flow.execute(() => console.log('c'));
    flow.async(() => {
       flow.execute(() => console.log('d'));
       flow.execute(() => console.log('e'));
    });
    flow.async(() => {
       flow.execute(() => console.log('f'));
       flow.execute(() => console.log('g'));
    });
    flow.once('idle', () => console.log('fin'));
    // a
    // d
    // f
    // b
    // e
    // g
    // c
    // fin

If the function itself throws, the error will be treated the same as an unhandled rejection within the control flow.

NOTE: This function is considered unstable.

Parameters

fn`Function`

  The function to execute.

opt_self`?Object=`

  The object in whose context to run the function.

var_args`...*`

  Any arguments to pass to the function.

### emit(type, var_args)code »

Fires an event and calls all listeners.

Defined by: webdriver.EventEmitter

Parameters

type`string`

  The type of event to emit.

var_args`...*`

  Any arguments to pass to each listener.

### `<T>` execute(fn, opt_description)code »

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. If the task function is a generator, the task will be executed using `webdriver.promise.consume`.

Parameters

fn`function(): (T|webdriver.promise.Promise<T>)`

  The function to call to start the task. If the function returns a `webdriver.promise.Promise`, this instance will wait for it to be resolved before starting the next task.

opt_description`string=`

  A description of the task.

Returns

`webdriver.promise.Promise<T>`

  A promise that will be resolved with the result of the action.

### getSchedule(opt_includeStackTraces)code »

Generates an annotated string describing the internal state of this control flow, including the currently executing as well as pending tasks. If `opt_includeStackTraces === true`, the string will include the stack trace from when each task was scheduled.

Parameters

opt_includeStackTraces`string=`

  Whether to include the stack traces from when each task was scheduled. Defaults to false.

Returns

`string`

  String representation of this flow's internal state.

### isIdle()code »

Returns

`boolean`

  Whether this flow is currently idle.

### listeners(type)code »

Returns a mutable list of listeners for a specific type of event.

Defined by: webdriver.EventEmitter

Parameters

type`string`

  The type of event to retrieve the listeners for.

Returns

`Array<{fn: Function, oneshot: boolean, scope: ?(Object)}>`

  The registered listeners for the given event type.

### on(type, listenerFn, opt_scope)code »

An alias for `#addListener()`.

Defined by: webdriver.EventEmitter

Parameters

type`string`

  The type of event to listen for.

listenerFn`Function`

  The function to invoke when the event is fired.

opt_scope`?Object=`

  The object in whose scope to invoke the listener.

Returns

`webdriver.EventEmitter`

  A self reference.

### once(type, listenerFn, opt_scope)code »

Registers a one-time listener which will be called only the first time an event is emitted, after which it will be removed.

Defined by: webdriver.EventEmitter

Parameters

type`string`

  The type of event to listen for.

listenerFn`Function`

  The function to invoke when the event is fired.

opt_scope`?Object=`

  The object in whose scope to invoke the listener.

Returns

`webdriver.EventEmitter`

  A self reference.

### removeAllListeners(opt_type)code »

Removes all listeners for a specific type of event. If no event is specified, all listeners across all types will be removed.

Defined by: webdriver.EventEmitter

Parameters

opt_type`string=`

  The type of event to remove listeners from.

Returns

`webdriver.EventEmitter`

  A self reference.

### removeListener(type, listenerFn)code »

Removes a previously registered event listener.

Defined by: webdriver.EventEmitter

Parameters

type`string`

  The type of event to unregister.

listenerFn`Function`

  The handler function to remove.

Returns

`webdriver.EventEmitter`

  A self reference.

### reset()code »

Resets this instance, clearing its queue and removing all event listeners.

### setPropagateUnhandledRejections(propagate)code »

Sets whether any unhandled rejections should propagate up through the control flow stack and cause rejections within parent tasks. If error propagation is disabled, tasks will not be aborted when an unhandled promise rejection is detected, but the rejection will trigger an `webdriver.promise.ControlFlow.EventType.UNCAUGHT_EXCEPTION` event.

The default behavior is to propagate all unhandled rejections. The use of this option is highly discouraged.

Parameters

propagate`boolean`

  whether to propagate errors.

### timeout(ms, opt_description)code »

Inserts a `setTimeout` into the command queue. This is equivalent to a thread sleep in a synchronous programming language.

Parameters

ms`number`

  The timeout delay, in milliseconds.

opt_description`string=`

  A description to accompany the timeout.

Returns

`webdriver.promise.Promise`

  A promise that will be resolved with the result of the action.

### toString()code »

Returns a string representation of this control flow, which is its current `schedule`, sans task stack traces.

Returns

`string`

  The string representation of this contorl flow.

### `<T>` wait(condition, opt_timeout, opt_message)code »

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.

If the condition is defined as a promise, the flow will wait for it to settle. If the timeout expires before the promise settles, the promise returned by this function will be rejected.

If this function is invoked with `timeout === 0`, or the timeout is omitted, the flow will wait indefinitely for the condition to be satisfied.

Parameters

condition`(webdriver.promise.Promise<T>|function(): ?)`

  The condition to poll, or a promise to wait on.

opt_timeout`number=`

  How long to wait, in milliseconds, for the condition to hold before timing out. If omitted, the flow will wait indefinitely.

opt_message`string=`

  An optional error message to include if the wait times out; defaults to the empty string.

Returns

`webdriver.promise.Promise<T>`

  A promise that will be fulfilled when the condition has been satisified. The promise shall be rejected if the wait times out waiting for the condition.

Throws

`TypeError`

  If condition is not a function or promise or if timeout is not a number >= 0.

## Types

ControlFlow.EventType

  Events that may be emitted by an `webdriver.promise.ControlFlow`.