… | |
… | |
53 | The newest version of this document is also available as a html-formatted |
53 | The newest version of this document is also available as a html-formatted |
54 | web page you might find easier to navigate when reading it for the first |
54 | web page you might find easier to navigate when reading it for the first |
55 | time: L<http://cvs.schmorp.de/libev/ev.html>. |
55 | time: L<http://cvs.schmorp.de/libev/ev.html>. |
56 | |
56 | |
57 | Libev is an event loop: you register interest in certain events (such as a |
57 | Libev is an event loop: you register interest in certain events (such as a |
58 | file descriptor being readable or a timeout occuring), and it will manage |
58 | file descriptor being readable or a timeout occurring), and it will manage |
59 | these event sources and provide your program with events. |
59 | these event sources and provide your program with events. |
60 | |
60 | |
61 | To do this, it must take more or less complete control over your process |
61 | To do this, it must take more or less complete control over your process |
62 | (or thread) by executing the I<event loop> handler, and will then |
62 | (or thread) by executing the I<event loop> handler, and will then |
63 | communicate events via a callback mechanism. |
63 | communicate events via a callback mechanism. |
… | |
… | |
98 | Libev represents time as a single floating point number, representing the |
98 | Libev represents time as a single floating point number, representing the |
99 | (fractional) number of seconds since the (POSIX) epoch (somewhere near |
99 | (fractional) number of seconds since the (POSIX) epoch (somewhere near |
100 | the beginning of 1970, details are complicated, don't ask). This type is |
100 | the beginning of 1970, details are complicated, don't ask). This type is |
101 | called C<ev_tstamp>, which is what you should use too. It usually aliases |
101 | called C<ev_tstamp>, which is what you should use too. It usually aliases |
102 | to the C<double> type in C, and when you need to do any calculations on |
102 | to the C<double> type in C, and when you need to do any calculations on |
103 | it, you should treat it as such. |
103 | it, you should treat it as some floatingpoint value. Unlike the name |
|
|
104 | component C<stamp> might indicate, it is also used for time differences |
|
|
105 | throughout libev. |
104 | |
106 | |
105 | =head1 GLOBAL FUNCTIONS |
107 | =head1 GLOBAL FUNCTIONS |
106 | |
108 | |
107 | These functions can be called anytime, even before initialising the |
109 | These functions can be called anytime, even before initialising the |
108 | library in any way. |
110 | library in any way. |
… | |
… | |
117 | |
119 | |
118 | =item int ev_version_major () |
120 | =item int ev_version_major () |
119 | |
121 | |
120 | =item int ev_version_minor () |
122 | =item int ev_version_minor () |
121 | |
123 | |
122 | You can find out the major and minor API/ABI version numbers of the library |
124 | You can find out the major and minor ABI version numbers of the library |
123 | you linked against by calling the functions C<ev_version_major> and |
125 | you linked against by calling the functions C<ev_version_major> and |
124 | C<ev_version_minor>. If you want, you can compare against the global |
126 | C<ev_version_minor>. If you want, you can compare against the global |
125 | symbols C<EV_VERSION_MAJOR> and C<EV_VERSION_MINOR>, which specify the |
127 | symbols C<EV_VERSION_MAJOR> and C<EV_VERSION_MINOR>, which specify the |
126 | version of the library your program was compiled against. |
128 | version of the library your program was compiled against. |
127 | |
129 | |
128 | These version numbers refer to the API and ABI version of the library, not |
130 | These version numbers refer to the ABI version of the library, not the |
129 | the release version. |
131 | release version. |
130 | |
132 | |
131 | Usually, it's a good idea to terminate if the major versions mismatch, |
133 | Usually, it's a good idea to terminate if the major versions mismatch, |
132 | as this indicates an incompatible change. Minor versions are usually |
134 | as this indicates an incompatible change. Minor versions are usually |
133 | compatible to older versions, so a larger minor version alone is usually |
135 | compatible to older versions, so a larger minor version alone is usually |
134 | not a problem. |
136 | not a problem. |
… | |
… | |
311 | lot of inactive fds). It scales similarly to select, i.e. O(total_fds). |
313 | lot of inactive fds). It scales similarly to select, i.e. O(total_fds). |
312 | |
314 | |
313 | =item C<EVBACKEND_EPOLL> (value 4, Linux) |
315 | =item C<EVBACKEND_EPOLL> (value 4, Linux) |
314 | |
316 | |
315 | For few fds, this backend is a bit little slower than poll and select, |
317 | For few fds, this backend is a bit little slower than poll and select, |
316 | but it scales phenomenally better. While poll and select usually scale like |
318 | but it scales phenomenally better. While poll and select usually scale |
317 | O(total_fds) where n is the total number of fds (or the highest fd), epoll scales |
319 | like O(total_fds) where n is the total number of fds (or the highest fd), |
318 | either O(1) or O(active_fds). |
320 | epoll scales either O(1) or O(active_fds). The epoll design has a number |
|
|
321 | of shortcomings, such as silently dropping events in some hard-to-detect |
|
|
322 | cases and rewuiring a syscall per fd change, no fork support and bad |
|
|
323 | support for dup: |
319 | |
324 | |
320 | While stopping and starting an I/O watcher in the same iteration will |
325 | While stopping, setting and starting an I/O watcher in the same iteration |
321 | result in some caching, there is still a syscall per such incident |
326 | will result in some caching, there is still a syscall per such incident |
322 | (because the fd could point to a different file description now), so its |
327 | (because the fd could point to a different file description now), so its |
323 | best to avoid that. Also, dup()ed file descriptors might not work very |
328 | best to avoid that. Also, C<dup ()>'ed file descriptors might not work |
324 | well if you register events for both fds. |
329 | very well if you register events for both fds. |
325 | |
330 | |
326 | Please note that epoll sometimes generates spurious notifications, so you |
331 | Please note that epoll sometimes generates spurious notifications, so you |
327 | need to use non-blocking I/O or other means to avoid blocking when no data |
332 | need to use non-blocking I/O or other means to avoid blocking when no data |
328 | (or space) is available. |
333 | (or space) is available. |
329 | |
334 | |
330 | =item C<EVBACKEND_KQUEUE> (value 8, most BSD clones) |
335 | =item C<EVBACKEND_KQUEUE> (value 8, most BSD clones) |
331 | |
336 | |
332 | Kqueue deserves special mention, as at the time of this writing, it |
337 | Kqueue deserves special mention, as at the time of this writing, it |
333 | was broken on all BSDs except NetBSD (usually it doesn't work with |
338 | was broken on I<all> BSDs (usually it doesn't work with anything but |
334 | anything but sockets and pipes, except on Darwin, where of course its |
339 | sockets and pipes, except on Darwin, where of course it's completely |
|
|
340 | useless. On NetBSD, it seems to work for all the FD types I tested, so it |
335 | completely useless). For this reason its not being "autodetected" |
341 | is used by default there). For this reason it's not being "autodetected" |
336 | unless you explicitly specify it explicitly in the flags (i.e. using |
342 | unless you explicitly specify it explicitly in the flags (i.e. using |
337 | C<EVBACKEND_KQUEUE>). |
343 | C<EVBACKEND_KQUEUE>) or libev was compiled on a known-to-be-good (-enough) |
|
|
344 | system like NetBSD. |
338 | |
345 | |
339 | It scales in the same way as the epoll backend, but the interface to the |
346 | It scales in the same way as the epoll backend, but the interface to the |
340 | kernel is more efficient (which says nothing about its actual speed, of |
347 | kernel is more efficient (which says nothing about its actual speed, |
341 | course). While starting and stopping an I/O watcher does not cause an |
348 | of course). While stopping, setting and starting an I/O watcher does |
342 | extra syscall as with epoll, it still adds up to four event changes per |
349 | never cause an extra syscall as with epoll, it still adds up to two event |
343 | incident, so its best to avoid that. |
350 | changes per incident, support for C<fork ()> is very bad and it drops fds |
|
|
351 | silently in similarly hard-to-detetc cases. |
344 | |
352 | |
345 | =item C<EVBACKEND_DEVPOLL> (value 16, Solaris 8) |
353 | =item C<EVBACKEND_DEVPOLL> (value 16, Solaris 8) |
346 | |
354 | |
347 | This is not implemented yet (and might never be). |
355 | This is not implemented yet (and might never be). |
348 | |
356 | |
349 | =item C<EVBACKEND_PORT> (value 32, Solaris 10) |
357 | =item C<EVBACKEND_PORT> (value 32, Solaris 10) |
350 | |
358 | |
351 | This uses the Solaris 10 port mechanism. As with everything on Solaris, |
359 | This uses the Solaris 10 event port mechanism. As with everything on Solaris, |
352 | it's really slow, but it still scales very well (O(active_fds)). |
360 | it's really slow, but it still scales very well (O(active_fds)). |
353 | |
361 | |
354 | Please note that solaris ports can result in a lot of spurious |
362 | Please note that solaris event ports can deliver a lot of spurious |
355 | notifications, so you need to use non-blocking I/O or other means to avoid |
363 | notifications, so you need to use non-blocking I/O or other means to avoid |
356 | blocking when no data (or space) is available. |
364 | blocking when no data (or space) is available. |
357 | |
365 | |
358 | =item C<EVBACKEND_ALL> |
366 | =item C<EVBACKEND_ALL> |
359 | |
367 | |
… | |
… | |
402 | Destroys the default loop again (frees all memory and kernel state |
410 | Destroys the default loop again (frees all memory and kernel state |
403 | etc.). None of the active event watchers will be stopped in the normal |
411 | etc.). None of the active event watchers will be stopped in the normal |
404 | sense, so e.g. C<ev_is_active> might still return true. It is your |
412 | sense, so e.g. C<ev_is_active> might still return true. It is your |
405 | responsibility to either stop all watchers cleanly yoursef I<before> |
413 | responsibility to either stop all watchers cleanly yoursef I<before> |
406 | calling this function, or cope with the fact afterwards (which is usually |
414 | calling this function, or cope with the fact afterwards (which is usually |
407 | the easiest thing, youc na just ignore the watchers and/or C<free ()> them |
415 | the easiest thing, you can just ignore the watchers and/or C<free ()> them |
408 | for example). |
416 | for example). |
|
|
417 | |
|
|
418 | Note that certain global state, such as signal state, will not be freed by |
|
|
419 | this function, and related watchers (such as signal and child watchers) |
|
|
420 | would need to be stopped manually. |
|
|
421 | |
|
|
422 | In general it is not advisable to call this function except in the |
|
|
423 | rare occasion where you really need to free e.g. the signal handling |
|
|
424 | pipe fds. If you need dynamically allocated loops it is better to use |
|
|
425 | C<ev_loop_new> and C<ev_loop_destroy>). |
409 | |
426 | |
410 | =item ev_loop_destroy (loop) |
427 | =item ev_loop_destroy (loop) |
411 | |
428 | |
412 | Like C<ev_default_destroy>, but destroys an event loop created by an |
429 | Like C<ev_default_destroy>, but destroys an event loop created by an |
413 | earlier call to C<ev_loop_new>. |
430 | earlier call to C<ev_loop_new>. |
… | |
… | |
458 | |
475 | |
459 | Returns the current "event loop time", which is the time the event loop |
476 | Returns the current "event loop time", which is the time the event loop |
460 | received events and started processing them. This timestamp does not |
477 | received events and started processing them. This timestamp does not |
461 | change as long as callbacks are being processed, and this is also the base |
478 | change as long as callbacks are being processed, and this is also the base |
462 | time used for relative timers. You can treat it as the timestamp of the |
479 | time used for relative timers. You can treat it as the timestamp of the |
463 | event occuring (or more correctly, libev finding out about it). |
480 | event occurring (or more correctly, libev finding out about it). |
464 | |
481 | |
465 | =item ev_loop (loop, int flags) |
482 | =item ev_loop (loop, int flags) |
466 | |
483 | |
467 | Finally, this is it, the event handler. This function usually is called |
484 | Finally, this is it, the event handler. This function usually is called |
468 | after you initialised all your watchers and you want to start handling |
485 | after you initialised all your watchers and you want to start handling |
… | |
… | |
911 | play around with an Xlib connection), then you have to seperately re-test |
928 | play around with an Xlib connection), then you have to seperately re-test |
912 | whether a file descriptor is really ready with a known-to-be good interface |
929 | whether a file descriptor is really ready with a known-to-be good interface |
913 | such as poll (fortunately in our Xlib example, Xlib already does this on |
930 | such as poll (fortunately in our Xlib example, Xlib already does this on |
914 | its own, so its quite safe to use). |
931 | its own, so its quite safe to use). |
915 | |
932 | |
|
|
933 | =head3 The special problem of disappearing file descriptors |
|
|
934 | |
|
|
935 | Some backends (e.g. kqueue, epoll) need to be told about closing a file |
|
|
936 | descriptor (either by calling C<close> explicitly or by any other means, |
|
|
937 | such as C<dup>). The reason is that you register interest in some file |
|
|
938 | descriptor, but when it goes away, the operating system will silently drop |
|
|
939 | this interest. If another file descriptor with the same number then is |
|
|
940 | registered with libev, there is no efficient way to see that this is, in |
|
|
941 | fact, a different file descriptor. |
|
|
942 | |
|
|
943 | To avoid having to explicitly tell libev about such cases, libev follows |
|
|
944 | the following policy: Each time C<ev_io_set> is being called, libev |
|
|
945 | will assume that this is potentially a new file descriptor, otherwise |
|
|
946 | it is assumed that the file descriptor stays the same. That means that |
|
|
947 | you I<have> to call C<ev_io_set> (or C<ev_io_init>) when you change the |
|
|
948 | descriptor even if the file descriptor number itself did not change. |
|
|
949 | |
|
|
950 | This is how one would do it normally anyway, the important point is that |
|
|
951 | the libev application should not optimise around libev but should leave |
|
|
952 | optimisations to libev. |
|
|
953 | |
|
|
954 | =head3 The special problem of dup'ed file descriptors |
|
|
955 | |
|
|
956 | Some backends (e.g. epoll), cannot register events for file descriptors, |
|
|
957 | but only events for the underlying file descriptions. That menas when you |
|
|
958 | have C<dup ()>'ed file descriptors and register events for them, only one |
|
|
959 | file descriptor might actually receive events. |
|
|
960 | |
|
|
961 | There is no workaorund possible except not registering events |
|
|
962 | for potentially C<dup ()>'ed file descriptors or to resort to |
|
|
963 | C<EVBACKEND_SELECT> or C<EVBACKEND_POLL>. |
|
|
964 | |
|
|
965 | =head3 The special problem of fork |
|
|
966 | |
|
|
967 | Some backends (epoll, kqueue) do not support C<fork ()> at all or exhibit |
|
|
968 | useless behaviour. Libev fully supports fork, but needs to be told about |
|
|
969 | it in the child. |
|
|
970 | |
|
|
971 | To support fork in your programs, you either have to call |
|
|
972 | C<ev_default_fork ()> or C<ev_loop_fork ()> after a fork in the child, |
|
|
973 | enable C<EVFLAG_FORKCHECK>, or resort to C<EVBACKEND_SELECT> or |
|
|
974 | C<EVBACKEND_POLL>. |
|
|
975 | |
|
|
976 | |
|
|
977 | =head3 Watcher-Specific Functions |
|
|
978 | |
916 | =over 4 |
979 | =over 4 |
917 | |
980 | |
918 | =item ev_io_init (ev_io *, callback, int fd, int events) |
981 | =item ev_io_init (ev_io *, callback, int fd, int events) |
919 | |
982 | |
920 | =item ev_io_set (ev_io *, int fd, int events) |
983 | =item ev_io_set (ev_io *, int fd, int events) |
… | |
… | |
972 | ev_timer_set (&timer, after + ev_now () - ev_time (), 0.); |
1035 | ev_timer_set (&timer, after + ev_now () - ev_time (), 0.); |
973 | |
1036 | |
974 | The callback is guarenteed to be invoked only when its timeout has passed, |
1037 | The callback is guarenteed to be invoked only when its timeout has passed, |
975 | but if multiple timers become ready during the same loop iteration then |
1038 | but if multiple timers become ready during the same loop iteration then |
976 | order of execution is undefined. |
1039 | order of execution is undefined. |
|
|
1040 | |
|
|
1041 | =head3 Watcher-Specific Functions and Data Members |
977 | |
1042 | |
978 | =over 4 |
1043 | =over 4 |
979 | |
1044 | |
980 | =item ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat) |
1045 | =item ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat) |
981 | |
1046 | |
… | |
… | |
1087 | |
1152 | |
1088 | As with timers, the callback is guarenteed to be invoked only when the |
1153 | As with timers, the callback is guarenteed to be invoked only when the |
1089 | time (C<at>) has been passed, but if multiple periodic timers become ready |
1154 | time (C<at>) has been passed, but if multiple periodic timers become ready |
1090 | during the same loop iteration then order of execution is undefined. |
1155 | during the same loop iteration then order of execution is undefined. |
1091 | |
1156 | |
|
|
1157 | =head3 Watcher-Specific Functions and Data Members |
|
|
1158 | |
1092 | =over 4 |
1159 | =over 4 |
1093 | |
1160 | |
1094 | =item ev_periodic_init (ev_periodic *, callback, ev_tstamp at, ev_tstamp interval, reschedule_cb) |
1161 | =item ev_periodic_init (ev_periodic *, callback, ev_tstamp at, ev_tstamp interval, reschedule_cb) |
1095 | |
1162 | |
1096 | =item ev_periodic_set (ev_periodic *, ev_tstamp after, ev_tstamp repeat, reschedule_cb) |
1163 | =item ev_periodic_set (ev_periodic *, ev_tstamp after, ev_tstamp repeat, reschedule_cb) |
… | |
… | |
1191 | =item ev_tstamp (*reschedule_cb)(struct ev_periodic *w, ev_tstamp now) [read-write] |
1258 | =item ev_tstamp (*reschedule_cb)(struct ev_periodic *w, ev_tstamp now) [read-write] |
1192 | |
1259 | |
1193 | The current reschedule callback, or C<0>, if this functionality is |
1260 | The current reschedule callback, or C<0>, if this functionality is |
1194 | switched off. Can be changed any time, but changes only take effect when |
1261 | switched off. Can be changed any time, but changes only take effect when |
1195 | the periodic timer fires or C<ev_periodic_again> is being called. |
1262 | the periodic timer fires or C<ev_periodic_again> is being called. |
|
|
1263 | |
|
|
1264 | =item ev_tstamp at [read-only] |
|
|
1265 | |
|
|
1266 | When active, contains the absolute time that the watcher is supposed to |
|
|
1267 | trigger next. |
1196 | |
1268 | |
1197 | =back |
1269 | =back |
1198 | |
1270 | |
1199 | Example: Call a callback every hour, or, more precisely, whenever the |
1271 | Example: Call a callback every hour, or, more precisely, whenever the |
1200 | system clock is divisible by 3600. The callback invocation times have |
1272 | system clock is divisible by 3600. The callback invocation times have |
… | |
… | |
1242 | with the kernel (thus it coexists with your own signal handlers as long |
1314 | with the kernel (thus it coexists with your own signal handlers as long |
1243 | as you don't register any with libev). Similarly, when the last signal |
1315 | as you don't register any with libev). Similarly, when the last signal |
1244 | watcher for a signal is stopped libev will reset the signal handler to |
1316 | watcher for a signal is stopped libev will reset the signal handler to |
1245 | SIG_DFL (regardless of what it was set to before). |
1317 | SIG_DFL (regardless of what it was set to before). |
1246 | |
1318 | |
|
|
1319 | =head3 Watcher-Specific Functions and Data Members |
|
|
1320 | |
1247 | =over 4 |
1321 | =over 4 |
1248 | |
1322 | |
1249 | =item ev_signal_init (ev_signal *, callback, int signum) |
1323 | =item ev_signal_init (ev_signal *, callback, int signum) |
1250 | |
1324 | |
1251 | =item ev_signal_set (ev_signal *, int signum) |
1325 | =item ev_signal_set (ev_signal *, int signum) |
… | |
… | |
1262 | |
1336 | |
1263 | =head2 C<ev_child> - watch out for process status changes |
1337 | =head2 C<ev_child> - watch out for process status changes |
1264 | |
1338 | |
1265 | Child watchers trigger when your process receives a SIGCHLD in response to |
1339 | Child watchers trigger when your process receives a SIGCHLD in response to |
1266 | some child status changes (most typically when a child of yours dies). |
1340 | some child status changes (most typically when a child of yours dies). |
|
|
1341 | |
|
|
1342 | =head3 Watcher-Specific Functions and Data Members |
1267 | |
1343 | |
1268 | =over 4 |
1344 | =over 4 |
1269 | |
1345 | |
1270 | =item ev_child_init (ev_child *, callback, int pid) |
1346 | =item ev_child_init (ev_child *, callback, int pid) |
1271 | |
1347 | |
… | |
… | |
1339 | reader). Inotify will be used to give hints only and should not change the |
1415 | reader). Inotify will be used to give hints only and should not change the |
1340 | semantics of C<ev_stat> watchers, which means that libev sometimes needs |
1416 | semantics of C<ev_stat> watchers, which means that libev sometimes needs |
1341 | to fall back to regular polling again even with inotify, but changes are |
1417 | to fall back to regular polling again even with inotify, but changes are |
1342 | usually detected immediately, and if the file exists there will be no |
1418 | usually detected immediately, and if the file exists there will be no |
1343 | polling. |
1419 | polling. |
|
|
1420 | |
|
|
1421 | =head3 Watcher-Specific Functions and Data Members |
1344 | |
1422 | |
1345 | =over 4 |
1423 | =over 4 |
1346 | |
1424 | |
1347 | =item ev_stat_init (ev_stat *, callback, const char *path, ev_tstamp interval) |
1425 | =item ev_stat_init (ev_stat *, callback, const char *path, ev_tstamp interval) |
1348 | |
1426 | |
… | |
… | |
1431 | Apart from keeping your process non-blocking (which is a useful |
1509 | Apart from keeping your process non-blocking (which is a useful |
1432 | effect on its own sometimes), idle watchers are a good place to do |
1510 | effect on its own sometimes), idle watchers are a good place to do |
1433 | "pseudo-background processing", or delay processing stuff to after the |
1511 | "pseudo-background processing", or delay processing stuff to after the |
1434 | event loop has handled all outstanding events. |
1512 | event loop has handled all outstanding events. |
1435 | |
1513 | |
|
|
1514 | =head3 Watcher-Specific Functions and Data Members |
|
|
1515 | |
1436 | =over 4 |
1516 | =over 4 |
1437 | |
1517 | |
1438 | =item ev_idle_init (ev_signal *, callback) |
1518 | =item ev_idle_init (ev_signal *, callback) |
1439 | |
1519 | |
1440 | Initialises and configures the idle watcher - it has no parameters of any |
1520 | Initialises and configures the idle watcher - it has no parameters of any |
… | |
… | |
1507 | their job. As C<ev_check> watchers are often used to embed other event |
1587 | their job. As C<ev_check> watchers are often used to embed other event |
1508 | loops those other event loops might be in an unusable state until their |
1588 | loops those other event loops might be in an unusable state until their |
1509 | C<ev_check> watcher ran (always remind yourself to coexist peacefully with |
1589 | C<ev_check> watcher ran (always remind yourself to coexist peacefully with |
1510 | others). |
1590 | others). |
1511 | |
1591 | |
|
|
1592 | =head3 Watcher-Specific Functions and Data Members |
|
|
1593 | |
1512 | =over 4 |
1594 | =over 4 |
1513 | |
1595 | |
1514 | =item ev_prepare_init (ev_prepare *, callback) |
1596 | =item ev_prepare_init (ev_prepare *, callback) |
1515 | |
1597 | |
1516 | =item ev_check_init (ev_check *, callback) |
1598 | =item ev_check_init (ev_check *, callback) |
… | |
… | |
1652 | =head2 C<ev_embed> - when one backend isn't enough... |
1734 | =head2 C<ev_embed> - when one backend isn't enough... |
1653 | |
1735 | |
1654 | This is a rather advanced watcher type that lets you embed one event loop |
1736 | This is a rather advanced watcher type that lets you embed one event loop |
1655 | into another (currently only C<ev_io> events are supported in the embedded |
1737 | into another (currently only C<ev_io> events are supported in the embedded |
1656 | loop, other types of watchers might be handled in a delayed or incorrect |
1738 | loop, other types of watchers might be handled in a delayed or incorrect |
1657 | fashion and must not be used). |
1739 | fashion and must not be used). (See portability notes, below). |
1658 | |
1740 | |
1659 | There are primarily two reasons you would want that: work around bugs and |
1741 | There are primarily two reasons you would want that: work around bugs and |
1660 | prioritise I/O. |
1742 | prioritise I/O. |
1661 | |
1743 | |
1662 | As an example for a bug workaround, the kqueue backend might only support |
1744 | As an example for a bug workaround, the kqueue backend might only support |
… | |
… | |
1717 | ev_embed_start (loop_hi, &embed); |
1799 | ev_embed_start (loop_hi, &embed); |
1718 | } |
1800 | } |
1719 | else |
1801 | else |
1720 | loop_lo = loop_hi; |
1802 | loop_lo = loop_hi; |
1721 | |
1803 | |
|
|
1804 | =head2 Portability notes |
|
|
1805 | |
|
|
1806 | Kqueue is nominally embeddable, but this is broken on all BSDs that I |
|
|
1807 | tried, in various ways. Usually the embedded event loop will simply never |
|
|
1808 | receive events, sometimes it will only trigger a few times, sometimes in a |
|
|
1809 | loop. Epoll is also nominally embeddable, but many Linux kernel versions |
|
|
1810 | will always eport the epoll fd as ready, even when no events are pending. |
|
|
1811 | |
|
|
1812 | While libev allows embedding these backends (they are contained in |
|
|
1813 | C<ev_embeddable_backends ()>), take extreme care that it will actually |
|
|
1814 | work. |
|
|
1815 | |
|
|
1816 | When in doubt, create a dynamic event loop forced to use sockets (this |
|
|
1817 | usually works) and possibly another thread and a pipe or so to report to |
|
|
1818 | your main event loop. |
|
|
1819 | |
|
|
1820 | =head3 Watcher-Specific Functions and Data Members |
|
|
1821 | |
1722 | =over 4 |
1822 | =over 4 |
1723 | |
1823 | |
1724 | =item ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop) |
1824 | =item ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop) |
1725 | |
1825 | |
1726 | =item ev_embed_set (ev_embed *, callback, struct ev_loop *embedded_loop) |
1826 | =item ev_embed_set (ev_embed *, callback, struct ev_loop *embedded_loop) |
… | |
… | |
1735 | |
1835 | |
1736 | Make a single, non-blocking sweep over the embedded loop. This works |
1836 | Make a single, non-blocking sweep over the embedded loop. This works |
1737 | similarly to C<ev_loop (embedded_loop, EVLOOP_NONBLOCK)>, but in the most |
1837 | similarly to C<ev_loop (embedded_loop, EVLOOP_NONBLOCK)>, but in the most |
1738 | apropriate way for embedded loops. |
1838 | apropriate way for embedded loops. |
1739 | |
1839 | |
1740 | =item struct ev_loop *loop [read-only] |
1840 | =item struct ev_loop *other [read-only] |
1741 | |
1841 | |
1742 | The embedded event loop. |
1842 | The embedded event loop. |
1743 | |
1843 | |
1744 | =back |
1844 | =back |
1745 | |
1845 | |
… | |
… | |
1752 | event loop blocks next and before C<ev_check> watchers are being called, |
1852 | event loop blocks next and before C<ev_check> watchers are being called, |
1753 | and only in the child after the fork. If whoever good citizen calling |
1853 | and only in the child after the fork. If whoever good citizen calling |
1754 | C<ev_default_fork> cheats and calls it in the wrong process, the fork |
1854 | C<ev_default_fork> cheats and calls it in the wrong process, the fork |
1755 | handlers will be invoked, too, of course. |
1855 | handlers will be invoked, too, of course. |
1756 | |
1856 | |
|
|
1857 | =head3 Watcher-Specific Functions and Data Members |
|
|
1858 | |
1757 | =over 4 |
1859 | =over 4 |
1758 | |
1860 | |
1759 | =item ev_fork_init (ev_signal *, callback) |
1861 | =item ev_fork_init (ev_signal *, callback) |
1760 | |
1862 | |
1761 | Initialises and configures the fork watcher - it has no parameters of any |
1863 | Initialises and configures the fork watcher - it has no parameters of any |
… | |
… | |
1977 | |
2079 | |
1978 | =item w->stop () |
2080 | =item w->stop () |
1979 | |
2081 | |
1980 | Stops the watcher if it is active. Again, no C<loop> argument. |
2082 | Stops the watcher if it is active. Again, no C<loop> argument. |
1981 | |
2083 | |
1982 | =item w->again () C<ev::timer>, C<ev::periodic> only |
2084 | =item w->again () (C<ev::timer>, C<ev::periodic> only) |
1983 | |
2085 | |
1984 | For C<ev::timer> and C<ev::periodic>, this invokes the corresponding |
2086 | For C<ev::timer> and C<ev::periodic>, this invokes the corresponding |
1985 | C<ev_TYPE_again> function. |
2087 | C<ev_TYPE_again> function. |
1986 | |
2088 | |
1987 | =item w->sweep () C<ev::embed> only |
2089 | =item w->sweep () (C<ev::embed> only) |
1988 | |
2090 | |
1989 | Invokes C<ev_embed_sweep>. |
2091 | Invokes C<ev_embed_sweep>. |
1990 | |
2092 | |
1991 | =item w->update () C<ev::stat> only |
2093 | =item w->update () (C<ev::stat> only) |
1992 | |
2094 | |
1993 | Invokes C<ev_stat_stat>. |
2095 | Invokes C<ev_stat_stat>. |
1994 | |
2096 | |
1995 | =back |
2097 | =back |
1996 | |
2098 | |
… | |
… | |
2016 | } |
2118 | } |
2017 | |
2119 | |
2018 | |
2120 | |
2019 | =head1 MACRO MAGIC |
2121 | =head1 MACRO MAGIC |
2020 | |
2122 | |
2021 | Libev can be compiled with a variety of options, the most fundemantal is |
2123 | Libev can be compiled with a variety of options, the most fundamantal |
2022 | C<EV_MULTIPLICITY>. This option determines whether (most) functions and |
2124 | of which is C<EV_MULTIPLICITY>. This option determines whether (most) |
2023 | callbacks have an initial C<struct ev_loop *> argument. |
2125 | functions and callbacks have an initial C<struct ev_loop *> argument. |
2024 | |
2126 | |
2025 | To make it easier to write programs that cope with either variant, the |
2127 | To make it easier to write programs that cope with either variant, the |
2026 | following macros are defined: |
2128 | following macros are defined: |
2027 | |
2129 | |
2028 | =over 4 |
2130 | =over 4 |
… | |
… | |
2082 | Libev can (and often is) directly embedded into host |
2184 | Libev can (and often is) directly embedded into host |
2083 | applications. Examples of applications that embed it include the Deliantra |
2185 | applications. Examples of applications that embed it include the Deliantra |
2084 | Game Server, the EV perl module, the GNU Virtual Private Ethernet (gvpe) |
2186 | Game Server, the EV perl module, the GNU Virtual Private Ethernet (gvpe) |
2085 | and rxvt-unicode. |
2187 | and rxvt-unicode. |
2086 | |
2188 | |
2087 | The goal is to enable you to just copy the neecssary files into your |
2189 | The goal is to enable you to just copy the necessary files into your |
2088 | source directory without having to change even a single line in them, so |
2190 | source directory without having to change even a single line in them, so |
2089 | you can easily upgrade by simply copying (or having a checked-out copy of |
2191 | you can easily upgrade by simply copying (or having a checked-out copy of |
2090 | libev somewhere in your source tree). |
2192 | libev somewhere in your source tree). |
2091 | |
2193 | |
2092 | =head2 FILESETS |
2194 | =head2 FILESETS |
… | |
… | |
2182 | |
2284 | |
2183 | If defined to be C<1>, libev will try to detect the availability of the |
2285 | If defined to be C<1>, libev will try to detect the availability of the |
2184 | monotonic clock option at both compiletime and runtime. Otherwise no use |
2286 | monotonic clock option at both compiletime and runtime. Otherwise no use |
2185 | of the monotonic clock option will be attempted. If you enable this, you |
2287 | of the monotonic clock option will be attempted. If you enable this, you |
2186 | usually have to link against librt or something similar. Enabling it when |
2288 | usually have to link against librt or something similar. Enabling it when |
2187 | the functionality isn't available is safe, though, althoguh you have |
2289 | the functionality isn't available is safe, though, although you have |
2188 | to make sure you link against any libraries where the C<clock_gettime> |
2290 | to make sure you link against any libraries where the C<clock_gettime> |
2189 | function is hiding in (often F<-lrt>). |
2291 | function is hiding in (often F<-lrt>). |
2190 | |
2292 | |
2191 | =item EV_USE_REALTIME |
2293 | =item EV_USE_REALTIME |
2192 | |
2294 | |
2193 | If defined to be C<1>, libev will try to detect the availability of the |
2295 | If defined to be C<1>, libev will try to detect the availability of the |
2194 | realtime clock option at compiletime (and assume its availability at |
2296 | realtime clock option at compiletime (and assume its availability at |
2195 | runtime if successful). Otherwise no use of the realtime clock option will |
2297 | runtime if successful). Otherwise no use of the realtime clock option will |
2196 | be attempted. This effectively replaces C<gettimeofday> by C<clock_get |
2298 | be attempted. This effectively replaces C<gettimeofday> by C<clock_get |
2197 | (CLOCK_REALTIME, ...)> and will not normally affect correctness. See tzhe note about libraries |
2299 | (CLOCK_REALTIME, ...)> and will not normally affect correctness. See the |
2198 | in the description of C<EV_USE_MONOTONIC>, though. |
2300 | note about libraries in the description of C<EV_USE_MONOTONIC>, though. |
2199 | |
2301 | |
2200 | =item EV_USE_SELECT |
2302 | =item EV_USE_SELECT |
2201 | |
2303 | |
2202 | If undefined or defined to be C<1>, libev will compile in support for the |
2304 | If undefined or defined to be C<1>, libev will compile in support for the |
2203 | C<select>(2) backend. No attempt at autodetection will be done: if no |
2305 | C<select>(2) backend. No attempt at autodetection will be done: if no |
… | |
… | |
2382 | |
2484 | |
2383 | =item ev_set_cb (ev, cb) |
2485 | =item ev_set_cb (ev, cb) |
2384 | |
2486 | |
2385 | Can be used to change the callback member declaration in each watcher, |
2487 | Can be used to change the callback member declaration in each watcher, |
2386 | and the way callbacks are invoked and set. Must expand to a struct member |
2488 | and the way callbacks are invoked and set. Must expand to a struct member |
2387 | definition and a statement, respectively. See the F<ev.v> header file for |
2489 | definition and a statement, respectively. See the F<ev.h> header file for |
2388 | their default definitions. One possible use for overriding these is to |
2490 | their default definitions. One possible use for overriding these is to |
2389 | avoid the C<struct ev_loop *> as first argument in all cases, or to use |
2491 | avoid the C<struct ev_loop *> as first argument in all cases, or to use |
2390 | method calls instead of plain function calls in C++. |
2492 | method calls instead of plain function calls in C++. |
|
|
2493 | |
|
|
2494 | =head2 EXPORTED API SYMBOLS |
|
|
2495 | |
|
|
2496 | If you need to re-export the API (e.g. via a dll) and you need a list of |
|
|
2497 | exported symbols, you can use the provided F<Symbol.*> files which list |
|
|
2498 | all public symbols, one per line: |
|
|
2499 | |
|
|
2500 | Symbols.ev for libev proper |
|
|
2501 | Symbols.event for the libevent emulation |
|
|
2502 | |
|
|
2503 | This can also be used to rename all public symbols to avoid clashes with |
|
|
2504 | multiple versions of libev linked together (which is obviously bad in |
|
|
2505 | itself, but sometimes it is inconvinient to avoid this). |
|
|
2506 | |
|
|
2507 | A sed command like this will create wrapper C<#define>'s that you need to |
|
|
2508 | include before including F<ev.h>: |
|
|
2509 | |
|
|
2510 | <Symbols.ev sed -e "s/.*/#define & myprefix_&/" >wrap.h |
|
|
2511 | |
|
|
2512 | This would create a file F<wrap.h> which essentially looks like this: |
|
|
2513 | |
|
|
2514 | #define ev_backend myprefix_ev_backend |
|
|
2515 | #define ev_check_start myprefix_ev_check_start |
|
|
2516 | #define ev_check_stop myprefix_ev_check_stop |
|
|
2517 | ... |
2391 | |
2518 | |
2392 | =head2 EXAMPLES |
2519 | =head2 EXAMPLES |
2393 | |
2520 | |
2394 | For a real-world example of a program the includes libev |
2521 | For a real-world example of a program the includes libev |
2395 | verbatim, you can have a look at the EV perl module |
2522 | verbatim, you can have a look at the EV perl module |