[FLINK-40503][core] Document effective idleness detection timing - #29039
Open
MartijnVisser wants to merge 1 commit into
Open
[FLINK-40503][core] Document effective idleness detection timing#29039MartijnVisser wants to merge 1 commit into
MartijnVisser wants to merge 1 commit into
Conversation
The withIdleness javadoc suggested a partition is considered idle once no records have arrived for idleTimeout, but WatermarksWithIdleness anchors its countdown at the first quiet periodic probe (up to two watermark intervals after the last record) and only switches to idle at the first probe strictly exceeding the timeout, so detection can take up to idleTimeout plus three watermark intervals. Document this actual behavior in the withIdleness and WatermarksWithIdleness javadocs and in the idle-sources documentation instead of changing the long-standing timing, and add a test pinning the documented contract. The Chinese documentation page translates this section and is left for a follow-up translation update. Generated-by: Claude Code (Fable 5)
Collaborator
uros-b
approved these changes
Aug 29, 2026
Member
|
LGTM, also kudos for nice testing |
github-actions
Bot
added
the
community-reviewed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What is the purpose of the change
Resolves FLINK-40503 by documenting when
withIdlenessactually takes effect. TheWatermarksWithIdlenesscountdown is anchored at the first quiet periodic probe rather than at the last record, and the strict>comparison only fires at the next probe after the timeout is exceeded — so idleness is detected between idleTimeout and idleTimeout plus three watermark intervals after the last record (the worst case is attained when the timeout is an exact multiple of the auto-watermark interval). The javadoc previously implied detection at idleTimeout. The timing itself is intentionally left unchanged: silently changing detection timing in this area has a regression track record (cf. the FLIP-471 follow-ups).Brief change log
WatermarkStrategy#withIdlenessjavadoc and theWatermarksWithIdlenessclass doc with the precise detection-timing contract.WatermarksWithIdlenessTimeoutTest, pinning the documented timing deterministically with a manual clock (timeout 10ms, probes every 5ms: not idle at the probes 11ms and 16ms after the last event, idle at the probe 21ms after it).Verifying this change
This change added tests and can be verified as follows:
WatermarksWithIdlenessTimeoutTestpins the documented detection timing.WatermarksWithIdlenessTestandWatermarkStrategyTestpass unchanged; no existing tests were modified.Does this pull request potentially affect one of the following parts:
@Public(Evolving): no (javadoc-only changes onWatermarkStrategy/WatermarksWithIdleness)Documentation
Was generative AI tooling used to co-author this PR?
Generated-by: Claude Code (Fable 5)