Externally generating events that keep time (&TIME events)

A &TIME event can have one of the following formats:

It can contain a number of seconds:

&TIME(float seconds)

The seconds parameter represents the number of seconds since the epoch, 1st January 1970. The maximum value for seconds that the correlator can accept is 1012, which equates to roughly 33658 AD, and should be enough for anyone. However, most time formatting libraries cannot produce a date for numbers anywhere near that large.

Or it can contain a time string:

&TIME(string time)

The time is a string in extended ISO8601 form, with fractional seconds. For example:

&TIME("2015-04-20T23:32:41.032+01:00")

&TIME("2015-04-20T22:32:41.032+00:00")

&TIME("2015-04-20T22:32:41.032Z")

&TIME("2015-04-20T22:32:41.032")

These all refer to the same time. Note that the first example shows the time in a different timezone with an offset of 1 hour.

When the correlator processes an &TIME event by taking it off an input queue, the correlator sets its internal time (the current time) in that context to the value encoded in the event. Every event that the correlator processes after an &TIME event and before the next &TIME event has the same timestamp. That is, they have the timestamp indicated by the value of the previous &TIME event. For example:

&TIME(1)
A()
B()
&TIME(2)
C()

Events A and B each have a timestamp of 1. Event C has a timestamp of 2.

If you specify the -Xclock option, and you do not send &TIME events to the correlator, it is as if time has stopped in the correlator. Every event receives the exact same timestamp. While not sending time events is not strictly incorrect, it does mean that time stands still.

You must use great care when implementing this facility. There are EPL operations that rely on correct time-keeping. For example, all timer operations rely on time progressing forwards. Timers will fail to fire if time remains at a standstill, or worse, moves backwards. There is a warning message in the correlator log if you send a time event that moves time backwards.

When sending &TIME events into a multi-context application, the time ticks are delivered directly to all contexts. This can be different than the way in which events in the .evt file are sent in to the correlator and then sent between contexts in an application. This difference can result in processing events at an incorrect simulated time. In these cases, sending &FLUSHING(1), for example, before sending time ticks and events can result in more predictable and reliable behavior.

For more information, see Event timing.