add comments and prioritize consumption of user action in diffing sagas

Author: philippotto

frontend/javascripts/viewer/model.ts

@@ -344,10 +344,20 @@ export class WebKnossosModel {
   };
 
   ensureSavedState = async () => {
-    // This function will only return once all state is saved
-    // even if new updates are pushed to the save queue during saving
+    /* This function will only return once all state is saved
+     * even if new updates are pushed to the save queue during saving
+     */
+
+    // This is a helper function which ensures that the diffing sagas
+    // have seen the newest tracings. These sagas are responsible for diffing
+    // old vs. new tracings to fill the save queue with update actions.
+    // waitForDifferResponses dispatches a special action which the diffing sagas
+    // will respond to be calling the callback that is attached to the action.
+    // That way, we can be sure that the diffing sagas have processed all user actions
+    // up until the time of where waitForDifferResponses was invoked.
     async function waitForDifferResponses() {
       const { annotation } = Store.getState();
+      // All skeleton and volume tracings should respond to the dispatched again.
       const tracingIds = new Set(
         _.compact([annotation.skeleton?.tracingId, ...annotation.volumes.map((t) => t.tracingId)]),
       );

frontend/javascripts/viewer/model/actions/save_actions.ts

@@ -126,6 +126,7 @@ export const dispatchRedoAsync = async (dispatch: Dispatch<any>): Promise<void>
   await readyDeferred.promise();
 };
 
+// See Model.ensureSavedState for an explanation of this action.
 export const ensureTracingsWereDiffedToSaveQueueAction = (callback: (tracingId: string) => void) =>
   ({
     type: "ENSURE_TRACINGS_WERE_DIFFED_TO_SAVE_QUEUE",

frontend/javascripts/viewer/model/sagas/save_saga.ts

@@ -7,6 +7,7 @@ import window, { alert, document, location } from "libs/window";
 import _ from "lodash";
 import memoizeOne from "memoize-one";
 import messages from "messages";
+import { buffers } from "redux-saga";
 import { actionChannel, call, delay, fork, put, race, take } from "typed-redux-saga";
 import { ControlModeEnum } from "viewer/constants";
 import { getMagInfo } from "viewer/model/accessors/dataset_accessor";
@@ -53,6 +54,7 @@ import type {
   SkeletonTracing,
   VolumeTracing,
 } from "viewer/store";
+import type { Action } from "../actions/actions";
 import { takeEveryWithBatchActionSupport } from "./saga_helpers";
 
 const ONE_YEAR_MS = 365 * 24 * 3600 * 1000;
@@ -388,6 +390,7 @@ export function* setupSavingForTracingType(
   let prevTdCamera = yield* select((state) => state.viewModeData.plane.tdCamera);
   yield* call(ensureWkReady);
 
+  const actionBuffer = buffers.expanding<Action>();
   const tracingActionChannel = yield* actionChannel(
     tracingType === "skeleton"
       ? [
@@ -399,20 +402,30 @@ export function* setupSavingForTracingType(
           "SET_TRACING",
         ]
       : [...VolumeTracingSaveRelevantActions, ...FlycamActions, ...ViewModeSaveRelevantActions],
+    actionBuffer,
   );
+
+  // See Model.ensureSavedState for an explanation of this action channel.
   const ensureDiffedChannel = yield* actionChannel<EnsureTracingsWereDiffedToSaveQueueAction>(
     "ENSURE_TRACINGS_WERE_DIFFED_TO_SAVE_QUEUE",
   );
 
   while (true) {
-    // todop: prioritize tracingAction?
-    const { ensureAction } = yield* race({
-      _tracingAction: take(tracingActionChannel),
-      ensureAction: take(ensureDiffedChannel),
-    });
-    if (ensureAction != null) {
-      ensureAction.callback(tracingId);
-      continue;
+    // Prioritize consumption of tracingActionChannel since we don't want to
+    // reply to the ENSURE_TRACINGS_WERE_DIFFED_TO_SAVE_QUEUE action if there
+    // are unprocessed user actions.
+    if (!actionBuffer.isEmpty()) {
+      yield* take(tracingActionChannel);
+    } else {
+      // Wait for either a user action or the "ensureAction".
+      const { ensureAction } = yield* race({
+        _tracingAction: take(tracingActionChannel),
+        ensureAction: take(ensureDiffedChannel),
+      });
+      if (ensureAction != null) {
+        ensureAction.callback(tracingId);
+        continue;
+      }
     }
 
     // The allowUpdate setting could have changed in the meantime