As a preliminary warning, using the
timeout module to kill useless Orchids threads is in general a bad idea, because Orchids is clever enough to kill them by itself.
One may also think of using the
timeout module to wait for an event for some amount of time, and stop waiting once that has elapsed, but that is also a wrong idea. Usually, the events we monitor have some form of time field, and the correct way to do this is something like:
expect (⟨what I am waiting for⟩
&& ⟨my time field⟩
$timeout holds the final time after which we will no longer care whether ⟨what I am waiting for⟩ happened or not. Orchids is clever enough to stop waiting after receiving the first event whose ⟨my time field⟩ field is larger than or equal to
$timeout, provided that ⟨my time field⟩ is flagged as monotonic, which is usually the case for time fields and sequence numbers.
timeout module has a different purpose, and is meant to schedule so-called
.timeout events to happen after some delay. By delay, we mean actual time, not any time field recorded in events. The difference is best explained by a thought experiment. Imagine you run Orchids on a file, holding events over a span of two hours. Orchids will probably read all those events in a fraction of a second, but calling
timeout("blah", 60) will only send a
.timeout event 60 seconds later, way after the whole file has been read.
set a real-time timeout
sets a timeout to delay seconds in the future: in delay seconds, a new synthetic event with the following fields will be injected:
.timeout.regdate: date at which the
timeoutcall was issued
.timeout.date: date at which the timeout is triggered, should be equal (or slightly above)
.timeout.name: the name name of the timeout, as given as first argument to
- returns: 1 (true)