[
https://issues.apache.org/jira/browse/FLINK-5529?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=15839969#comment-15839969
]
ASF GitHub Bot commented on FLINK-5529:
---------------------------------------
Github user fhueske commented on a diff in the pull request:
https://github.com/apache/flink/pull/3191#discussion_r98028299
--- Diff: docs/dev/windows.md ---
@@ -692,30 +708,39 @@ input
## Triggers
-A `Trigger` determines when a window (as formed by the `WindowAssigner`)
is ready to be
+A `Trigger` determines when a window (as formed by the *window assigner*)
is ready to be
processed by the *window function*. Each `WindowAssigner` comes with a
default `Trigger`.
If the default trigger does not fit your needs, you can specify a custom
trigger using `trigger(...)`.
-The trigger interface provides five methods that react to different
events:
+The trigger interface has five methods that allow a `Trigger` to react to
different events:
* The `onElement()` method is called for each element that is added to a
window.
* The `onEventTime()` method is called when a registered event-time timer
fires.
* The `onProcessingTime()` method is called when a registered
processing-time timer fires.
* The `onMerge()` method is relevant for stateful triggers and merges the
states of two triggers when their corresponding windows merge, *e.g.* when
using session windows.
* Finally the `clear()` method performs any action needed upon removal of
the corresponding window.
-Any of these methods can be used to register processing- or event-time
timers for future actions.
+Two things to notice about the above methods are:
+
+1) The first three can return a `TriggerResult`, *i.e.* take action as a
response to their corresponding event. The action can be one of the following:
+* `CONTINUE`: do nothing,
+* `FIRE`: trigger the computation,
+* `PURGE`: clear the elements in the window, and
+* `FIRE_AND_PURGE`: take both previous actions.
+
+2) Any of these methods can be used to register processing- or event-time
timers for future actions.
### Fire and Purge
-Once a trigger determines that a window is ready for processing, it fires.
This is the signal for the window operator to emit the result of the current
window. Given a window with a `WindowFunction`
+Once a trigger determines that a window is ready for processing, it fires,
*i.e.*, it returns `FIRE` or `FIRE_AND_PURGE`. This is the signal for the
window operator
+to emit the result of the current window. Given a window with a
`WindowFunction`
all elements are passed to the `WindowFunction` (possibly after passing
them to an evictor).
Windows with `ReduceFunction` of `FoldFunction` simply emit their eagerly
aggregated result.
When a trigger fires, it can either `FIRE` or `FIRE_AND_PURGE`. While
`FIRE` keeps the contents of the window, `FIRE_AND_PURGE` removes its content.
By default, the pre-implemented triggers simply `FIRE` without purging the
window state.
-<span class="label label-danger">Attention</span> When purging, only the
contents of the window are cleared. The window itself is not removed and
accepts new elements.
+<span class="label label-danger">Attention</span> Purging will simply
remove the contents of the window and will leave any eventual meta-information
about the window and any trigger state intact.
--- End diff --
"eventual" -> "potential"?
> Improve / extends windowing documentation
> -----------------------------------------
>
> Key: FLINK-5529
> URL: https://issues.apache.org/jira/browse/FLINK-5529
> Project: Flink
> Issue Type: Sub-task
> Components: Documentation
> Reporter: Stephan Ewen
> Assignee: Kostas Kloudas
> Fix For: 1.2.0, 1.3.0
>
>
> Suggested Outline:
> {code}
> Windows
> (0) Outline: The anatomy of a window operation
> stream
> [.keyBy(...)] <- keyed versus non-keyed windows
> .window(...) <- required: "assigner"
> [.trigger(...)] <- optional: "trigger" (else default trigger)
> [.evictor(...)] <- optional: "evictor" (else no evictor)
> [.allowedLateness()] <- optional, else zero
> .reduce/fold/apply() <- required: "function"
> (1) Types of windows
> - tumble
> - slide
> - session
> - global
> (2) Pre-defined windows
> timeWindow() (tumble, slide)
> countWindow() (tumble, slide)
> - mention that count windows are inherently
> resource leaky unless limited key space
> (3) Window Functions
> - apply: most basic, iterates over elements in window
>
> - aggregating: reduce and fold, can be used with "apply()" which will get
> one element
>
> - forward reference to state size section
> (4) Advanced Windows
> - assigner
> - simple
> - merging
> - trigger
> - registering timers (processing time, event time)
> - state in triggers
> - life cycle of a window
> - create
> - state
> - cleanup
> - when is window contents purged
> - when is state dropped
> - when is metadata (like merging set) dropped
> (5) Late data
> - picture
> - fire vs fire_and_purge: late accumulates vs late resurrects (cf
> discarding mode)
>
> (6) Evictors
> - TDB
>
> (7) State size: How large will the state be?
> Basic rule: Each element has one copy per window it is assigned to
> --> num windows * num elements in window
> --> example: tumbline is one copy, sliding(n,m) is n/m copies
> --> per key
> Pre-aggregation:
> - if reduce or fold is set -> one element per window (rather than num
> elements in window)
> - evictor voids pre-aggregation from the perspective of state
> Special rules:
> - fold cannot pre-aggregate on session windows (and other merging windows)
> (8) Non-keyed windows
> - all elements through the same windows
> - currently not parallel
> - possible parallel in the future when having pre-aggregation functions
> - inherently (by definition) produce a result stream with parallelism one
> - state similar to one key of keyed windows
> {code}
--
This message was sent by Atlassian JIRA
(v6.3.4#6332)
