Embed
— Embed watcher¶
-
class
Embed
(other, loop[, callback=None, data=None, priority=0])¶ Parameters: - other (
Loop
) – the loop to embed, this loop must be embeddable (i.e. its backend must be in the set ofembeddable_backends()
). - loop (
Loop
) – loop object responsible for this watcher (accessible throughloop
). - callback (callable or None) – see
callback
. - data (object) – any Python object you might want to attach to the
watcher (stored in
data
). - priority (int) – see
priority
.
This is a rather advanced watcher type that lets you embed one event loop into another (currently only
Io
events are supported in the embedded loop, other types of watchers might be handled in a delayed or incorrect fashion and must not be used).There are primarily two reasons you would want that: work around bugs and prioritise I/O.
As an example for a bug workaround, the
kqueue
backend might only support sockets on some platform, so it is unusable as generic backend, but you still want to make use of it because you have many sockets and it scales so nicely. In this case, you would create a kqueue-based loop and embed it into your default loop (which might use poll(2)). Overall operation will be a bit slower because first libev has to callpoll()
and thenkevent()
, but at least you can use both mechanisms for what they are best:kqueue
for scalable sockets and poll(2) if you want it to work :)As for prioritising I/O: under rare circumstances you have the case where some fds have to be watched and handled very quickly (with low latency), and even priorities and
Idle
watchers might have too much overhead. In this case you would put all the high priority stuff in one loop and all the rest in a second one, and embed the second one in the first.Unfortunately, not all backends are embeddable: only the ones returned by
embeddable_backends()
are, which, unfortunately, does not include any portable one.-
set
(other)¶ Parameters: other ( Loop
) – the loop to embed, this loop must be embeddable (i.e. its backend must be in the set ofembeddable_backends()
).Reconfigures the watcher.
-
sweep
()¶ Make a single, non-blocking sweep over the embedded loop. This works similarly to:
other.start(EVRUN_NOWAIT)
but in the most appropriate way for embedded loops.
-
callback
¶ As long as the watcher is active, the callback will be invoked every time there might be events pending in the embedded loop. The callback must then call
sweep()
to make a single sweep and invoke their callbacks (the callback doesn’t need to invoke thesweep()
method directly, it could also start anIdle
watcher to give the embedded loop strictly lower priority for example).You can also set the callback to
None
, in which case theEmbed
watcher will automatically execute the embedded loop sweep whenever necessary.See also
Watcher.callback
.
-
other
¶ Read only
The embedded event loop.
- other (