shaka-player 4.5.0 → 4.6.1

package/lib/routing/walker.js

@@ -1,587 +0,0 @@
-/*! @license
- * Shaka Player
- * Copyright 2016 Google LLC
- * SPDX-License-Identifier: Apache-2.0
- */
-
-goog.provide('shaka.routing.Walker');
-
-goog.require('goog.asserts');
-goog.require('shaka.routing.Node');
-goog.require('shaka.routing.Payload');
-goog.require('shaka.util.Destroyer');
-goog.require('shaka.util.Error');
-goog.require('shaka.util.IDestroyable');
-goog.require('shaka.util.PublicPromise');
-goog.requireType('shaka.util.AbortableOperation');
-
-
-/**
- * The walker moves through a graph node-by-node executing asynchronous work
- * as it enters each node.
- *
- * The walker accepts requests for where it should go next. Requests are queued
- * and executed in FIFO order. If the current request can be interrupted, it
- * will be cancelled and the next request started.
- *
- * A request says "I want to change where we are going". When the walker is
- * ready to change destinations, it will resolve the request, allowing the
- * destination to differ based on the current state and not the state when
- * the request was appended.
- *
- * Example (from shaka.Player):
- *  When we unload, we need to either go to the attached or detached state based
- *  on whether or not we have a video element.
- *
- *  When we are asked to unload, we don't know what other pending requests may
- *  be ahead of us (there could be attach requests or detach requests). We need
- *  to wait until its our turn to know if:
- *    - we should go to the attach state because we have a media element
- *    - we should go to the detach state because we don't have a media element
- *
- * The walker allows the caller to specify if a route can or cannot be
- * interrupted. This is to allow potentially dependent routes to wait until
- * other routes have finished.
- *
- * Example (from shaka.Player):
- *  A request to load content depends on an attach request finishing. We don't
- *  want load request to interrupt an attach request. By marking the attach
- *  request as non-interruptible we ensure that calling load before attach
- *  finishes will work.
- *
- * @implements {shaka.util.IDestroyable}
- * @final
- */
-shaka.routing.Walker = class {
-  /**
-   * Create a new walker that starts at |startingAt| and with |startingWith|.
-   * The instance of |startingWith| will be the one that the walker holds and
-   * uses for its life. No one else should reference it.
-   *
-   * The per-instance behaviour for the walker is provided via |implementation|
-   * which is used to connect this walker with the "outside world".
-   *
-   * @param {shaka.routing.Node} startingAt
-   * @param {shaka.routing.Payload} startingWith
-   * @param {shaka.routing.Walker.Implementation} implementation
-   */
-  constructor(startingAt, startingWith, implementation) {
-    /** @private {?shaka.routing.Walker.Implementation} */
-    this.implementation_ = implementation;
-
-    /** @private {shaka.routing.Node} */
-    this.currentlyAt_ = startingAt;
-
-    /** @private {shaka.routing.Payload} */
-    this.currentlyWith_ = startingWith;
-
-    /**
-     * When we run out of work to do, we will set this promise so that when
-     * new work is added (and this is not null) it can be resolved. The only
-     * time when this should be non-null is when we are waiting for more work.
-     *
-     * @private {?shaka.util.PublicPromise}
-     */
-    this.waitForWork_ = null;
-
-    /** @private {!Array.<shaka.routing.Walker.Request_>} */
-    this.requests_ = [];
-
-    /** @private {?shaka.routing.Walker.ActiveRoute_} */
-    this.currentRoute_ = null;
-
-    /** @private {?shaka.util.AbortableOperation} */
-    this.currentStep_ = null;
-
-    /**
-     * Hold a reference to the main loop's promise so that we know when it has
-     * exited. This will determine when |destroy| can resolve. Purposely make
-     * the main loop start next interpreter cycle so that the constructor will
-     * finish before it starts.
-     *
-     * @private {!Promise}
-     */
-    this.mainLoopPromise_ = Promise.resolve().then(() => this.mainLoop_());
-
-    /** @private {!shaka.util.Destroyer} */
-    this.destroyer_ = new shaka.util.Destroyer(() => this.doDestroy_());
-  }
-
-  /**
-   * Get the current routing payload.
-   *
-   * @return {shaka.routing.Payload}
-   */
-  getCurrentPayload() {
-    return this.currentlyWith_;
-  }
-
-  /** @override */
-  destroy() {
-    return this.destroyer_.destroy();
-  }
-
-  /** @private */
-  async doDestroy_() {
-    // If we are executing a current step, we want to interrupt it so that we
-    // can force the main loop to terminate.
-    if (this.currentStep_) {
-      this.currentStep_.abort();
-    }
-
-    // If we are waiting for more work, we want to wake-up the main loop so that
-    // it can exit on its own.
-    this.unblockMainLoop_();
-
-    // Wait for the main loop to terminate so that an async operation won't
-    // try and use state that we released.
-    await this.mainLoopPromise_;
-
-    // Any routes that we are not going to finish, we need to cancel. If we
-    // don't do this, those listening will be left hanging.
-    if (this.currentRoute_) {
-      this.currentRoute_.listeners.onCancel();
-    }
-    for (const request of this.requests_) {
-      request.listeners.onCancel();
-    }
-
-    // Release anything that could hold references to anything outside of this
-    // class.
-    this.currentRoute_ = null;
-    this.requests_ = [];
-    this.implementation_ = null;
-  }
-
-  /**
-   * Ask the walker to start a new route. When the walker is ready to start a
-   * new route, it will call |create| and |create| will provide the walker with
-   * a new route to execute.
-   *
-   * If any previous calls to |startNewRoute| created non-interruptible routes,
-   * |create| won't be called until all previous non-interruptible routes have
-   * finished.
-   *
-   * This method will return a collection of listeners that the caller can hook
-   * into. Any listener that the caller is interested should be assigned
-   * immediately after calling |startNewRoute| or else they could miss the event
-   * they want to listen for.
-   *
-   * @param {function(shaka.routing.Payload):?shaka.routing.Walker.Route} create
-   * @return {shaka.routing.Walker.Listeners}
-   */
-  startNewRoute(create) {
-    const listeners = {
-      onStart: () => {},
-      onEnd: () => {},
-      onCancel: () => {},
-      onError: (error) => {},
-      onSkip: () => {},
-      onEnter: () => {},
-    };
-
-    this.requests_.push({
-      create: create,
-      listeners: listeners,
-    });
-
-    // If we are in the middle of a step, try to abort it. If this is successful
-    // the main loop will error and the walker will enter recovery mode.
-    if (this.currentStep_) {
-      this.currentStep_.abort();
-    }
-
-    // Tell the main loop that new work is available. If the main loop was not
-    // blocked, this will be a no-op.
-    this.unblockMainLoop_();
-
-    return listeners;
-  }
-
-  /**
-   * @return {!Promise}
-   * @private
-   */
-  async mainLoop_() {
-    while (!this.destroyer_.destroyed()) {
-      // eslint-disable-next-line no-await-in-loop
-      await this.doOneThing_();
-    }
-  }
-
-  /**
-   * Do one thing to move the walker closer to its destination. This can be:
-   *   1. Starting a new route.
-   *   2. Taking one more step/finishing a route.
-   *   3. Wait for a new route.
-   *
-   * @return {!Promise}
-   * @private
-   */
-  doOneThing_() {
-    if (this.tryNewRoute_()) {
-      return Promise.resolve();
-    }
-
-    if (this.currentRoute_) {
-      return this.takeNextStep_();
-    }
-
-    goog.asserts.assert(this.waitForWork_ == null,
-        'We should not have a promise yet.');
-
-    // We have no more work to do. We will wait until new work has been provided
-    // via request route or until we are destroyed.
-
-    this.implementation_.onIdle(this.currentlyAt_);
-
-    // Wait on a new promise so that we can be resolved by |waitForWork|. This
-    // avoids us acting like a busy-wait.
-    this.waitForWork_ = new shaka.util.PublicPromise();
-    return this.waitForWork_;
-  }
-
-  /**
-   * Check if the walker can start a new route. There are a couple ways this can
-   * happen:
-   *  1. We have a new request but no current route
-   *  2. We have a new request and our current route can be interrupted
-   *
-   * @return {boolean}
-   *    |true| when a new route was started (regardless of reason) and |false|
-   *    when no new route was started.
-   *
-   * @private
-   */
-  tryNewRoute_() {
-    goog.asserts.assert(
-        this.currentStep_ == null,
-        'We should never have a current step between taking steps.');
-
-    if (this.requests_.length == 0) {
-      return false;
-    }
-
-    // If the current route cannot be interrupted, we can't start a new route.
-    if (this.currentRoute_ && !this.currentRoute_.interruptible) {
-      return false;
-    }
-
-    // Stop any previously active routes. Even if we don't pick-up a new route,
-    // this route should stop.
-    if (this.currentRoute_) {
-      this.currentRoute_.listeners.onCancel();
-      this.currentRoute_ = null;
-    }
-
-    // Create and start the next route. We may not take any steps because it may
-    // be interrupted by the next request.
-    const request = this.requests_.shift();
-    const newRoute = request.create(this.currentlyWith_);
-
-    // Based on the current state of |payload|, a new route may not be
-    // possible. In these cases |create| will return |null| to signal that
-    // we should just stop the current route and move onto the next request
-    // (in the next main loop iteration).
-    if (newRoute) {
-      request.listeners.onStart();
-
-      // Convert the route created from the request's create method to an
-      // active route.
-      this.currentRoute_ = {
-        node: newRoute.node,
-        payload: newRoute.payload,
-        interruptible: newRoute.interruptible,
-        listeners: request.listeners,
-      };
-    } else {
-      request.listeners.onSkip();
-    }
-
-    return true;
-  }
-
-
-  /**
-   * Move forward one step on our current route. This assumes that we have a
-   * current route. A couple things can happen when moving forward:
-   *  1. An error - if an error occurs, it will signal an error occurred,
-   *     attempt to recover, and drop the route.
-   *  2. Move - if no error occurs, we will move forward. When we arrive at
-   *     our destination, it will signal the end and drop the route.
-   *
-   * In the event of an error or arriving at the destination, we drop the
-   * current route. This allows us to pick-up a new route next time the main
-   * loop iterates.
-   *
-   * @return {!Promise}
-   * @private
-   */
-  async takeNextStep_() {
-    goog.asserts.assert(
-        this.currentRoute_,
-        'We need a current route to take the next step.');
-
-    // Figure out where we are supposed to go next.
-    this.currentlyAt_ = this.implementation_.getNext(
-        this.currentlyAt_,
-        this.currentlyWith_,
-        this.currentRoute_.node,
-        this.currentRoute_.payload);
-
-    this.currentRoute_.listeners.onEnter(this.currentlyAt_);
-
-    // Enter the new node, this is where things can go wrong since it is
-    // possible for "supported errors" to occur - errors that the code using
-    // the walker can't predict but can recover from.
-    try {
-      // TODO: This is probably a false-positive.  See eslint/eslint#11687.
-      // eslint-disable-next-line require-atomic-updates
-      this.currentStep_ = this.implementation_.enterNode(
-          /* node= */ this.currentlyAt_,
-          /* has= */ this.currentlyWith_,
-          /* wants= */ this.currentRoute_.payload);
-
-      await this.currentStep_.promise;
-      this.currentStep_ = null;
-
-      // If we are at the end of the route, we need to signal it and clear the
-      // route so that we will pick-up a new route next iteration.
-      if (this.currentlyAt_ == this.currentRoute_.node) {
-        this.currentRoute_.listeners.onEnd();
-        this.currentRoute_ = null;
-      }
-    } catch (error) {
-      if (error.code == shaka.util.Error.Code.OPERATION_ABORTED) {
-        goog.asserts.assert(
-            this.currentRoute_.interruptible,
-            'Do not put abortable steps in non-interruptible routes!');
-        this.currentRoute_.listeners.onCancel();
-      } else {
-        // There was an error with this route, so we going to abandon it and
-        // resolve the error. We don't reset the payload because the payload may
-        // still contain useful information.
-        this.currentRoute_.listeners.onError(error);
-      }
-
-      // The route and step are done. Clear them before we handle the error or
-      // else we may attempt to abort |currentStep_| when handling the error.
-      this.currentRoute_ = null;
-      this.currentStep_ = null;
-
-      // Still need to handle error because aborting an operation could leave us
-      // in an unexpected state.
-      this.currentlyAt_ = await this.implementation_.handleError(
-          this.currentlyWith_,
-          error);
-    }
-  }
-
-  /**
-   * If the main loop is blocked waiting for new work, then resolve the promise
-   * so that the next iteration of the main loop can execute.
-   *
-   * @private
-   */
-  unblockMainLoop_() {
-    if (this.waitForWork_) {
-      this.waitForWork_.resolve();
-      this.waitForWork_ = null;
-    }
-  }
-};
-
-/**
- * @typedef {{
- *   getNext: function(
- *       shaka.routing.Node,
- *       shaka.routing.Payload,
- *       shaka.routing.Node,
- *       shaka.routing.Payload):shaka.routing.Node,
- *   enterNode: function(
- *       shaka.routing.Node,
- *       shaka.routing.Payload,
- *       shaka.routing.Payload):!shaka.util.AbortableOperation,
- *   handleError: function(
- *       shaka.routing.Payload,
- *       !Error):!Promise.<shaka.routing.Node>,
- *   onIdle: function(shaka.routing.Node)
- * }}
- *
- * @description
- *   There are some parts of the walker that will be per-instance. This type
- *   provides those per-instance parts.
- *
- * @property {function(
- *     shaka.routing.Node,
- *     shaka.routing.Payload,
- *     shaka.routing.Node,
- *     shaka.routing.Payload):shaka.routing.Node getNext
- *   Get the next node that the walker should move to. This method will be
- *   passed (in this order) the current node, current payload, destination
- *   node, and destination payload.
- *
- * @property {function(
- *     shaka.routing.Node,
- *     shaka.routing.Payload,
- *     shaka.routing.Payload):!Promise} enterNode
- *   When the walker moves into a node, it will call |enterNode| and allow the
- *   implementation to change the current payload. This method will be passed
- *   (in this order) the node the walker is entering, the current payload, and
- *   the destination payload. This method should NOT modify the destination
- *   payload.
- *
- * @property {function(
- *     shaka.routing.Payload,
- *     !Error):!Promise.<shaka.routing.Node> handleError
- *   This is the callback for when |enterNode| fails. It is passed the current
- *   payload and the error. If a step is aborted, the error will be
- *   OPERATION_ABORTED. It should reset all external dependences, modify the
- *   payload, and return the new current node. Calls to |handleError| should
- *   always resolve and the walker should always be able to continue operating.
- *
- * @property {function(shaka.routing.Node)} onIdle
- *   This is the callback for when the walker has finished processing all route
- *   requests and needs to wait for more work. |onIdle| will be passed the
- *   current node.  After |onIdle| has been called, the walker will block until
- *   a new request is made, or the walker is destroyed.
- */
-shaka.routing.Walker.Implementation;
-
-/**
- * @typedef {{
- *   onStart: function(),
- *   onEnd: function(),
- *   onCancel: function(),
- *   onError: function(!Error),
- *   onSkip: function(),
- *   onEnter: function(shaka.routing.Node)
- * }}
- *
- * @description
- *   The collection of callbacks that the walker will call while executing a
- *   route. By setting these immediately after calling |startNewRoute|
- *   the user can react to route-specific events.
- *
- * @property {function()} onStart
- *   The callback for when the walker has accepted the route and will soon take
- *   the first step unless interrupted. Either |onStart| or |onSkip| will be
- *   called.
- *
- * @property {function()} onEnd
- *   The callback for when the walker has reached the end of the route. For
- *   every route that had |onStart| called, either |onEnd|, |onCancel|, or
- *   |onError| will be called.
- *
- * @property {function()} onCancel
- *   The callback for when the walker is stopping a route before getting to the
- *   end. This will be called either when a new route is interrupting the route,
- *   or the walker is being destroyed mid-route. |onCancel| will only be called
- *   when a route has been interrupted by another route or the walker is being
- *   destroyed.
- *
- * @property {function()} onError
- *   The callback for when the walker failed to execute the route because an
- *   unexpected error occurred. The walker will enter a recovery mode and the
- *   route will be abandoned.
- *
- * @property {function()} onSkip
- *   The callback for when the walker was ready to start the route, but the
- *   create-method returned |null|.
- *
- * @property {function()} onEnter
- *   The callback for when the walker enters a node. This will allow us to
- *   track the progress of the walker within a per-route scope.
- */
-shaka.routing.Walker.Listeners;
-
-/**
- * @typedef {{
- *   node: shaka.routing.Node,
- *   payload: shaka.routing.Payload,
- *   interruptible: boolean
- * }}
- *
- * @description
- *   The public description of where the walker should go. This is created
- *   when the callback given to |startNewRoute| is called by the walker.
- *
- * @property {shaka.routing.Node} node
- *   The node that the walker should move towards. This will be passed to
- *   |shaka.routing.Walker.Implementation.getNext| to help determine where to
- *   go next.
- *
- * @property {shaka.routing.Payload| payload
- *   The payload that the walker should have once it arrives at |node|. This
- *   will be passed to the |shaka.routing.Walker.Implementation.getNext| to
- *   help determine where to go next.
- *
- * @property {boolean} interruptible
- *   Whether or not this route can be interrupted by another request. When
- *   |true| this route will be interrupted so that a pending request can be
- *   resolved. When |false|, the route will be allowed to finished before
- *   resolving the next request.
- */
-shaka.routing.Walker.Route;
-
-/**
- * @typedef {{
- *   node: shaka.routing.Node,
- *   payload: shaka.routing.Payload,
- *   interruptible: boolean,
- *   listeners: shaka.routing.Walker.Listeners
- * }}
- *
- * @description
- *   The active route is the walker's internal representation of a route. It
- *   is the union of |shaka.routing.Walker.Request_| and the
- *   |shaka.routing.Walker.Route| created by |shaka.routing.Walker.Request_|.
- *
- * @property {shaka.routing.Node} node
- *   The node that the walker should move towards. This will be passed to
- *   |shaka.routing.Walker.Implementation.getNext| to help determine where to
- *   go next.
- *
- * @property {shaka.routing.Payload| payload
- *   The payload that the walker should have once it arrives at |node|. This
- *   will be passed to the |shaka.routing.Walker.Implementation.getNext| to
- *   help determine where to go next.
- *
- * @property {boolean} interruptible
- *   Whether or not this route can be interrupted by another request. When
- *   |true| this route will be interrupted so that a pending request can be
- *   resolved. When |false|, the route will be allowed to finished before
- *   resolving the next request.
- *
- * @property {shaka.routing.Walker.Listeners} listeners
- *   The listeners that the walker can used to communicate with whoever
- *   requested the route.
- *
- * @private
- */
-shaka.routing.Walker.ActiveRoute_;
-
-/**
- * @typedef {{
- *   create: function(shaka.routing.Payload):?shaka.routing.Walker.Route,
- *   listeners: shaka.routing.Walker.Listeners
- * }}
- *
- * @description
- *   The request is how users can talk to the walker. They can give the walker
- *   a request and when the walker is ready, it will resolve the request by
- *   calling |create|.
- *
- * @property {
- *     function(shaka.routing.Payload):?shaka.routing.Walker.Route} create
- *   The function called when the walker is ready to start a new route. This can
- *   return |null| to say that the request was not possible and should be
- *   skipped.
- *
- * @property {shaka.routing.Walker.Listeners} listeners
- *   The collection of callbacks that the walker will use to talk to whoever
- *   provided the request.
- *
- * @private
- */
-shaka.routing.Walker.Request_;