davidzollo opened a new issue, #10545: URL: https://github.com/apache/seatunnel/issues/10545
Sub-issue of #10533 ## Scope `CheckpointCoordinator` implements Zeta's distributed checkpoint protocol: barrier injection, task ACK collection, state persistence, and restore. At 1 174 lines it has only ~21 Javadoc lines (~1.8 % coverage). The state machine and field semantics are entirely undocumented. ## File `seatunnel-engine/seatunnel-engine-server/src/main/java/org/apache/seatunnel/engine/server/checkpoint/CheckpointCoordinator.java` ## Methods to document | Method | Line | What to explain | |--------|------|-----------------| | `reportedTask(TaskReportStatusOperation)` | 256 | Entry point for task status reports; maps `WAITING_RESTORE` → `restoreTaskState`, `READY_START` → `allTaskReady` | | `restoreTaskState(TaskLocation)` | 306 | Looks up latest `CompletedCheckpoint`; distributes per-action states to the target task; parallelism remapping; `COORDINATOR_INDEX` special case for enumerator state | | `allTaskReady()` | 346 | Called once all tasks report `READY_START`; triggers first checkpoint cycle or immediately completes if no checkpoint is needed | | `tryTriggerPendingCheckpoint(CheckpointType)` | 500 | Enforces minimum checkpoint interval; guards against concurrent pending checkpoints; schedules barrier injection | | `acknowledgeTask(TaskAcknowledgeOperation)` | 905 | Accumulates per-task ACKs inside the `PendingCheckpoint`; calls `completePendingCheckpoint` when all tasks have ACKed | | `completePendingCheckpoint(CompletedCheckpoint)` | 942 | Persists checkpoint to storage; updates `runningJobStateIMap`; notifies all tasks; prunes oldest checkpoint from history | | `cleanPendingCheckpoint(CheckpointCloseReason)` | 853 | Abort path: maps close reason to failure vs cancel; clears all pending checkpoints | | `readyToClose(TaskLocation)` | 424 | Tracks source-complete signals; once all sources are ready-to-close, triggers final savepoint barrier | | `notifyTaskStart()` | 397 | Broadcasts task-start event to all pipeline tasks; part of startup sequencing | | `scheduleSchemaChangeBeforeCheckpoint()` | 1111 | Initiates the DDL-before-checkpoint phase of the schema-evolution protocol | ## Fields to document (add field-level Javadoc) | Field | Line | What to explain | |-------|------|-----------------| | `readyToCloseStartingTask` | 119 | Source tasks that have finished emitting data and are waiting for the final barrier | | `readyToCloseIdleTask` | 120 | Source tasks currently in idle (no-data) state awaiting close | | `closedIdleTask` | 121 | Idle tasks that have fully closed; used to gate coordinator completion | | `schemaChanging` | 136 | Guards normal checkpoint triggers during an in-progress DDL schema-change event | | `isAllTaskReady` | 143 | Set to `true` once; prevents duplicate `allTaskReady` calls on subsequent checkpoint cycles | ## How to contribute 1. Fork the repo and create a branch 2. Add Javadoc to the methods and fields above 3. Run `./mvnw spotless:apply` and `./mvnw -q -DskipTests verify` 4. Open a PR with title: `[Docs][Core] Add Javadoc to CheckpointCoordinator` -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
