Add some docs explaining [64f4f3cd878b1a72].

FossilOrigin-Name: 4fdf9a322fccf7d68b03d07a42a526f18f951e2e19228b7d41e01121b667cc86

1 files changed, 15 insertions, 3 deletions

diff --git a/ext/wasm/api/sqlite3-vfs-opfs.c-pp.js b/ext/wasm/api/sqlite3-vfs-opfs.c-pp.js
index da556224a..a5af548fa 100644
--- a/ext/wasm/api/sqlite3-vfs-opfs.c-pp.js
+++ b/ext/wasm/api/sqlite3-vfs-opfs.c-pp.js
@@ -471,10 +471,22 @@ const installOpfsVfs = function callee(options){
       /* async thread will take over here */;
       const t = performance.now();
       while('not-equal'!==Atomics.wait(state.sabOPView, state.opIds.rc, -1)){
-        /* See discussion at https://github.com/sqlite/sqlite-wasm/issues/12 */
+        /*
+          The reason for this loop is burried in the details of
+          a long discussion at:
+
+          https://github.com/sqlite/sqlite-wasm/issues/12
+
+          Summary: in at least one browser flavor, under high loads,
+          this wait() call can, on rare occasion, end up returning
+          'ok', which indicates that it's returning _without_ the
+          other half of the proxy having called Atomics.notify(). When
+          this happens, we just wait() again.
+        */
       }
-      /* When this wait() call returns, the async half will have
-         completed the operation and reported its results. */;
+      /* When the above wait() call returns 'not-equal', the async
+         half will have completed the operation and reported its results
+         in the state.opIds.rc slot of the SAB. */
       const rc = Atomics.load(state.sabOPView, state.opIds.rc);
       metrics[op].wait += performance.now() - t;
       if(rc && state.asyncS11nExceptions){