update the comments

Author: zhongkechen

sdk/src/main/java/com/amazonaws/lambda/durable/execution/CheckpointBatcher.java

@@ -72,6 +72,7 @@ CompletableFuture<Operation> pollForUpdate(String operationId) {
         logger.debug("Polling request received: operation id {}", operationId);
         var future = new CompletableFuture<Operation>();
         synchronized (pollingFutures) {
+            // register the future in pollingFutures, which will be completed by the polling thread
             pollingFutures
                     .computeIfAbsent(operationId, k -> Collections.synchronizedList(new ArrayList<>()))
                     .add(future);
@@ -120,25 +121,28 @@ private void processQueue() {
     }
 
     protected CompletableFuture<Void> doBatchAction(List<OperationUpdate> updates) {
-        logger.debug("Calling durable API checkpointDurableExecution with {} updates", updates.size());
-        var response = client.checkpoint(durableExecutionArn, checkpointToken, updates);
-        logger.debug("Durable API checkpointDurableExecution called: {}.", response);
+        // doBatchAction will be called from the polling thread and also from AsyncBatcher.
+        // Use synchronized here to make sure no concurrent checkpoint API calls
+        synchronized (pollingFutures) {
+            logger.debug("Calling durable API checkpointDurableExecution with {} updates", updates.size());
+            var response = client.checkpoint(durableExecutionArn, checkpointToken, updates);
+            logger.debug("Durable API checkpointDurableExecution called: {}.", response);
 
-        // Notify callback of completion
-        // TODO: sam local backend returns no new execution state when called with zero
-        // updates. WHY?
-        // This means the polling will never receive an operation update and complete
-        // the Phaser.
-        checkpointToken = response.checkpointToken();
-        if (response.newExecutionState() != null) {
-            var operations = fetchAllPages(
-                    response.newExecutionState().operations(),
-                    response.newExecutionState().nextMarker());
-            if (!operations.isEmpty()) {
-                callback.accept(operations);
-            }
+            // Notify callback of completion
+            // TODO: sam local backend returns no new execution state when called with zero
+            // updates. WHY?
+            // This means the polling will never receive an operation update and complete
+            // the Phaser.
+            checkpointToken = response.checkpointToken();
+            if (response.newExecutionState() != null) {
+                var operations = fetchAllPages(
+                        response.newExecutionState().operations(),
+                        response.newExecutionState().nextMarker());
+                if (!operations.isEmpty()) {
+                    callback.accept(operations);
+                }
 
-            synchronized (pollingFutures) {
+                // complete the registered pollingFutures
                 for (var operation : operations) {
                     var pollers = pollingFutures.remove(operation.id());
                     if (pollers != null) {
@@ -150,7 +154,7 @@ protected CompletableFuture<Void> doBatchAction(List<OperationUpdate> updates) {
         return CompletableFuture.completedFuture(null);
     }
 
-    public static int estimateSize(OperationUpdate update) {
+    private static int estimateSize(OperationUpdate update) {
         if (update == null) {
             return 0;
         }

sdk/src/main/java/com/amazonaws/lambda/durable/execution/ExecutionManager.java

@@ -198,18 +198,18 @@ public Phaser startPhaser(String operationId) {
 
     // ===== Checkpointing =====
 
-    // This method will checkpoint the operation updates to the DAR backend and return a future which completes
+    // This method will checkpoint the operation updates to the durable backend and return a future which completes
     // when the checkpoint completes.
     public CompletableFuture<Void> sendOperationUpdate(OperationUpdate update) {
         return checkpointBatcher.checkpoint(update);
     }
 
     // ===== Polling =====
 
-    // This method will poll the operation from the DAR backend and return a future which completes
+    // This method will poll the operation updates from the durable backend and return a future which completes
     // when an update of the operation is received.
     // This is useful for in-process waits. For example, we want to
-    // wait while another thread is still running and we therefore are not
+    // wait while another thread is still running, and we therefore are not
     // re-invoked because we never suspended.
     public CompletableFuture<Operation> pollForOperationUpdates(String operationId) {
         return checkpointBatcher.pollForUpdate(operationId);