[core] Provide rationale for blocking queue while errors resolve

1 files changed, 17 insertions, 0 deletions

diff --git a/platform/default/mbgl/storage/offline_download.cpp b/platform/default/mbgl/storage/offline_download.cpp
index f8f5a2b737..5728b66647 100644
--- a/platform/default/mbgl/storage/offline_download.cpp
+++ b/platform/default/mbgl/storage/offline_download.cpp
@@ -199,6 +199,23 @@ void OfflineDownload::activateDownload() {
     });
 }
 
+/*
+   Fill up our own request queue by requesting the next few resources. This is called
+   when activating the download, or when a request completes successfully.
+
+   Note "successfully"; it's not called when a requests receives an error. A request
+   that errors will be retried after some delay. So in that sense it's still "active"
+   and consuming resources, notably the request object, its timer, and network resources
+   when the timer fires.
+
+   We could try to squeeze in subsequent requests while we wait for the errored request
+   to retry. But that risks overloading the upstream request queue -- defeating our own
+   metering -- if there are a lot of errored requests that all come up for retry at the
+   same time. And many times, the cause of a request error will apply to many requests
+   of the same type. For instance if a server is unreachable, all the requests to that
+   host are going to error. In that case, continuing to try subsequent resources after
+   the first few errors is fruitless anyway.
+*/
 void OfflineDownload::continueDownload() {
     if (resourcesRemaining.empty() && status.complete()) {
         setState(OfflineRegionDownloadState::Inactive);