Prepare/Check — Prepare and Check watchers

class Prepare(loop, callback[, data=None, priority=0])
class Check(loop, callback[, data=None, priority=0])
Parameters:
  • loop (Loop) – loop object responsible for this watcher (accessible through loop).
  • callback (callable) – see callback.
  • data (object) – any Python object you might want to attach to the watcher (stored in data).
  • priority (int) – see priority.

Prepare and Check watchers are often (but not always) used in pairs: Prepare watchers get invoked before the process blocks and Check watchers afterwards.

You must not call Loop.start() (or similar methods that enter the current event loop) or Loop.reset() from either Prepare or Check watchers. Other loops than the current one are fine, however. The rationale behind this is that you do not need to check for recursion in those watchers, i.e. the sequence will always be Prepare -> blocking -> Check so if you have one watcher of each kind they will always be called in pairs bracketing the blocking call.

They could be used, for example, to track variable changes, implement your own watchers, integrate net-snmp or a coroutine library and lots more. They are also occasionally useful if you cache some data and want to flush it before blocking.

Their main purpose is to integrate other event mechanisms into libev and their use is somewhat advanced. This is done by examining in each Prepare callback which file descriptors need to be watched by the other library, registering Io watchers for them and starting a Timer watcher for any timeouts (many libraries provide exactly this functionality). Then, in the Check watcher, you check for any events that occurred (by checking the pending status of all watchers and stopping them) and call back into the library. The I/O and timer callbacks will never actually be called (but must be valid nevertheless). When used for this purpose, it is recommended to give Check watchers highest (EV_MAXPRI) priority, to ensure that they are being run before any other watchers after the poll (this doesn’t matter for Prepare watchers).

Also, Check watchers (and Prepare watchers, too) should not activate (“feed”) events into libev. While libev fully supports this, they might get executed before other Check watchers did their job. As Check watchers are often used to embed other (non-libev) event loops those other event loops might be in an unusable state until their Check watcher ran.

See also

ev_prepare and ev_check - customise your event loop!