Request Scheduler Prioritization

Source/Core/ArcGisImageServerTerrainProvider.js

@@ -14,6 +14,7 @@ define([
         './loadImage',
         './Math',
         './RequestScheduler',
+        './RequestType',
         './TerrainProvider'
     ], function(
         when,
@@ -30,6 +31,7 @@ define([
         loadImage,
         CesiumMath,
         RequestScheduler,
+        RequestType,
         TerrainProvider) {
     "use strict";
 
@@ -200,11 +202,15 @@ define([
      * @param {Number} x The X coordinate of the tile for which to request geometry.
      * @param {Number} y The Y coordinate of the tile for which to request geometry.
      * @param {Number} level The level of the tile for which to request geometry.
+     * @param {Boolean} [throttleRequests=true] True if the number of simultaneous requests should be limited,
+     *                  or false if the request should be initiated regardless of the number of requests
+     *                  already in progress.
+     * @param {Number} [distance] The distance of the tile from the camera, used to prioritize requests.
      * @returns {Promise.<TerrainData>|undefined} A promise for the requested geometry.  If this method
      *          returns undefined instead of a promise, it is an indication that too many requests are already
      *          pending and the request will be retried later.
      */
-    ArcGisImageServerTerrainProvider.prototype.requestTileGeometry = function(x, y, level) {
+    ArcGisImageServerTerrainProvider.prototype.requestTileGeometry = function(x, y, level, throttleRequests, distance) {
         var rectangle = this._tilingScheme.tileXYToRectangle(x, y, level);
 
         // Each pixel in the heightmap represents the height at the center of that
@@ -231,9 +237,16 @@ define([
             url = proxy.getURL(url);
         }
 
-        var promise = RequestScheduler.throttleRequest(url, loadImage);
-        if (!defined(promise)) {
-            return undefined;
+        var promise;
+
+        throttleRequests = defaultValue(throttleRequests, true);
+        if (throttleRequests) {
+            promise = RequestScheduler.throttleRequest(url, loadImage, RequestType.TERRAIN, distance);
+            if (!defined(promise)) {
+                return undefined;
+            }
+        } else {
+            promise = loadImage(url);
         }
 
         var that = this;

Source/Core/CesiumTerrainProvider.js

@@ -21,6 +21,7 @@ define([
         './OrientedBoundingBox',
         './QuantizedMeshTerrainData',
         './RequestScheduler',
+        './RequestType',
         './RuntimeError',
         './TerrainProvider',
         './TileProviderError'
@@ -46,6 +47,7 @@ define([
         OrientedBoundingBox,
         QuantizedMeshTerrainData,
         RequestScheduler,
+        RequestType,
         RuntimeError,
         TerrainProvider,
         TileProviderError) {
@@ -477,14 +479,16 @@ define([
      * @param {Boolean} [throttleRequests=true] True if the number of simultaneous requests should be limited,
      *                  or false if the request should be initiated regardless of the number of requests
      *                  already in progress.
+     * @param {Number} [distance] The distance of the tile from the camera, used to prioritize requests.
+     *
      * @returns {Promise.<TerrainData>|undefined} A promise for the requested geometry.  If this method
      *          returns undefined instead of a promise, it is an indication that too many requests are already
      *          pending and the request will be retried later.
      *
      * @exception {DeveloperError} This function must not be called before {@link CesiumTerrainProvider#ready}
      *            returns true.
      */
-    CesiumTerrainProvider.prototype.requestTileGeometry = function(x, y, level, throttleRequests) {
+    CesiumTerrainProvider.prototype.requestTileGeometry = function(x, y, level, throttleRequests, distance) {
         //>>includeStart('debug', pragmas.debug)
         if (!this._ready) {
             throw new DeveloperError('requestTileGeometry must not be called before the terrain provider is ready.');
@@ -522,7 +526,7 @@ define([
         }
         throttleRequests = defaultValue(throttleRequests, true);
         if (throttleRequests) {
-            promise = RequestScheduler.throttleRequest(url, tileLoader);
+            promise = RequestScheduler.throttleRequest(url, tileLoader, RequestType.TERRAIN, distance);
             if (!defined(promise)) {
                 return undefined;
             }

Source/Core/EllipsoidTerrainProvider.js

@@ -163,11 +163,13 @@ define([
      * @param {Boolean} [throttleRequests=true] True if the number of simultaneous requests should be limited,
      *                  or false if the request should be initiated regardless of the number of requests
      *                  already in progress.
+     * @param {Number} [distance] The distance of the tile from the camera, used to prioritize requests.
+     *
      * @returns {Promise.<TerrainData>|undefined} A promise for the requested geometry.  If this method
      *          returns undefined instead of a promise, it is an indication that too many requests are already
      *          pending and the request will be retried later.
      */
-    EllipsoidTerrainProvider.prototype.requestTileGeometry = function(x, y, level, throttleRequests) {
+    EllipsoidTerrainProvider.prototype.requestTileGeometry = function(x, y, level, throttleRequests, distance) {
         return this._terrainData;
     };
 

Source/Core/RequestScheduler.js

@@ -15,8 +15,31 @@ define([
         DeveloperError) {
     "use strict";
 
+    var RequestTypeBudget = function(type) {
+        /**
+         * Total requests allowed this frame
+         */
+        this.total = 0;
+
+        /**
+         * Total requests used this frame
+         */
+        this.used = 0;
+
+        /**
+         * Type of request. Used for more fine-grained priority sorting
+         */
+        this.type = type;
+    };
+
     var activeRequestsByServer = {};
     var activeRequests = 0;
+    var budgets = {};
+    var leftoverRequests = [];
+
+    var stats = {
+        numberOfRequestsThisFrame : 0
+    };
 
     /**
      * Because browsers throttle the number of parallel requests allowed to each server
@@ -32,6 +55,70 @@ define([
     function RequestScheduler() {
     }
 
+    function handleLeftoverRequest(url, type, distance) {
+        // TODO : don't create a new object, reuse instead
+        leftoverRequests.push({
+            url : url,
+            type : type,
+            distance : defaultValue(distance, 0.0)
+        });
+    }
+
+    function printStats() {
+        if (stats.numberOfRequestsThisFrame > 0) {
+            console.log('Number of requests attempted: ' + stats.numberOfRequestsThisFrame);
+        }
+
+        var numberOfActiveRequests = RequestScheduler.maximumRequests - RequestScheduler.getNumberOfAvailableRequests();
+        if (numberOfActiveRequests > 0) {
+            console.log('Number of active requests: ' + numberOfActiveRequests);
+        }
+    }
+
+    function distanceSortFunction(a, b) {
+        return a.distance - b.distance;
+    }
+
+    RequestScheduler.resetBudgets = function() {
+        // TODO : Right now, assume that requests made the previous frame will probably be issued again the current frame
+        // TODO : If this assumption changes, we should introduce stealing from other budgets.
+
+        if (!RequestScheduler.prioritize) {
+            return;
+        }
+
+        printStats();
+        stats.numberOfRequestsThisFrame = 0;
+
+        // Reset budget totals
+        for (var name in budgets) {
+            if (budgets.hasOwnProperty(name)) {
+                budgets[name].total = 0;
+                budgets[name].used = 0;
+            }
+        }
+
+        // Sort all requests made this frame by distance
+        var requests = leftoverRequests;
+        requests.sort(distanceSortFunction);
+
+        // Allocate new budgets based on the distances of leftover requests
+        var availableRequests = RequestScheduler.getNumberOfAvailableRequests();
+        var requestsLength = requests.length;
+        for (var j = 0; (j < requestsLength) && (availableRequests > 0); ++j) {
+            var request = requests[j];
+            var server = RequestScheduler.getServer(request.url);
+            var budget = budgets[server];
+            var budgetAvailable = RequestScheduler.getNumberOfAvailableRequestsByServer(request.url);
+            if (budget.total < budgetAvailable) {
+                ++budget.total;
+                --availableRequests;
+            }
+        }
+
+        requests.length = 0;
+    };
+
     var pageUri = typeof document !== 'undefined' ? new Uri(document.location.href) : new Uri();
 
     /**
@@ -109,6 +196,9 @@ define([
      * @param {String} url The URL to request.
      * @param {RequestScheduler~RequestFunction} requestFunction The actual function that
      *        makes the request.
+     * @param {RequestType} [requestType] The type of request being issued.
+     * @param {Number} [distance] The distance from the camera, used to prioritize requests.
+     *
      * @returns {Promise.<Object>|undefined} Either undefined, meaning the request would exceed the maximum number of
      *          parallel requests, or a Promise for the requested data.
      *
@@ -129,7 +219,7 @@ define([
      * }
      *
      */
-    RequestScheduler.throttleRequest = function(url, requestFunction) {
+    RequestScheduler.throttleRequest = function(url, requestFunction, requestType, distance) {
         //>>includeStart('debug', pragmas.debug);
         if (!defined(url)) {
             throw new DeveloperError('url is required.');
@@ -140,16 +230,33 @@ define([
         }
         //>>includeEnd('debug');
 
+        ++stats.numberOfRequestsThisFrame;
+
         if (activeRequests >= RequestScheduler.maximumRequests) {
+            handleLeftoverRequest(url, requestType, distance);
             return undefined;
         }
 
         var server = RequestScheduler.getServer(url);
         var activeRequestsForServer = defaultValue(activeRequestsByServer[server], 0);
         if (activeRequestsForServer >= RequestScheduler.maximumRequestsPerServer) {
+            handleLeftoverRequest(url, requestType, distance);
             return undefined;
         }
 
+        if (RequestScheduler.prioritize && defined(requestType)) {
+            var budget = budgets[server];
+            if (!defined(budget)) {
+                budget = new RequestTypeBudget(requestType);
+                budgets[server] = budget;
+            }
+            if (budget.used >= budget.total) {
+                handleLeftoverRequest(url, requestType, distance);
+                return undefined;
+            }
+            ++budget.used;
+        }
+
         ++activeRequests;
         activeRequestsByServer[server] = activeRequestsForServer + 1;
 
@@ -182,5 +289,12 @@ define([
      */
     RequestScheduler.maximumRequests = 10;
 
+    /**
+     * Specifies if the request scheduler should prioritize incoming requests
+     * @type {Boolean}
+     * @default true
+     */
+    RequestScheduler.prioritize = true;
+
     return RequestScheduler;
 });

Source/Core/RequestType.js

@@ -0,0 +1,19 @@
+/*global define*/
+define([
+        '../Core/freezeObject'
+    ], function(
+        freezeObject) {
+    "use strict";
+
+    /**
+     * @private
+     */
+    var RequestType = {
+        TERRAIN : 0,
+        IMAGERY : 1,
+        TILES3D : 2,
+        OTHER : 3
+    };
+
+    return freezeObject(RequestType);
+});

Source/Core/TerrainProvider.js

@@ -189,6 +189,8 @@ define([
      * @param {Boolean} [throttleRequests=true] True if the number of simultaneous requests should be limited,
      *                  or false if the request should be initiated regardless of the number of requests
      *                  already in progress.
+     * @param {Number} [distance] The distance of the tile from the camera, used to prioritize requests.
+     *
      * @returns {Promise.<TerrainData>|undefined} A promise for the requested geometry.  If this method
      *          returns undefined instead of a promise, it is an indication that too many requests are already
      *          pending and the request will be retried later.

Source/Core/VRTheWorldTerrainProvider.js

@@ -16,6 +16,7 @@ define([
         './Math',
         './Rectangle',
         './RequestScheduler',
+        './RequestType',
         './TerrainProvider',
         './TileProviderError'
     ], function(
@@ -35,6 +36,7 @@ define([
         CesiumMath,
         Rectangle,
         RequestScheduler,
+        RequestType,
         TerrainProvider,
         TileProviderError) {
     "use strict";
@@ -253,11 +255,12 @@ define([
      * @param {Boolean} [throttleRequests=true] True if the number of simultaneous requests should be limited,
      *                  or false if the request should be initiated regardless of the number of requests
      *                  already in progress.
+     * @param {Number} [distance] The distance of the tile from the camera, used to prioritize requests.
      * @returns {Promise.<TerrainData>|undefined} A promise for the requested geometry.  If this method
      *          returns undefined instead of a promise, it is an indication that too many requests are already
      *          pending and the request will be retried later.
      */
-    VRTheWorldTerrainProvider.prototype.requestTileGeometry = function(x, y, level, throttleRequests) {
+    VRTheWorldTerrainProvider.prototype.requestTileGeometry = function(x, y, level, throttleRequests, distance) {
         if (!this.ready) {
             throw new DeveloperError('requestTileGeometry must not be called before ready returns true.');
         }
@@ -274,7 +277,7 @@ define([
 
         throttleRequests = defaultValue(throttleRequests, true);
         if (throttleRequests) {
-            promise = RequestScheduler.throttleRequest(url, loadImage);
+            promise = RequestScheduler.throttleRequest(url, loadImage, RequestType.TERRAIN, distance);
             if (!defined(promise)) {
                 return undefined;
             }

Source/Scene/ArcGisMapServerImageryProvider.js

@@ -578,22 +578,23 @@ define([
      * @param {Number} x The tile X coordinate.
      * @param {Number} y The tile Y coordinate.
      * @param {Number} level The tile level.
+     * @param {Number} [distance] The distance of the tile from the camera, used to prioritize requests.
      * @returns {Promise.<Image|Canvas>|undefined} A promise for the image that will resolve when the image is available, or
      *          undefined if there are too many active requests to the server, and the request
      *          should be retried later.  The resolved image may be either an
      *          Image or a Canvas DOM object.
      *
      * @exception {DeveloperError} <code>requestImage</code> must not be called before the imagery provider is ready.
      */
-    ArcGisMapServerImageryProvider.prototype.requestImage = function(x, y, level) {
+    ArcGisMapServerImageryProvider.prototype.requestImage = function(x, y, level, distance) {
         //>>includeStart('debug', pragmas.debug);
         if (!this._ready) {
             throw new DeveloperError('requestImage must not be called before the imagery provider is ready.');
         }
         //>>includeEnd('debug');
 
         var url = buildImageUrl(this, x, y, level);
-        return ImageryProvider.loadImage(this, url);
+        return ImageryProvider.loadImage(this, url, distance);
     };
 
     /**