ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/libev/ev.pod
(Generate patch)

Comparing libev/ev.pod (file contents):
Revision 1.61 by root, Thu Nov 29 12:21:05 2007 UTC vs.
Revision 1.83 by root, Wed Dec 12 17:55:31 2007 UTC

47 47
48 return 0; 48 return 0;
49 } 49 }
50 50
51=head1 DESCRIPTION 51=head1 DESCRIPTION
52
53The newest version of this document is also available as a html-formatted
54web page you might find easier to navigate when reading it for the first
55time: L<http://cvs.schmorp.de/libev/ev.html>.
52 56
53Libev is an event loop: you register interest in certain events (such as a 57Libev is an event loop: you register interest in certain events (such as a
54file descriptor being readable or a timeout occuring), and it will manage 58file descriptor being readable or a timeout occuring), and it will manage
55these event sources and provide your program with events. 59these event sources and provide your program with events.
56 60
113 117
114=item int ev_version_major () 118=item int ev_version_major ()
115 119
116=item int ev_version_minor () 120=item int ev_version_minor ()
117 121
118You can find out the major and minor version numbers of the library 122You can find out the major and minor ABI version numbers of the library
119you linked against by calling the functions C<ev_version_major> and 123you linked against by calling the functions C<ev_version_major> and
120C<ev_version_minor>. If you want, you can compare against the global 124C<ev_version_minor>. If you want, you can compare against the global
121symbols C<EV_VERSION_MAJOR> and C<EV_VERSION_MINOR>, which specify the 125symbols C<EV_VERSION_MAJOR> and C<EV_VERSION_MINOR>, which specify the
122version of the library your program was compiled against. 126version of the library your program was compiled against.
123 127
128These version numbers refer to the ABI version of the library, not the
129release version.
130
124Usually, it's a good idea to terminate if the major versions mismatch, 131Usually, it's a good idea to terminate if the major versions mismatch,
125as this indicates an incompatible change. Minor versions are usually 132as this indicates an incompatible change. Minor versions are usually
126compatible to older versions, so a larger minor version alone is usually 133compatible to older versions, so a larger minor version alone is usually
127not a problem. 134not a problem.
128 135
129Example: Make sure we haven't accidentally been linked against the wrong 136Example: Make sure we haven't accidentally been linked against the wrong
130version. 137version.
266C<LIBEV_FLAGS>. Otherwise (the default), this environment variable will 273C<LIBEV_FLAGS>. Otherwise (the default), this environment variable will
267override the flags completely if it is found in the environment. This is 274override the flags completely if it is found in the environment. This is
268useful to try out specific backends to test their performance, or to work 275useful to try out specific backends to test their performance, or to work
269around bugs. 276around bugs.
270 277
278=item C<EVFLAG_FORKCHECK>
279
280Instead of calling C<ev_default_fork> or C<ev_loop_fork> manually after
281a fork, you can also make libev check for a fork in each iteration by
282enabling this flag.
283
284This works by calling C<getpid ()> on every iteration of the loop,
285and thus this might slow down your event loop if you do a lot of loop
286iterations and little real work, but is usually not noticeable (on my
287Linux system for example, C<getpid> is actually a simple 5-insn sequence
288without a syscall and thus I<very> fast, but my Linux system also has
289C<pthread_atfork> which is even faster).
290
291The big advantage of this flag is that you can forget about fork (and
292forget about forgetting to tell libev about forking) when you use this
293flag.
294
295This flag setting cannot be overriden or specified in the C<LIBEV_FLAGS>
296environment variable.
297
271=item C<EVBACKEND_SELECT> (value 1, portable select backend) 298=item C<EVBACKEND_SELECT> (value 1, portable select backend)
272 299
273This is your standard select(2) backend. Not I<completely> standard, as 300This is your standard select(2) backend. Not I<completely> standard, as
274libev tries to roll its own fd_set with no limits on the number of fds, 301libev tries to roll its own fd_set with no limits on the number of fds,
275but if that fails, expect a fairly low limit on the number of fds when 302but if that fails, expect a fairly low limit on the number of fds when
410 437
411Like C<ev_default_fork>, but acts on an event loop created by 438Like C<ev_default_fork>, but acts on an event loop created by
412C<ev_loop_new>. Yes, you have to call this on every allocated event loop 439C<ev_loop_new>. Yes, you have to call this on every allocated event loop
413after fork, and how you do this is entirely your own problem. 440after fork, and how you do this is entirely your own problem.
414 441
442=item unsigned int ev_loop_count (loop)
443
444Returns the count of loop iterations for the loop, which is identical to
445the number of times libev did poll for new events. It starts at C<0> and
446happily wraps around with enough iterations.
447
448This value can sometimes be useful as a generation counter of sorts (it
449"ticks" the number of loop iterations), as it roughly corresponds with
450C<ev_prepare> and C<ev_check> calls.
451
415=item unsigned int ev_backend (loop) 452=item unsigned int ev_backend (loop)
416 453
417Returns one of the C<EVBACKEND_*> flags indicating the event backend in 454Returns one of the C<EVBACKEND_*> flags indicating the event backend in
418use. 455use.
419 456
452libev watchers. However, a pair of C<ev_prepare>/C<ev_check> watchers is 489libev watchers. However, a pair of C<ev_prepare>/C<ev_check> watchers is
453usually a better approach for this kind of thing. 490usually a better approach for this kind of thing.
454 491
455Here are the gory details of what C<ev_loop> does: 492Here are the gory details of what C<ev_loop> does:
456 493
494 - Before the first iteration, call any pending watchers.
457 * If there are no active watchers (reference count is zero), return. 495 * If there are no active watchers (reference count is zero), return.
458 - Queue prepare watchers and then call all outstanding watchers. 496 - Queue all prepare watchers and then call all outstanding watchers.
459 - If we have been forked, recreate the kernel state. 497 - If we have been forked, recreate the kernel state.
460 - Update the kernel state with all outstanding changes. 498 - Update the kernel state with all outstanding changes.
461 - Update the "event loop time". 499 - Update the "event loop time".
462 - Calculate for how long to block. 500 - Calculate for how long to block.
463 - Block the process, waiting for any events. 501 - Block the process, waiting for any events.
702=item bool ev_is_pending (ev_TYPE *watcher) 740=item bool ev_is_pending (ev_TYPE *watcher)
703 741
704Returns a true value iff the watcher is pending, (i.e. it has outstanding 742Returns a true value iff the watcher is pending, (i.e. it has outstanding
705events but its callback has not yet been invoked). As long as a watcher 743events but its callback has not yet been invoked). As long as a watcher
706is pending (but not active) you must not call an init function on it (but 744is pending (but not active) you must not call an init function on it (but
707C<ev_TYPE_set> is safe) and you must make sure the watcher is available to 745C<ev_TYPE_set> is safe), you must not change its priority, and you must
708libev (e.g. you cnanot C<free ()> it). 746make sure the watcher is available to libev (e.g. you cannot C<free ()>
747it).
709 748
710=item callback ev_cb (ev_TYPE *watcher) 749=item callback ev_cb (ev_TYPE *watcher)
711 750
712Returns the callback currently set on the watcher. 751Returns the callback currently set on the watcher.
713 752
714=item ev_cb_set (ev_TYPE *watcher, callback) 753=item ev_cb_set (ev_TYPE *watcher, callback)
715 754
716Change the callback. You can change the callback at virtually any time 755Change the callback. You can change the callback at virtually any time
717(modulo threads). 756(modulo threads).
757
758=item ev_set_priority (ev_TYPE *watcher, priority)
759
760=item int ev_priority (ev_TYPE *watcher)
761
762Set and query the priority of the watcher. The priority is a small
763integer between C<EV_MAXPRI> (default: C<2>) and C<EV_MINPRI>
764(default: C<-2>). Pending watchers with higher priority will be invoked
765before watchers with lower priority, but priority will not keep watchers
766from being executed (except for C<ev_idle> watchers).
767
768This means that priorities are I<only> used for ordering callback
769invocation after new events have been received. This is useful, for
770example, to reduce latency after idling, or more often, to bind two
771watchers on the same event and make sure one is called first.
772
773If you need to suppress invocation when higher priority events are pending
774you need to look at C<ev_idle> watchers, which provide this functionality.
775
776You I<must not> change the priority of a watcher as long as it is active or
777pending.
778
779The default priority used by watchers when no priority has been set is
780always C<0>, which is supposed to not be too high and not be too low :).
781
782Setting a priority outside the range of C<EV_MINPRI> to C<EV_MAXPRI> is
783fine, as long as you do not mind that the priority value you query might
784or might not have been adjusted to be within valid range.
785
786=item ev_invoke (loop, ev_TYPE *watcher, int revents)
787
788Invoke the C<watcher> with the given C<loop> and C<revents>. Neither
789C<loop> nor C<revents> need to be valid as long as the watcher callback
790can deal with that fact.
791
792=item int ev_clear_pending (loop, ev_TYPE *watcher)
793
794If the watcher is pending, this function returns clears its pending status
795and returns its C<revents> bitset (as if its callback was invoked). If the
796watcher isn't pending it does nothing and returns C<0>.
718 797
719=back 798=back
720 799
721 800
722=head2 ASSOCIATING CUSTOM DATA WITH A WATCHER 801=head2 ASSOCIATING CUSTOM DATA WITH A WATCHER
828it is best to always use non-blocking I/O: An extra C<read>(2) returning 907it is best to always use non-blocking I/O: An extra C<read>(2) returning
829C<EAGAIN> is far preferable to a program hanging until some data arrives. 908C<EAGAIN> is far preferable to a program hanging until some data arrives.
830 909
831If you cannot run the fd in non-blocking mode (for example you should not 910If you cannot run the fd in non-blocking mode (for example you should not
832play around with an Xlib connection), then you have to seperately re-test 911play around with an Xlib connection), then you have to seperately re-test
833wether a file descriptor is really ready with a known-to-be good interface 912whether a file descriptor is really ready with a known-to-be good interface
834such as poll (fortunately in our Xlib example, Xlib already does this on 913such as poll (fortunately in our Xlib example, Xlib already does this on
835its own, so its quite safe to use). 914its own, so its quite safe to use).
915
916=head3 The special problem of disappearing file descriptors
917
918Some backends (e.g kqueue, epoll) need to be told about closing a file
919descriptor (either by calling C<close> explicitly or by any other means,
920such as C<dup>). The reason is that you register interest in some file
921descriptor, but when it goes away, the operating system will silently drop
922this interest. If another file descriptor with the same number then is
923registered with libev, there is no efficient way to see that this is, in
924fact, a different file descriptor.
925
926To avoid having to explicitly tell libev about such cases, libev follows
927the following policy: Each time C<ev_io_set> is being called, libev
928will assume that this is potentially a new file descriptor, otherwise
929it is assumed that the file descriptor stays the same. That means that
930you I<have> to call C<ev_io_set> (or C<ev_io_init>) when you change the
931descriptor even if the file descriptor number itself did not change.
932
933This is how one would do it normally anyway, the important point is that
934the libev application should not optimise around libev but should leave
935optimisations to libev.
936
937
938=head3 Watcher-Specific Functions
836 939
837=over 4 940=over 4
838 941
839=item ev_io_init (ev_io *, callback, int fd, int events) 942=item ev_io_init (ev_io *, callback, int fd, int events)
840 943
893 ev_timer_set (&timer, after + ev_now () - ev_time (), 0.); 996 ev_timer_set (&timer, after + ev_now () - ev_time (), 0.);
894 997
895The callback is guarenteed to be invoked only when its timeout has passed, 998The callback is guarenteed to be invoked only when its timeout has passed,
896but if multiple timers become ready during the same loop iteration then 999but if multiple timers become ready during the same loop iteration then
897order of execution is undefined. 1000order of execution is undefined.
1001
1002=head3 Watcher-Specific Functions and Data Members
898 1003
899=over 4 1004=over 4
900 1005
901=item ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat) 1006=item ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat)
902 1007
998but on wallclock time (absolute time). You can tell a periodic watcher 1103but on wallclock time (absolute time). You can tell a periodic watcher
999to trigger "at" some specific point in time. For example, if you tell a 1104to trigger "at" some specific point in time. For example, if you tell a
1000periodic watcher to trigger in 10 seconds (by specifiying e.g. C<ev_now () 1105periodic watcher to trigger in 10 seconds (by specifiying e.g. C<ev_now ()
1001+ 10.>) and then reset your system clock to the last year, then it will 1106+ 10.>) and then reset your system clock to the last year, then it will
1002take a year to trigger the event (unlike an C<ev_timer>, which would trigger 1107take a year to trigger the event (unlike an C<ev_timer>, which would trigger
1003roughly 10 seconds later and of course not if you reset your system time 1108roughly 10 seconds later).
1004again).
1005 1109
1006They can also be used to implement vastly more complex timers, such as 1110They can also be used to implement vastly more complex timers, such as
1007triggering an event on eahc midnight, local time. 1111triggering an event on each midnight, local time or other, complicated,
1112rules.
1008 1113
1009As with timers, the callback is guarenteed to be invoked only when the 1114As with timers, the callback is guarenteed to be invoked only when the
1010time (C<at>) has been passed, but if multiple periodic timers become ready 1115time (C<at>) has been passed, but if multiple periodic timers become ready
1011during the same loop iteration then order of execution is undefined. 1116during the same loop iteration then order of execution is undefined.
1012 1117
1118=head3 Watcher-Specific Functions and Data Members
1119
1013=over 4 1120=over 4
1014 1121
1015=item ev_periodic_init (ev_periodic *, callback, ev_tstamp at, ev_tstamp interval, reschedule_cb) 1122=item ev_periodic_init (ev_periodic *, callback, ev_tstamp at, ev_tstamp interval, reschedule_cb)
1016 1123
1017=item ev_periodic_set (ev_periodic *, ev_tstamp after, ev_tstamp repeat, reschedule_cb) 1124=item ev_periodic_set (ev_periodic *, ev_tstamp after, ev_tstamp repeat, reschedule_cb)
1019Lots of arguments, lets sort it out... There are basically three modes of 1126Lots of arguments, lets sort it out... There are basically three modes of
1020operation, and we will explain them from simplest to complex: 1127operation, and we will explain them from simplest to complex:
1021 1128
1022=over 4 1129=over 4
1023 1130
1024=item * absolute timer (interval = reschedule_cb = 0) 1131=item * absolute timer (at = time, interval = reschedule_cb = 0)
1025 1132
1026In this configuration the watcher triggers an event at the wallclock time 1133In this configuration the watcher triggers an event at the wallclock time
1027C<at> and doesn't repeat. It will not adjust when a time jump occurs, 1134C<at> and doesn't repeat. It will not adjust when a time jump occurs,
1028that is, if it is to be run at January 1st 2011 then it will run when the 1135that is, if it is to be run at January 1st 2011 then it will run when the
1029system time reaches or surpasses this time. 1136system time reaches or surpasses this time.
1030 1137
1031=item * non-repeating interval timer (interval > 0, reschedule_cb = 0) 1138=item * non-repeating interval timer (at = offset, interval > 0, reschedule_cb = 0)
1032 1139
1033In this mode the watcher will always be scheduled to time out at the next 1140In this mode the watcher will always be scheduled to time out at the next
1034C<at + N * interval> time (for some integer N) and then repeat, regardless 1141C<at + N * interval> time (for some integer N, which can also be negative)
1035of any time jumps. 1142and then repeat, regardless of any time jumps.
1036 1143
1037This can be used to create timers that do not drift with respect to system 1144This can be used to create timers that do not drift with respect to system
1038time: 1145time:
1039 1146
1040 ev_periodic_set (&periodic, 0., 3600., 0); 1147 ev_periodic_set (&periodic, 0., 3600., 0);
1046 1153
1047Another way to think about it (for the mathematically inclined) is that 1154Another way to think about it (for the mathematically inclined) is that
1048C<ev_periodic> will try to run the callback in this mode at the next possible 1155C<ev_periodic> will try to run the callback in this mode at the next possible
1049time where C<time = at (mod interval)>, regardless of any time jumps. 1156time where C<time = at (mod interval)>, regardless of any time jumps.
1050 1157
1158For numerical stability it is preferable that the C<at> value is near
1159C<ev_now ()> (the current time), but there is no range requirement for
1160this value.
1161
1051=item * manual reschedule mode (reschedule_cb = callback) 1162=item * manual reschedule mode (at and interval ignored, reschedule_cb = callback)
1052 1163
1053In this mode the values for C<interval> and C<at> are both being 1164In this mode the values for C<interval> and C<at> are both being
1054ignored. Instead, each time the periodic watcher gets scheduled, the 1165ignored. Instead, each time the periodic watcher gets scheduled, the
1055reschedule callback will be called with the watcher as first, and the 1166reschedule callback will be called with the watcher as first, and the
1056current time as second argument. 1167current time as second argument.
1057 1168
1058NOTE: I<This callback MUST NOT stop or destroy any periodic watcher, 1169NOTE: I<This callback MUST NOT stop or destroy any periodic watcher,
1059ever, or make any event loop modifications>. If you need to stop it, 1170ever, or make any event loop modifications>. If you need to stop it,
1060return C<now + 1e30> (or so, fudge fudge) and stop it afterwards (e.g. by 1171return C<now + 1e30> (or so, fudge fudge) and stop it afterwards (e.g. by
1061starting a prepare watcher). 1172starting an C<ev_prepare> watcher, which is legal).
1062 1173
1063Its prototype is C<ev_tstamp (*reschedule_cb)(struct ev_periodic *w, 1174Its prototype is C<ev_tstamp (*reschedule_cb)(struct ev_periodic *w,
1064ev_tstamp now)>, e.g.: 1175ev_tstamp now)>, e.g.:
1065 1176
1066 static ev_tstamp my_rescheduler (struct ev_periodic *w, ev_tstamp now) 1177 static ev_tstamp my_rescheduler (struct ev_periodic *w, ev_tstamp now)
1088 1199
1089Simply stops and restarts the periodic watcher again. This is only useful 1200Simply stops and restarts the periodic watcher again. This is only useful
1090when you changed some parameters or the reschedule callback would return 1201when you changed some parameters or the reschedule callback would return
1091a different time than the last time it was called (e.g. in a crond like 1202a different time than the last time it was called (e.g. in a crond like
1092program when the crontabs have changed). 1203program when the crontabs have changed).
1204
1205=item ev_tstamp offset [read-write]
1206
1207When repeating, this contains the offset value, otherwise this is the
1208absolute point in time (the C<at> value passed to C<ev_periodic_set>).
1209
1210Can be modified any time, but changes only take effect when the periodic
1211timer fires or C<ev_periodic_again> is being called.
1093 1212
1094=item ev_tstamp interval [read-write] 1213=item ev_tstamp interval [read-write]
1095 1214
1096The current interval value. Can be modified any time, but changes only 1215The current interval value. Can be modified any time, but changes only
1097take effect when the periodic timer fires or C<ev_periodic_again> is being 1216take effect when the periodic timer fires or C<ev_periodic_again> is being
1151with the kernel (thus it coexists with your own signal handlers as long 1270with the kernel (thus it coexists with your own signal handlers as long
1152as you don't register any with libev). Similarly, when the last signal 1271as you don't register any with libev). Similarly, when the last signal
1153watcher for a signal is stopped libev will reset the signal handler to 1272watcher for a signal is stopped libev will reset the signal handler to
1154SIG_DFL (regardless of what it was set to before). 1273SIG_DFL (regardless of what it was set to before).
1155 1274
1275=head3 Watcher-Specific Functions and Data Members
1276
1156=over 4 1277=over 4
1157 1278
1158=item ev_signal_init (ev_signal *, callback, int signum) 1279=item ev_signal_init (ev_signal *, callback, int signum)
1159 1280
1160=item ev_signal_set (ev_signal *, int signum) 1281=item ev_signal_set (ev_signal *, int signum)
1171 1292
1172=head2 C<ev_child> - watch out for process status changes 1293=head2 C<ev_child> - watch out for process status changes
1173 1294
1174Child watchers trigger when your process receives a SIGCHLD in response to 1295Child watchers trigger when your process receives a SIGCHLD in response to
1175some child status changes (most typically when a child of yours dies). 1296some child status changes (most typically when a child of yours dies).
1297
1298=head3 Watcher-Specific Functions and Data Members
1176 1299
1177=over 4 1300=over 4
1178 1301
1179=item ev_child_init (ev_child *, callback, int pid) 1302=item ev_child_init (ev_child *, callback, int pid)
1180 1303
1248reader). Inotify will be used to give hints only and should not change the 1371reader). Inotify will be used to give hints only and should not change the
1249semantics of C<ev_stat> watchers, which means that libev sometimes needs 1372semantics of C<ev_stat> watchers, which means that libev sometimes needs
1250to fall back to regular polling again even with inotify, but changes are 1373to fall back to regular polling again even with inotify, but changes are
1251usually detected immediately, and if the file exists there will be no 1374usually detected immediately, and if the file exists there will be no
1252polling. 1375polling.
1376
1377=head3 Watcher-Specific Functions and Data Members
1253 1378
1254=over 4 1379=over 4
1255 1380
1256=item ev_stat_init (ev_stat *, callback, const char *path, ev_tstamp interval) 1381=item ev_stat_init (ev_stat *, callback, const char *path, ev_tstamp interval)
1257 1382
1321 ev_stat_start (loop, &passwd); 1446 ev_stat_start (loop, &passwd);
1322 1447
1323 1448
1324=head2 C<ev_idle> - when you've got nothing better to do... 1449=head2 C<ev_idle> - when you've got nothing better to do...
1325 1450
1326Idle watchers trigger events when there are no other events are pending 1451Idle watchers trigger events when no other events of the same or higher
1327(prepare, check and other idle watchers do not count). That is, as long 1452priority are pending (prepare, check and other idle watchers do not
1328as your process is busy handling sockets or timeouts (or even signals, 1453count).
1329imagine) it will not be triggered. But when your process is idle all idle 1454
1330watchers are being called again and again, once per event loop iteration - 1455That is, as long as your process is busy handling sockets or timeouts
1456(or even signals, imagine) of the same or higher priority it will not be
1457triggered. But when your process is idle (or only lower-priority watchers
1458are pending), the idle watchers are being called once per event loop
1331until stopped, that is, or your process receives more events and becomes 1459iteration - until stopped, that is, or your process receives more events
1332busy. 1460and becomes busy again with higher priority stuff.
1333 1461
1334The most noteworthy effect is that as long as any idle watchers are 1462The most noteworthy effect is that as long as any idle watchers are
1335active, the process will not block when waiting for new events. 1463active, the process will not block when waiting for new events.
1336 1464
1337Apart from keeping your process non-blocking (which is a useful 1465Apart from keeping your process non-blocking (which is a useful
1338effect on its own sometimes), idle watchers are a good place to do 1466effect on its own sometimes), idle watchers are a good place to do
1339"pseudo-background processing", or delay processing stuff to after the 1467"pseudo-background processing", or delay processing stuff to after the
1340event loop has handled all outstanding events. 1468event loop has handled all outstanding events.
1469
1470=head3 Watcher-Specific Functions and Data Members
1341 1471
1342=over 4 1472=over 4
1343 1473
1344=item ev_idle_init (ev_signal *, callback) 1474=item ev_idle_init (ev_signal *, callback)
1345 1475
1403with priority higher than or equal to the event loop and one coroutine 1533with priority higher than or equal to the event loop and one coroutine
1404of lower priority, but only once, using idle watchers to keep the event 1534of lower priority, but only once, using idle watchers to keep the event
1405loop from blocking if lower-priority coroutines are active, thus mapping 1535loop from blocking if lower-priority coroutines are active, thus mapping
1406low-priority coroutines to idle/background tasks). 1536low-priority coroutines to idle/background tasks).
1407 1537
1538It is recommended to give C<ev_check> watchers highest (C<EV_MAXPRI>)
1539priority, to ensure that they are being run before any other watchers
1540after the poll. Also, C<ev_check> watchers (and C<ev_prepare> watchers,
1541too) should not activate ("feed") events into libev. While libev fully
1542supports this, they will be called before other C<ev_check> watchers did
1543their job. As C<ev_check> watchers are often used to embed other event
1544loops those other event loops might be in an unusable state until their
1545C<ev_check> watcher ran (always remind yourself to coexist peacefully with
1546others).
1547
1548=head3 Watcher-Specific Functions and Data Members
1549
1408=over 4 1550=over 4
1409 1551
1410=item ev_prepare_init (ev_prepare *, callback) 1552=item ev_prepare_init (ev_prepare *, callback)
1411 1553
1412=item ev_check_init (ev_check *, callback) 1554=item ev_check_init (ev_check *, callback)
1415parameters of any kind. There are C<ev_prepare_set> and C<ev_check_set> 1557parameters of any kind. There are C<ev_prepare_set> and C<ev_check_set>
1416macros, but using them is utterly, utterly and completely pointless. 1558macros, but using them is utterly, utterly and completely pointless.
1417 1559
1418=back 1560=back
1419 1561
1420Example: To include a library such as adns, you would add IO watchers 1562There are a number of principal ways to embed other event loops or modules
1421and a timeout watcher in a prepare handler, as required by libadns, and 1563into libev. Here are some ideas on how to include libadns into libev
1564(there is a Perl module named C<EV::ADNS> that does this, which you could
1565use for an actually working example. Another Perl module named C<EV::Glib>
1566embeds a Glib main context into libev, and finally, C<Glib::EV> embeds EV
1567into the Glib event loop).
1568
1569Method 1: Add IO watchers and a timeout watcher in a prepare handler,
1422in a check watcher, destroy them and call into libadns. What follows is 1570and in a check watcher, destroy them and call into libadns. What follows
1423pseudo-code only of course: 1571is pseudo-code only of course. This requires you to either use a low
1572priority for the check watcher or use C<ev_clear_pending> explicitly, as
1573the callbacks for the IO/timeout watchers might not have been called yet.
1424 1574
1425 static ev_io iow [nfd]; 1575 static ev_io iow [nfd];
1426 static ev_timer tw; 1576 static ev_timer tw;
1427 1577
1428 static void 1578 static void
1429 io_cb (ev_loop *loop, ev_io *w, int revents) 1579 io_cb (ev_loop *loop, ev_io *w, int revents)
1430 { 1580 {
1431 // set the relevant poll flags
1432 // could also call adns_processreadable etc. here
1433 struct pollfd *fd = (struct pollfd *)w->data;
1434 if (revents & EV_READ ) fd->revents |= fd->events & POLLIN;
1435 if (revents & EV_WRITE) fd->revents |= fd->events & POLLOUT;
1436 } 1581 }
1437 1582
1438 // create io watchers for each fd and a timer before blocking 1583 // create io watchers for each fd and a timer before blocking
1439 static void 1584 static void
1440 adns_prepare_cb (ev_loop *loop, ev_prepare *w, int revents) 1585 adns_prepare_cb (ev_loop *loop, ev_prepare *w, int revents)
1441 { 1586 {
1442 int timeout = 3600000;truct pollfd fds [nfd]; 1587 int timeout = 3600000;
1588 struct pollfd fds [nfd];
1443 // actual code will need to loop here and realloc etc. 1589 // actual code will need to loop here and realloc etc.
1444 adns_beforepoll (ads, fds, &nfd, &timeout, timeval_from (ev_time ())); 1590 adns_beforepoll (ads, fds, &nfd, &timeout, timeval_from (ev_time ()));
1445 1591
1446 /* the callback is illegal, but won't be called as we stop during check */ 1592 /* the callback is illegal, but won't be called as we stop during check */
1447 ev_timer_init (&tw, 0, timeout * 1e-3); 1593 ev_timer_init (&tw, 0, timeout * 1e-3);
1448 ev_timer_start (loop, &tw); 1594 ev_timer_start (loop, &tw);
1449 1595
1450 // create on ev_io per pollfd 1596 // create one ev_io per pollfd
1451 for (int i = 0; i < nfd; ++i) 1597 for (int i = 0; i < nfd; ++i)
1452 { 1598 {
1453 ev_io_init (iow + i, io_cb, fds [i].fd, 1599 ev_io_init (iow + i, io_cb, fds [i].fd,
1454 ((fds [i].events & POLLIN ? EV_READ : 0) 1600 ((fds [i].events & POLLIN ? EV_READ : 0)
1455 | (fds [i].events & POLLOUT ? EV_WRITE : 0))); 1601 | (fds [i].events & POLLOUT ? EV_WRITE : 0)));
1456 1602
1457 fds [i].revents = 0; 1603 fds [i].revents = 0;
1458 iow [i].data = fds + i;
1459 ev_io_start (loop, iow + i); 1604 ev_io_start (loop, iow + i);
1460 } 1605 }
1461 } 1606 }
1462 1607
1463 // stop all watchers after blocking 1608 // stop all watchers after blocking
1465 adns_check_cb (ev_loop *loop, ev_check *w, int revents) 1610 adns_check_cb (ev_loop *loop, ev_check *w, int revents)
1466 { 1611 {
1467 ev_timer_stop (loop, &tw); 1612 ev_timer_stop (loop, &tw);
1468 1613
1469 for (int i = 0; i < nfd; ++i) 1614 for (int i = 0; i < nfd; ++i)
1615 {
1616 // set the relevant poll flags
1617 // could also call adns_processreadable etc. here
1618 struct pollfd *fd = fds + i;
1619 int revents = ev_clear_pending (iow + i);
1620 if (revents & EV_READ ) fd->revents |= fd->events & POLLIN;
1621 if (revents & EV_WRITE) fd->revents |= fd->events & POLLOUT;
1622
1623 // now stop the watcher
1470 ev_io_stop (loop, iow + i); 1624 ev_io_stop (loop, iow + i);
1625 }
1471 1626
1472 adns_afterpoll (adns, fds, nfd, timeval_from (ev_now (loop)); 1627 adns_afterpoll (adns, fds, nfd, timeval_from (ev_now (loop));
1628 }
1629
1630Method 2: This would be just like method 1, but you run C<adns_afterpoll>
1631in the prepare watcher and would dispose of the check watcher.
1632
1633Method 3: If the module to be embedded supports explicit event
1634notification (adns does), you can also make use of the actual watcher
1635callbacks, and only destroy/create the watchers in the prepare watcher.
1636
1637 static void
1638 timer_cb (EV_P_ ev_timer *w, int revents)
1639 {
1640 adns_state ads = (adns_state)w->data;
1641 update_now (EV_A);
1642
1643 adns_processtimeouts (ads, &tv_now);
1644 }
1645
1646 static void
1647 io_cb (EV_P_ ev_io *w, int revents)
1648 {
1649 adns_state ads = (adns_state)w->data;
1650 update_now (EV_A);
1651
1652 if (revents & EV_READ ) adns_processreadable (ads, w->fd, &tv_now);
1653 if (revents & EV_WRITE) adns_processwriteable (ads, w->fd, &tv_now);
1654 }
1655
1656 // do not ever call adns_afterpoll
1657
1658Method 4: Do not use a prepare or check watcher because the module you
1659want to embed is too inflexible to support it. Instead, youc na override
1660their poll function. The drawback with this solution is that the main
1661loop is now no longer controllable by EV. The C<Glib::EV> module does
1662this.
1663
1664 static gint
1665 event_poll_func (GPollFD *fds, guint nfds, gint timeout)
1666 {
1667 int got_events = 0;
1668
1669 for (n = 0; n < nfds; ++n)
1670 // create/start io watcher that sets the relevant bits in fds[n] and increment got_events
1671
1672 if (timeout >= 0)
1673 // create/start timer
1674
1675 // poll
1676 ev_loop (EV_A_ 0);
1677
1678 // stop timer again
1679 if (timeout >= 0)
1680 ev_timer_stop (EV_A_ &to);
1681
1682 // stop io watchers again - their callbacks should have set
1683 for (n = 0; n < nfds; ++n)
1684 ev_io_stop (EV_A_ iow [n]);
1685
1686 return got_events;
1473 } 1687 }
1474 1688
1475 1689
1476=head2 C<ev_embed> - when one backend isn't enough... 1690=head2 C<ev_embed> - when one backend isn't enough...
1477 1691
1541 ev_embed_start (loop_hi, &embed); 1755 ev_embed_start (loop_hi, &embed);
1542 } 1756 }
1543 else 1757 else
1544 loop_lo = loop_hi; 1758 loop_lo = loop_hi;
1545 1759
1760=head3 Watcher-Specific Functions and Data Members
1761
1546=over 4 1762=over 4
1547 1763
1548=item ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop) 1764=item ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop)
1549 1765
1550=item ev_embed_set (ev_embed *, callback, struct ev_loop *embedded_loop) 1766=item ev_embed_set (ev_embed *, callback, struct ev_loop *embedded_loop)
1576event loop blocks next and before C<ev_check> watchers are being called, 1792event loop blocks next and before C<ev_check> watchers are being called,
1577and only in the child after the fork. If whoever good citizen calling 1793and only in the child after the fork. If whoever good citizen calling
1578C<ev_default_fork> cheats and calls it in the wrong process, the fork 1794C<ev_default_fork> cheats and calls it in the wrong process, the fork
1579handlers will be invoked, too, of course. 1795handlers will be invoked, too, of course.
1580 1796
1797=head3 Watcher-Specific Functions and Data Members
1798
1581=over 4 1799=over 4
1582 1800
1583=item ev_fork_init (ev_signal *, callback) 1801=item ev_fork_init (ev_signal *, callback)
1584 1802
1585Initialises and configures the fork watcher - it has no parameters of any 1803Initialises and configures the fork watcher - it has no parameters of any
1681 1899
1682To use it, 1900To use it,
1683 1901
1684 #include <ev++.h> 1902 #include <ev++.h>
1685 1903
1686(it is not installed by default). This automatically includes F<ev.h> 1904This automatically includes F<ev.h> and puts all of its definitions (many
1687and puts all of its definitions (many of them macros) into the global 1905of them macros) into the global namespace. All C++ specific things are
1688namespace. All C++ specific things are put into the C<ev> namespace. 1906put into the C<ev> namespace. It should support all the same embedding
1907options as F<ev.h>, most notably C<EV_MULTIPLICITY>.
1689 1908
1690It should support all the same embedding options as F<ev.h>, most notably 1909Care has been taken to keep the overhead low. The only data member the C++
1691C<EV_MULTIPLICITY>. 1910classes add (compared to plain C-style watchers) is the event loop pointer
1911that the watcher is associated with (or no additional members at all if
1912you disable C<EV_MULTIPLICITY> when embedding libev).
1913
1914Currently, functions, and static and non-static member functions can be
1915used as callbacks. Other types should be easy to add as long as they only
1916need one additional pointer for context. If you need support for other
1917types of functors please contact the author (preferably after implementing
1918it).
1692 1919
1693Here is a list of things available in the C<ev> namespace: 1920Here is a list of things available in the C<ev> namespace:
1694 1921
1695=over 4 1922=over 4
1696 1923
1712 1939
1713All of those classes have these methods: 1940All of those classes have these methods:
1714 1941
1715=over 4 1942=over 4
1716 1943
1717=item ev::TYPE::TYPE (object *, object::method *) 1944=item ev::TYPE::TYPE ()
1718 1945
1719=item ev::TYPE::TYPE (object *, object::method *, struct ev_loop *) 1946=item ev::TYPE::TYPE (struct ev_loop *)
1720 1947
1721=item ev::TYPE::~TYPE 1948=item ev::TYPE::~TYPE
1722 1949
1723The constructor takes a pointer to an object and a method pointer to 1950The constructor (optionally) takes an event loop to associate the watcher
1724the event handler callback to call in this class. The constructor calls 1951with. If it is omitted, it will use C<EV_DEFAULT>.
1725C<ev_init> for you, which means you have to call the C<set> method 1952
1726before starting it. If you do not specify a loop then the constructor 1953The constructor calls C<ev_init> for you, which means you have to call the
1727automatically associates the default loop with this watcher. 1954C<set> method before starting it.
1955
1956It will not set a callback, however: You have to call the templated C<set>
1957method to set a callback before you can start the watcher.
1958
1959(The reason why you have to use a method is a limitation in C++ which does
1960not allow explicit template arguments for constructors).
1728 1961
1729The destructor automatically stops the watcher if it is active. 1962The destructor automatically stops the watcher if it is active.
1963
1964=item w->set<class, &class::method> (object *)
1965
1966This method sets the callback method to call. The method has to have a
1967signature of C<void (*)(ev_TYPE &, int)>, it receives the watcher as
1968first argument and the C<revents> as second. The object must be given as
1969parameter and is stored in the C<data> member of the watcher.
1970
1971This method synthesizes efficient thunking code to call your method from
1972the C callback that libev requires. If your compiler can inline your
1973callback (i.e. it is visible to it at the place of the C<set> call and
1974your compiler is good :), then the method will be fully inlined into the
1975thunking function, making it as fast as a direct C callback.
1976
1977Example: simple class declaration and watcher initialisation
1978
1979 struct myclass
1980 {
1981 void io_cb (ev::io &w, int revents) { }
1982 }
1983
1984 myclass obj;
1985 ev::io iow;
1986 iow.set <myclass, &myclass::io_cb> (&obj);
1987
1988=item w->set<function> (void *data = 0)
1989
1990Also sets a callback, but uses a static method or plain function as
1991callback. The optional C<data> argument will be stored in the watcher's
1992C<data> member and is free for you to use.
1993
1994The prototype of the C<function> must be C<void (*)(ev::TYPE &w, int)>.
1995
1996See the method-C<set> above for more details.
1997
1998Example:
1999
2000 static void io_cb (ev::io &w, int revents) { }
2001 iow.set <io_cb> ();
1730 2002
1731=item w->set (struct ev_loop *) 2003=item w->set (struct ev_loop *)
1732 2004
1733Associates a different C<struct ev_loop> with this watcher. You can only 2005Associates a different C<struct ev_loop> with this watcher. You can only
1734do this when the watcher is inactive (and not pending either). 2006do this when the watcher is inactive (and not pending either).
1735 2007
1736=item w->set ([args]) 2008=item w->set ([args])
1737 2009
1738Basically the same as C<ev_TYPE_set>, with the same args. Must be 2010Basically the same as C<ev_TYPE_set>, with the same args. Must be
1739called at least once. Unlike the C counterpart, an active watcher gets 2011called at least once. Unlike the C counterpart, an active watcher gets
1740automatically stopped and restarted. 2012automatically stopped and restarted when reconfiguring it with this
2013method.
1741 2014
1742=item w->start () 2015=item w->start ()
1743 2016
1744Starts the watcher. Note that there is no C<loop> argument as the 2017Starts the watcher. Note that there is no C<loop> argument, as the
1745constructor already takes the loop. 2018constructor already stores the event loop.
1746 2019
1747=item w->stop () 2020=item w->stop ()
1748 2021
1749Stops the watcher if it is active. Again, no C<loop> argument. 2022Stops the watcher if it is active. Again, no C<loop> argument.
1750 2023
1775 2048
1776 myclass (); 2049 myclass ();
1777 } 2050 }
1778 2051
1779 myclass::myclass (int fd) 2052 myclass::myclass (int fd)
1780 : io (this, &myclass::io_cb),
1781 idle (this, &myclass::idle_cb)
1782 { 2053 {
2054 io .set <myclass, &myclass::io_cb > (this);
2055 idle.set <myclass, &myclass::idle_cb> (this);
2056
1783 io.start (fd, ev::READ); 2057 io.start (fd, ev::READ);
1784 } 2058 }
1785 2059
1786 2060
1787=head1 MACRO MAGIC 2061=head1 MACRO MAGIC
1788 2062
1789Libev can be compiled with a variety of options, the most fundemantal is 2063Libev can be compiled with a variety of options, the most fundemantal is
1790C<EV_MULTIPLICITY>. This option determines wether (most) functions and 2064C<EV_MULTIPLICITY>. This option determines whether (most) functions and
1791callbacks have an initial C<struct ev_loop *> argument. 2065callbacks have an initial C<struct ev_loop *> argument.
1792 2066
1793To make it easier to write programs that cope with either variant, the 2067To make it easier to write programs that cope with either variant, the
1794following macros are defined: 2068following macros are defined:
1795 2069
1828Similar to the other two macros, this gives you the value of the default 2102Similar to the other two macros, this gives you the value of the default
1829loop, if multiple loops are supported ("ev loop default"). 2103loop, if multiple loops are supported ("ev loop default").
1830 2104
1831=back 2105=back
1832 2106
1833Example: Declare and initialise a check watcher, working regardless of 2107Example: Declare and initialise a check watcher, utilising the above
1834wether multiple loops are supported or not. 2108macros so it will work regardless of whether multiple loops are supported
2109or not.
1835 2110
1836 static void 2111 static void
1837 check_cb (EV_P_ ev_timer *w, int revents) 2112 check_cb (EV_P_ ev_timer *w, int revents)
1838 { 2113 {
1839 ev_check_stop (EV_A_ w); 2114 ev_check_stop (EV_A_ w);
1841 2116
1842 ev_check check; 2117 ev_check check;
1843 ev_check_init (&check, check_cb); 2118 ev_check_init (&check, check_cb);
1844 ev_check_start (EV_DEFAULT_ &check); 2119 ev_check_start (EV_DEFAULT_ &check);
1845 ev_loop (EV_DEFAULT_ 0); 2120 ev_loop (EV_DEFAULT_ 0);
1846
1847 2121
1848=head1 EMBEDDING 2122=head1 EMBEDDING
1849 2123
1850Libev can (and often is) directly embedded into host 2124Libev can (and often is) directly embedded into host
1851applications. Examples of applications that embed it include the Deliantra 2125applications. Examples of applications that embed it include the Deliantra
1891 ev_vars.h 2165 ev_vars.h
1892 ev_wrap.h 2166 ev_wrap.h
1893 2167
1894 ev_win32.c required on win32 platforms only 2168 ev_win32.c required on win32 platforms only
1895 2169
1896 ev_select.c only when select backend is enabled (which is by default) 2170 ev_select.c only when select backend is enabled (which is enabled by default)
1897 ev_poll.c only when poll backend is enabled (disabled by default) 2171 ev_poll.c only when poll backend is enabled (disabled by default)
1898 ev_epoll.c only when the epoll backend is enabled (disabled by default) 2172 ev_epoll.c only when the epoll backend is enabled (disabled by default)
1899 ev_kqueue.c only when the kqueue backend is enabled (disabled by default) 2173 ev_kqueue.c only when the kqueue backend is enabled (disabled by default)
1900 ev_port.c only when the solaris port backend is enabled (disabled by default) 2174 ev_port.c only when the solaris port backend is enabled (disabled by default)
1901 2175
2064will have the C<struct ev_loop *> as first argument, and you can create 2338will have the C<struct ev_loop *> as first argument, and you can create
2065additional independent event loops. Otherwise there will be no support 2339additional independent event loops. Otherwise there will be no support
2066for multiple event loops and there is no first event loop pointer 2340for multiple event loops and there is no first event loop pointer
2067argument. Instead, all functions act on the single default loop. 2341argument. Instead, all functions act on the single default loop.
2068 2342
2343=item EV_MINPRI
2344
2345=item EV_MAXPRI
2346
2347The range of allowed priorities. C<EV_MINPRI> must be smaller or equal to
2348C<EV_MAXPRI>, but otherwise there are no non-obvious limitations. You can
2349provide for more priorities by overriding those symbols (usually defined
2350to be C<-2> and C<2>, respectively).
2351
2352When doing priority-based operations, libev usually has to linearly search
2353all the priorities, so having many of them (hundreds) uses a lot of space
2354and time, so using the defaults of five priorities (-2 .. +2) is usually
2355fine.
2356
2357If your embedding app does not need any priorities, defining these both to
2358C<0> will save some memory and cpu.
2359
2069=item EV_PERIODIC_ENABLE 2360=item EV_PERIODIC_ENABLE
2070 2361
2071If undefined or defined to be C<1>, then periodic timers are supported. If 2362If undefined or defined to be C<1>, then periodic timers are supported. If
2363defined to be C<0>, then they are not. Disabling them saves a few kB of
2364code.
2365
2366=item EV_IDLE_ENABLE
2367
2368If undefined or defined to be C<1>, then idle watchers are supported. If
2072defined to be C<0>, then they are not. Disabling them saves a few kB of 2369defined to be C<0>, then they are not. Disabling them saves a few kB of
2073code. 2370code.
2074 2371
2075=item EV_EMBED_ENABLE 2372=item EV_EMBED_ENABLE
2076 2373
2143interface) and F<EV.xs> (implementation) files. Only the F<EV.xs> file 2440interface) and F<EV.xs> (implementation) files. Only the F<EV.xs> file
2144will be compiled. It is pretty complex because it provides its own header 2441will be compiled. It is pretty complex because it provides its own header
2145file. 2442file.
2146 2443
2147The usage in rxvt-unicode is simpler. It has a F<ev_cpp.h> header file 2444The usage in rxvt-unicode is simpler. It has a F<ev_cpp.h> header file
2148that everybody includes and which overrides some autoconf choices: 2445that everybody includes and which overrides some configure choices:
2149 2446
2447 #define EV_MINIMAL 1
2150 #define EV_USE_POLL 0 2448 #define EV_USE_POLL 0
2151 #define EV_MULTIPLICITY 0 2449 #define EV_MULTIPLICITY 0
2152 #define EV_PERIODICS 0 2450 #define EV_PERIODIC_ENABLE 0
2451 #define EV_STAT_ENABLE 0
2452 #define EV_FORK_ENABLE 0
2153 #define EV_CONFIG_H <config.h> 2453 #define EV_CONFIG_H <config.h>
2454 #define EV_MINPRI 0
2455 #define EV_MAXPRI 0
2154 2456
2155 #include "ev++.h" 2457 #include "ev++.h"
2156 2458
2157And a F<ev_cpp.C> implementation file that contains libev proper and is compiled: 2459And a F<ev_cpp.C> implementation file that contains libev proper and is compiled:
2158 2460
2164 2466
2165In this section the complexities of (many of) the algorithms used inside 2467In this section the complexities of (many of) the algorithms used inside
2166libev will be explained. For complexity discussions about backends see the 2468libev will be explained. For complexity discussions about backends see the
2167documentation for C<ev_default_init>. 2469documentation for C<ev_default_init>.
2168 2470
2471All of the following are about amortised time: If an array needs to be
2472extended, libev needs to realloc and move the whole array, but this
2473happens asymptotically never with higher number of elements, so O(1) might
2474mean it might do a lengthy realloc operation in rare cases, but on average
2475it is much faster and asymptotically approaches constant time.
2476
2169=over 4 2477=over 4
2170 2478
2171=item Starting and stopping timer/periodic watchers: O(log skipped_other_timers) 2479=item Starting and stopping timer/periodic watchers: O(log skipped_other_timers)
2172 2480
2481This means that, when you have a watcher that triggers in one hour and
2482there are 100 watchers that would trigger before that then inserting will
2483have to skip those 100 watchers.
2484
2173=item Changing timer/periodic watchers (by autorepeat, again): O(log skipped_other_timers) 2485=item Changing timer/periodic watchers (by autorepeat, again): O(log skipped_other_timers)
2174 2486
2487That means that for changing a timer costs less than removing/adding them
2488as only the relative motion in the event queue has to be paid for.
2489
2175=item Starting io/check/prepare/idle/signal/child watchers: O(1) 2490=item Starting io/check/prepare/idle/signal/child watchers: O(1)
2176 2491
2492These just add the watcher into an array or at the head of a list.
2177=item Stopping check/prepare/idle watchers: O(1) 2493=item Stopping check/prepare/idle watchers: O(1)
2178 2494
2179=item Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % EV_PID_HASHSIZE)) 2495=item Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % EV_PID_HASHSIZE))
2180 2496
2497These watchers are stored in lists then need to be walked to find the
2498correct watcher to remove. The lists are usually short (you don't usually
2499have many watchers waiting for the same fd or signal).
2500
2181=item Finding the next timer per loop iteration: O(1) 2501=item Finding the next timer per loop iteration: O(1)
2182 2502
2183=item Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd) 2503=item Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd)
2184 2504
2505A change means an I/O watcher gets started or stopped, which requires
2506libev to recalculate its status (and possibly tell the kernel).
2507
2185=item Activating one watcher: O(1) 2508=item Activating one watcher: O(1)
2186 2509
2510=item Priority handling: O(number_of_priorities)
2511
2512Priorities are implemented by allocating some space for each
2513priority. When doing priority-based operations, libev usually has to
2514linearly search all the priorities.
2515
2187=back 2516=back
2188 2517
2189 2518
2190=head1 AUTHOR 2519=head1 AUTHOR
2191 2520

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines