summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--ev.315
-rw-r--r--ev.c2
-rw-r--r--ev.html16
-rw-r--r--ev.pod13
4 files changed, 39 insertions, 7 deletions
diff --git a/ev.3 b/ev.3
index 5e213b8..d7dbe2e 100644
--- a/ev.3
+++ b/ev.3
@@ -636,9 +636,10 @@ usually a better approach for this kind of thing.
.Sp
Here are the gory details of what \f(CW\*(C`ev_loop\*(C'\fR does:
.Sp
-.Vb 18
+.Vb 19
+\& - Before the first iteration, call any pending watchers.
\& * If there are no active watchers (reference count is zero), return.
-\& - Queue prepare watchers and then call all outstanding watchers.
+\& - Queue all prepare watchers and then call all outstanding watchers.
\& - If we have been forked, recreate the kernel state.
\& - Update the kernel state with all outstanding changes.
\& - Update the "event loop time".
@@ -1636,6 +1637,16 @@ with priority higher than or equal to the event loop and one coroutine
of lower priority, but only once, using idle watchers to keep the event
loop from blocking if lower-priority coroutines are active, thus mapping
low-priority coroutines to idle/background tasks).
+.PP
+It is recommended to give \f(CW\*(C`ev_check\*(C'\fR watchers highest (\f(CW\*(C`EV_MAXPRI\*(C'\fR)
+priority, to ensure that they are being run before any other watchers
+after the poll. Also, \f(CW\*(C`ev_check\*(C'\fR watchers (and \f(CW\*(C`ev_prepare\*(C'\fR watchers,
+too) should not activate (\*(L"feed\*(R") events into libev. While libev fully
+supports this, they will be called before other \f(CW\*(C`ev_check\*(C'\fR watchers did
+their job. As \f(CW\*(C`ev_check\*(C'\fR watchers are often used to embed other event
+loops those other event loops might be in an unusable state until their
+\&\f(CW\*(C`ev_check\*(C'\fR watcher ran (always remind yourself to coexist peacefully with
+others).
.IP "ev_prepare_init (ev_prepare *, callback)" 4
.IX Item "ev_prepare_init (ev_prepare *, callback)"
.PD 0
diff --git a/ev.c b/ev.c
index dbda0b9..628ccf9 100644
--- a/ev.c
+++ b/ev.c
@@ -1416,7 +1416,7 @@ ev_loop (EV_P_ int flags)
}
#endif
- /* queue check watchers (and execute them) */
+ /* queue prepare watchers (and execute them) */
if (expect_false (preparecnt))
{
queue_events (EV_A_ (W *)prepares, preparecnt, EV_PREPARE);
diff --git a/ev.html b/ev.html
index 1dcdd21..da28682 100644
--- a/ev.html
+++ b/ev.html
@@ -6,7 +6,7 @@
<meta name="description" content="Pod documentation for libev" />
<meta name="inputfile" content="&lt;standard input&gt;" />
<meta name="outputfile" content="&lt;standard output&gt;" />
- <meta name="created" content="Sat Dec 8 16:30:24 2007" />
+ <meta name="created" content="Sat Dec 8 23:11:11 2007" />
<meta name="generator" content="Pod::Xhtml 1.57" />
<link rel="stylesheet" href="http://res.tst.eu/pod.css"/></head>
<body>
@@ -531,8 +531,9 @@ external event in conjunction with something not expressible using other
libev watchers. However, a pair of <code>ev_prepare</code>/<code>ev_check</code> watchers is
usually a better approach for this kind of thing.</p>
<p>Here are the gory details of what <code>ev_loop</code> does:</p>
-<pre> * If there are no active watchers (reference count is zero), return.
- - Queue prepare watchers and then call all outstanding watchers.
+<pre> - Before the first iteration, call any pending watchers.
+ * If there are no active watchers (reference count is zero), return.
+ - Queue all prepare watchers and then call all outstanding watchers.
- If we have been forked, recreate the kernel state.
- Update the kernel state with all outstanding changes.
- Update the &quot;event loop time&quot;.
@@ -1485,6 +1486,15 @@ with priority higher than or equal to the event loop and one coroutine
of lower priority, but only once, using idle watchers to keep the event
loop from blocking if lower-priority coroutines are active, thus mapping
low-priority coroutines to idle/background tasks).</p>
+<p>It is recommended to give <code>ev_check</code> watchers highest (<code>EV_MAXPRI</code>)
+priority, to ensure that they are being run before any other watchers
+after the poll. Also, <code>ev_check</code> watchers (and <code>ev_prepare</code> watchers,
+too) should not activate (&quot;feed&quot;) events into libev. While libev fully
+supports this, they will be called before other <code>ev_check</code> watchers did
+their job. As <code>ev_check</code> watchers are often used to embed other event
+loops those other event loops might be in an unusable state until their
+<code>ev_check</code> watcher ran (always remind yourself to coexist peacefully with
+others).</p>
<dl>
<dt>ev_prepare_init (ev_prepare *, callback)</dt>
<dt>ev_check_init (ev_check *, callback)</dt>
diff --git a/ev.pod b/ev.pod
index 538b9f8..237bdb0 100644
--- a/ev.pod
+++ b/ev.pod
@@ -488,8 +488,9 @@ usually a better approach for this kind of thing.
Here are the gory details of what C<ev_loop> does:
+ - Before the first iteration, call any pending watchers.
* If there are no active watchers (reference count is zero), return.
- - Queue prepare watchers and then call all outstanding watchers.
+ - Queue all prepare watchers and then call all outstanding watchers.
- If we have been forked, recreate the kernel state.
- Update the kernel state with all outstanding changes.
- Update the "event loop time".
@@ -1483,6 +1484,16 @@ of lower priority, but only once, using idle watchers to keep the event
loop from blocking if lower-priority coroutines are active, thus mapping
low-priority coroutines to idle/background tasks).
+It is recommended to give C<ev_check> watchers highest (C<EV_MAXPRI>)
+priority, to ensure that they are being run before any other watchers
+after the poll. Also, C<ev_check> watchers (and C<ev_prepare> watchers,
+too) should not activate ("feed") events into libev. While libev fully
+supports this, they will be called before other C<ev_check> watchers did
+their job. As C<ev_check> watchers are often used to embed other event
+loops those other event loops might be in an unusable state until their
+C<ev_check> watcher ran (always remind yourself to coexist peacefully with
+others).
+
=over 4
=item ev_prepare_init (ev_prepare *, callback)