Module loop

source code

One-at-a-time notification-triggered Deferred event loop. Each such loop has a 'doorbell' named trigger() and a set of processing functions. The processing functions are expected to be callables like Scheduler methods, which examine a database for work to do. The doorbell will be rung by other code that writes into the database (possibly in a separate process).

At some point after the doorbell is rung, each function will be run in turn, one at a time. Each function can return a Deferred, and the next function will not be run until the previous one's Deferred has fired. That is, at all times, at most one processing function will be active.

If the doorbell is rung during a run, the loop will be run again later. Multiple rings may be handled by a single run, but the class guarantees that there will be at least one full run that begins after the last ring. The relative order of processing functions within a run is not preserved. If a processing function is added to the loop more than once, it will still only be called once per run.

If the Deferred returned by the processing function fires with a number, the event loop will call that function again at or after the given time (expressed as seconds since epoch). This can be used by processing functions when they want to 'sleep' until some amount of time has passed, such as for a Scheduler that is waiting for a tree-stable-timer to expire, or a Periodic scheduler that wants to fire once every six hours. This delayed call will obey the same one-at-a-time behavior as the run-everything trigger.

Each function's return-value-timer value will replace the previous timer. Any outstanding timer will be cancelled just before invoking a processing function. As a result, these functions should basically be idempotent: if the database says that the Scheduler needs to wake up at 5pm, it should keep returning '5pm' until it gets called after 5pm, at which point it should start returning None.

The functions should also add an epsilon (perhaps one second) to their desired wakeup time, so that rounding errors or low-resolution system timers don't cause 'OCD Alarm Clock Syndrome' (in which they get woken up a moment too early and then try to sleep repeatedly for zero seconds). The event loop will silently impose a 5-second minimum delay time to avoid this.

Any errors in the processing functions are written to log.err and then ignored.