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 of embeddable_backends()).
  • loop (Loop) – loop object responsible for this watcher (accessible through loop).
  • 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 call poll() and then kevent(), 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.

See also

ev_embed - when one backend isn’t enough…

set(other)
Parameters:other (Loop) – the loop to embed, this loop must be embeddable (i.e. its backend must be in the set of embeddable_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 the sweep() method directly, it could also start an Idle watcher to give the embedded loop strictly lower priority for example).

You can also set the callback to None, in which case the Embed watcher will automatically execute the embedded loop sweep whenever necessary.

See also Watcher.callback.

other

Read only

The embedded event loop.