summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--Changes3
-rw-r--r--ev.pod55
2 files changed, 58 insertions, 0 deletions
diff --git a/Changes b/Changes
index 0a2b469..6f8e7d5 100644
--- a/Changes
+++ b/Changes
@@ -1,5 +1,8 @@
Revision history for libev, a high-performance and full-featured event loop.
+TODO: move some other examples to common idioms? combining watchers,
+thread usage, coroutine switch?
+
4.01 Fri Nov 5 21:51:29 CET 2010
- automake fucked it up, apparently, --add-missing -f is not quite enough
to make it update its files, so 4.00 didn't install ev++.h and
diff --git a/ev.pod b/ev.pod
index bcea84b..a72bec9 100644
--- a/ev.pod
+++ b/ev.pod
@@ -3369,6 +3369,56 @@ loop!).
=back
+=head1 COMMON OR USEFUL IDIOMS (OR BOTH)
+
+This section explains some common idioms that are not immediately
+obvious. Note that examples are sprinkled over the whole manual, and this
+section only contains stuff that wouldn't fit anywhere else.
+
+=over 4
+
+=item Model/nested event loop invocations and exit conditions.
+
+Often (especially in GUI toolkits) there are places where you have
+I<modal> interaction, which is most easily implemented by recursively
+invoking C<ev_run>.
+
+This brings the problem of exiting - a callback might want to finish the
+main C<ev_run> call, but not the nested one (e.g. user clicked "Quit", but
+a modal "Are you sure?" dialog is still waiting), or just the nested one
+and not the main one (e.g. user clocked "Ok" in a modal dialog), or some
+other combination: In these cases, C<ev_break> will not work alone.
+
+The solution is to maintain "break this loop" variable for each C<ev_run>
+invocation, and use a loop around C<ev_run> until the condition is
+triggered, using C<EVRUN_ONCE>:
+
+ // main loop
+ int exit_main_loop = 0;
+
+ while (!exit_main_loop)
+ ev_run (EV_DEFAULT_ EVRUN_ONCE);
+
+ // in a model watcher
+ int exit_nested_loop = 0;
+
+ while (!exit_nested_loop)
+ ev_run (EV_A_ EVRUN_ONCE);
+
+To exit from any of these loops, just set the corresponding exit variable:
+
+ // exit modal loop
+ exit_nested_loop = 1;
+
+ // exit main program, after modal loop is finished
+ exit_main_loop = 1;
+
+ // exit both
+ exit_main_loop = exit_nested_loop = 1;
+
+=back
+
+
=head1 LIBEVENT EMULATION
Libev offers a compatibility emulation layer for libevent. It cannot
@@ -3376,6 +3426,11 @@ emulate the internals of libevent, so here are some usage hints:
=over 4
+=item * Only the libevent-1.4.1-beta API is being emulated.
+
+This was the newest libevent version available when libev was implemented,
+and is still mostly uncanged in 2010.
+
=item * Use it by including <event.h>, as usual.
=item * The following members are fully supported: ev_base, ev_callback,