1515
1616package window
1717
18- import "fmt"
18+ import (
19+ "fmt"
20+ "time"
21+ )
1922
23+ // Trigger describes when to emit new aggregations.
24+ // Fields are exported for use by the framework, and not intended
25+ // to be set by end users.
26+ //
27+ // This API is experimental and subject to change.
2028type Trigger struct {
21- Kind string
22- SubTriggers []Trigger
23- Delay int64 // in milliseconds
24- ElementCount int32
25- EarlyTrigger * Trigger
26- LateTrigger * Trigger
29+ Kind string
30+ SubTriggers []Trigger // Repeat, OrFinally, Any, All
31+ TimestampTransforms []TimestampTransform // AfterProcessingTime
32+ ElementCount int32 // ElementCount
33+ EarlyTrigger * Trigger // AfterEndOfWindow
34+ LateTrigger * Trigger // AfterEndOfWindow
35+ }
36+
37+ // TimestampTransform describes how an after processing time trigger
38+ // time is transformed to determine when to fire an aggregation.const
39+ // The base timestamp is always the when the first element of the pane
40+ // is received.
41+ //
42+ // A series of these transforms will be applied in order emit at regular intervals.
43+ type TimestampTransform interface {
44+ timestampTransform ()
45+ }
46+
47+ // DelayTransform takes the timestamp and adds the given delay to it.
48+ type DelayTransform struct {
49+ Delay int64 // in milliseconds
2750}
2851
52+ func (DelayTransform ) timestampTransform () {}
53+
54+ // AlignToTransform takes the timestamp and transforms it to the lowest
55+ // multiple of the period starting from the offset.
56+ //
57+ // Eg. A period of 20 with an offset of 45 would have alignments at 5,25,45,65 etc.
58+ // Timestamps would be transformed as follows: 0 to 5 would be transformed to 5,
59+ // 6 to 25 would be transformed to 25, 26 to 45 would be transformed to 45, and so on.
60+ type AlignToTransform struct {
61+ Period , Offset int64 // in milliseconds
62+ }
63+
64+ func (AlignToTransform ) timestampTransform () {}
65+
2966const (
3067 DefaultTrigger string = "Trigger_Default_"
3168 AlwaysTrigger string = "Trigger_Always_"
@@ -46,49 +83,101 @@ func TriggerDefault() Trigger {
4683 return Trigger {Kind : DefaultTrigger }
4784}
4885
49- // TriggerAlways constructs an always trigger that keeps firing immediately after an element is processed.
86+ // TriggerAlways constructs a trigger that fires immediately
87+ // whenever an element is received.
88+ //
5089// Equivalent to window.TriggerRepeat(window.TriggerAfterCount(1))
5190func TriggerAlways () Trigger {
5291 return Trigger {Kind : AlwaysTrigger }
5392}
5493
55- // TriggerAfterCount constructs an element count trigger that fires after atleast `count` number of elements are processed.
94+ // TriggerAfterCount constructs a trigger that fires after
95+ // at least `count` number of elements are processed.
5696func TriggerAfterCount (count int32 ) Trigger {
5797 return Trigger {Kind : ElementCountTrigger , ElementCount : count }
5898}
5999
60- // TriggerAfterProcessingTime constructs an after processing time trigger that fires after 'delay' milliseconds of processing time have passed.
61- func TriggerAfterProcessingTime (delay int64 ) Trigger {
62- return Trigger {Kind : AfterProcessingTimeTrigger , Delay : delay }
100+ // TriggerAfterProcessingTime constructs a trigger that fires relative to
101+ // when input first arrives.
102+ //
103+ // Must be configured with calls to PlusDelay, or AlignedTo. May be
104+ // configured with additional delay.
105+ func TriggerAfterProcessingTime () Trigger {
106+ return Trigger {Kind : AfterProcessingTimeTrigger }
63107}
64108
65- // TriggerRepeat constructs a repeat trigger that fires a trigger repeatedly once the condition has been met.
109+ // PlusDelay configures an AfterProcessingTime trigger to fire after a specified delay,
110+ // no smaller than a millisecond.
111+ func (tr Trigger ) PlusDelay (delay time.Duration ) Trigger {
112+ if tr .Kind != AfterProcessingTimeTrigger {
113+ panic (fmt .Errorf ("can't apply processing delay to %s, want: AfterProcessingTimeTrigger" , tr .Kind ))
114+ }
115+ if delay < time .Millisecond {
116+ panic (fmt .Errorf ("can't apply processing delay of less than a millisecond. Got: %v" , delay ))
117+ }
118+ tr .TimestampTransforms = append (tr .TimestampTransforms , DelayTransform {Delay : int64 (delay / time .Millisecond )})
119+ return tr
120+ }
121+
122+ // AlignedTo configures an AfterProcessingTime trigger to fire
123+ // at the smallest multiple of period since the offset greater than the first element timestamp.
124+ //
125+ // * Period may not be smaller than a millisecond.
126+ // * Offset may be a zero time (time.Time{}).
127+ func (tr Trigger ) AlignedTo (period time.Duration , offset time.Time ) Trigger {
128+ if tr .Kind != AfterProcessingTimeTrigger {
129+ panic (fmt .Errorf ("can't apply processing delay to %s, want: AfterProcessingTimeTrigger" , tr .Kind ))
130+ }
131+ if period < time .Millisecond {
132+ panic (fmt .Errorf ("can't apply an alignment period of less than a millisecond. Got: %v" , period ))
133+ }
134+ offsetMillis := int64 (0 )
135+ if ! offset .IsZero () {
136+ // TODO: Change to call UnixMilli() once we move to only supporting a go version > 1.17.
137+ offsetMillis = offset .Unix ()* 1e3 + int64 (offset .Nanosecond ())/ 1e6
138+ }
139+ tr .TimestampTransforms = append (tr .TimestampTransforms , AlignToTransform {
140+ Period : int64 (period / time .Millisecond ),
141+ Offset : offsetMillis ,
142+ })
143+ return tr
144+ }
145+
146+ // TriggerRepeat constructs a trigger that fires a trigger repeatedly
147+ // once the condition has been met.
148+ //
66149// Ex: window.TriggerRepeat(window.TriggerAfterCount(1)) is same as window.TriggerAlways().
67150func TriggerRepeat (tr Trigger ) Trigger {
68151 return Trigger {Kind : RepeatTrigger , SubTriggers : []Trigger {tr }}
69152}
70153
71- // TriggerAfterEndOfWindow constructs an end of window trigger that is configurable for early firing trigger(before the end of window)
72- // and late firing trigger(after the end of window).
73- // Default Options are: Default Trigger for EarlyFiring and No LateFiring. Override it with EarlyFiring and LateFiring methods on this trigger.
154+ // TriggerAfterEndOfWindow constructs a trigger that is configurable for early firing
155+ // (before the end of window) and late firing (after the end of window).
156+ //
157+ // Default Options are: Default Trigger for EarlyFiring and No LateFiring.
158+ // Override it with EarlyFiring and LateFiring methods on this trigger.
74159func TriggerAfterEndOfWindow () Trigger {
75160 defaultEarly := TriggerDefault ()
76161 return Trigger {Kind : AfterEndOfWindowTrigger , EarlyTrigger : & defaultEarly , LateTrigger : nil }
77162}
78163
79- // EarlyFiring configures AfterEndOfWindow trigger with an early firing trigger.
164+ // EarlyFiring configures an AfterEndOfWindow trigger with an implicitly
165+ // repeated trigger that applies before the end of the window.
80166func (tr Trigger ) EarlyFiring (early Trigger ) Trigger {
81167 if tr .Kind != AfterEndOfWindowTrigger {
82- panic (fmt .Errorf ("can't apply early firing to %s, got: %s, want: AfterEndOfWindowTrigger" , tr . Kind , tr .Kind ))
168+ panic (fmt .Errorf ("can't apply early firing to %s, want: AfterEndOfWindowTrigger" , tr .Kind ))
83169 }
84170 tr .EarlyTrigger = & early
85171 return tr
86172}
87173
88- // LateFiring configures AfterEndOfWindow trigger with a late firing trigger
174+ // LateFiring configures an AfterEndOfWindow trigger with an implicitly
175+ // repeated trigger that applies after the end of the window.
176+ //
177+ // Not setting a late firing trigger means elements are discarded.
89178func (tr Trigger ) LateFiring (late Trigger ) Trigger {
90179 if tr .Kind != AfterEndOfWindowTrigger {
91- panic (fmt .Errorf ("can't apply late firing to %s, got: %s, want: AfterEndOfWindowTrigger" , tr . Kind , tr .Kind ))
180+ panic (fmt .Errorf ("can't apply late firing to %s, want: AfterEndOfWindowTrigger" , tr .Kind ))
92181 }
93182 tr .LateTrigger = & late
94183 return tr
0 commit comments