+</div>
+<h2 id="code_ev_embed_code_when_one_backend_"><code>ev_embed</code> - when one backend isn't enough</h2>
+<div id="code_ev_embed_code_when_one_backend_-2">
+<p>This is a rather advanced watcher type that lets you embed one event loop
+into another (currently only <code>ev_io</code> 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).</p>
+<p>There are primarily two reasons you would want that: work around bugs and
+prioritise I/O.</p>
+<p>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 e.g. poll). Overall operation will
+be a bit slower because first libev has to poll and then call kevent, but
+at least you can use both at what they are best.</p>
+<p>As for prioritising I/O: rarely 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.</p>
+<p>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 <code>ev_embed_sweep (mainloop, watcher)</code> to make a single sweep and invoke
+their callbacks (you could also start an idle watcher to give the embedded
+loop strictly lower priority for example). You can also set the callback
+to <code>0</code>, in which case the embed watcher will automatically execute the
+embedded loop sweep.</p>
+<p>As long as the watcher is started it will automatically handle events. The
+callback will be invoked whenever some events have been handled. You can
+set the callback to <code>0</code> to avoid having to specify one if you are not
+interested in that.</p>
+<p>Also, there have not currently been made special provisions for forking:
+when you fork, you not only have to call <code>ev_loop_fork</code> on both loops,
+but you will also have to stop and restart any <code>ev_embed</code> watchers
+yourself.</p>
+<p>Unfortunately, not all backends are embeddable, only the ones returned by
+<code>ev_embeddable_backends</code> are, which, unfortunately, does not include any
+portable one.</p>
+<p>So when you want to use this feature you will always have to be prepared
+that you cannot get an embeddable loop. The recommended way to get around
+this is to have a separate variables for your embeddable loop, try to
+create it, and if that fails, use the normal loop for everything:</p>
+<pre> struct ev_loop *loop_hi = ev_default_init (0);
+ struct ev_loop *loop_lo = 0;
+ struct ev_embed embed;
+
+ // see if there is a chance of getting one that works
+ // (remember that a flags value of 0 means autodetection)
+ loop_lo = ev_embeddable_backends () & ev_recommended_backends ()
+ ? ev_loop_new (ev_embeddable_backends () & ev_recommended_backends ())
+ : 0;
+
+ // if we got one, then embed it, otherwise default to loop_hi
+ if (loop_lo)
+ {
+ ev_embed_init (&embed, 0, loop_lo);
+ ev_embed_start (loop_hi, &embed);
+ }
+ else
+ loop_lo = loop_hi;
+
+</pre>
+<dl>
+ <dt>ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop)</dt>
+ <dt>ev_embed_set (ev_embed *, callback, struct ev_loop *embedded_loop)</dt>
+ <dd>
+ <p>Configures the watcher to embed the given loop, which must be
+embeddable. If the callback is <code>0</code>, then <code>ev_embed_sweep</code> will be
+invoked automatically, otherwise it is the responsibility of the callback
+to invoke it (it will continue to be called until the sweep has been done,
+if you do not want thta, you need to temporarily stop the embed watcher).</p>
+ </dd>
+ <dt>ev_embed_sweep (loop, ev_embed *)</dt>
+ <dd>
+ <p>Make a single, non-blocking sweep over the embedded loop. This works
+similarly to <code>ev_loop (embedded_loop, EVLOOP_NONBLOCK)</code>, but in the most
+apropriate way for embedded loops.</p>
+ </dd>
+</dl>
+
+
+
+
+
projects / software / libev.git / blobdiff