Github user pnowojski commented on a diff in the pull request:
https://github.com/apache/flink/pull/6076#discussion_r194390932
--- Diff: docs/dev/event_time.md ---
@@ -213,10 +213,33 @@ arrive after the system's event time clock (as
signaled by the watermarks) has a
timestamp. See [Allowed Lateness]({{ site.baseurl
}}/dev/stream/operators/windows.html#allowed-lateness) for more information on
how to work
with late elements in event time windows.
+## Idling sources
+
+Currently with pure event time watermarks generators, watermarks can not
progress if there are no elements
+to be processed. That means in case of gap in the incoming data, even time
will not progress and for
+example window operator will not be triggered and thus existing windows
will not be able produce any
+output data.
+
+To circumvent this one can use periodic watermark assigners that don't
only assign based on
+element timestamps. Example solution could be an assigner that switches to
using current processing time
+as the time basis after not observing new events for a while.
## Debugging Watermarks
Please refer to the [Debugging Windows & Event Time]({{ site.baseurl
}}/monitoring/debugging_event_time.html) section for debugging
watermarks at runtime.
+## How operators are processing watermarks
+
+As a general rule, operators are required to completely process a given
watermark before forwarding it downstream. For example,
+`WindowOperator` will first evaluate which windows should be fired, and
only after producing all of the output triggered by
+the watermark will the watermark itself be sent downstream. In other
words, all elements produced due to occurrence of a watermark
+will be emitted before the watermark.
+
+The same rule applies to `TwoInputStreamOperator`. However, in this case
the current watermark of the operator is defined as
--- End diff --
They are part of the public api, so I don't see a big problem referring to
them. Especially that users are asking how to override the default behaviour
defined by `TwoInputStreamOperator.processWatermark1` and
`TwoInputStreamOperator.processWatermark2` (that was one of the reasons for
this doc improvement).
---
