… | |
… | |
359 | writing a server, you should C<accept ()> in a loop to accept as many |
359 | writing a server, you should C<accept ()> in a loop to accept as many |
360 | connections as possible during one iteration. You might also want to have |
360 | connections as possible during one iteration. You might also want to have |
361 | a look at C<ev_set_io_collect_interval ()> to increase the amount of |
361 | a look at C<ev_set_io_collect_interval ()> to increase the amount of |
362 | readiness notifications you get per iteration. |
362 | readiness notifications you get per iteration. |
363 | |
363 | |
|
|
364 | This backend maps C<EV_READ> to the C<readfds> set and C<EV_WRITE> to the |
|
|
365 | C<writefds> set (and to work around Microsoft Windows bugs, also onto the |
|
|
366 | C<exceptfds> set on that platform). |
|
|
367 | |
364 | =item C<EVBACKEND_POLL> (value 2, poll backend, available everywhere except on windows) |
368 | =item C<EVBACKEND_POLL> (value 2, poll backend, available everywhere except on windows) |
365 | |
369 | |
366 | And this is your standard poll(2) backend. It's more complicated |
370 | And this is your standard poll(2) backend. It's more complicated |
367 | than select, but handles sparse fds better and has no artificial |
371 | than select, but handles sparse fds better and has no artificial |
368 | limit on the number of fds you can use (except it will slow down |
372 | limit on the number of fds you can use (except it will slow down |
369 | considerably with a lot of inactive fds). It scales similarly to select, |
373 | considerably with a lot of inactive fds). It scales similarly to select, |
370 | i.e. O(total_fds). See the entry for C<EVBACKEND_SELECT>, above, for |
374 | i.e. O(total_fds). See the entry for C<EVBACKEND_SELECT>, above, for |
371 | performance tips. |
375 | performance tips. |
|
|
376 | |
|
|
377 | This backend maps C<EV_READ> to C<POLLIN | POLLERR | POLLHUP>, and |
|
|
378 | C<EV_WRITE> to C<POLLOUT | POLLERR | POLLHUP>. |
372 | |
379 | |
373 | =item C<EVBACKEND_EPOLL> (value 4, Linux) |
380 | =item C<EVBACKEND_EPOLL> (value 4, Linux) |
374 | |
381 | |
375 | For few fds, this backend is a bit little slower than poll and select, |
382 | For few fds, this backend is a bit little slower than poll and select, |
376 | but it scales phenomenally better. While poll and select usually scale |
383 | but it scales phenomenally better. While poll and select usually scale |
… | |
… | |
395 | keep at least one watcher active per fd at all times. |
402 | keep at least one watcher active per fd at all times. |
396 | |
403 | |
397 | While nominally embeddable in other event loops, this feature is broken in |
404 | While nominally embeddable in other event loops, this feature is broken in |
398 | all kernel versions tested so far. |
405 | all kernel versions tested so far. |
399 | |
406 | |
|
|
407 | This backend maps C<EV_READ> and C<EV_WRITE> in the same way as |
|
|
408 | C<EVBACKEND_POLL>. |
|
|
409 | |
400 | =item C<EVBACKEND_KQUEUE> (value 8, most BSD clones) |
410 | =item C<EVBACKEND_KQUEUE> (value 8, most BSD clones) |
401 | |
411 | |
402 | Kqueue deserves special mention, as at the time of this writing, it |
412 | Kqueue deserves special mention, as at the time of this writing, it |
403 | was broken on all BSDs except NetBSD (usually it doesn't work reliably |
413 | was broken on all BSDs except NetBSD (usually it doesn't work reliably |
404 | with anything but sockets and pipes, except on Darwin, where of course |
414 | with anything but sockets and pipes, except on Darwin, where of course |
… | |
… | |
425 | almost everywhere, you should only use it when you have a lot of sockets |
435 | almost everywhere, you should only use it when you have a lot of sockets |
426 | (for which it usually works), by embedding it into another event loop |
436 | (for which it usually works), by embedding it into another event loop |
427 | (e.g. C<EVBACKEND_SELECT> or C<EVBACKEND_POLL>) and using it only for |
437 | (e.g. C<EVBACKEND_SELECT> or C<EVBACKEND_POLL>) and using it only for |
428 | sockets. |
438 | sockets. |
429 | |
439 | |
|
|
440 | This backend maps C<EV_READ> into an C<EVFILT_READ> kevent with |
|
|
441 | C<NOTE_EOF>, and C<EV_WRITE> into an C<EVFILT_WRITE> kevent with |
|
|
442 | C<NOTE_EOF>. |
|
|
443 | |
430 | =item C<EVBACKEND_DEVPOLL> (value 16, Solaris 8) |
444 | =item C<EVBACKEND_DEVPOLL> (value 16, Solaris 8) |
431 | |
445 | |
432 | This is not implemented yet (and might never be, unless you send me an |
446 | This is not implemented yet (and might never be, unless you send me an |
433 | implementation). According to reports, C</dev/poll> only supports sockets |
447 | implementation). According to reports, C</dev/poll> only supports sockets |
434 | and is not embeddable, which would limit the usefulness of this backend |
448 | and is not embeddable, which would limit the usefulness of this backend |
… | |
… | |
449 | might perform better. |
463 | might perform better. |
450 | |
464 | |
451 | On the positive side, ignoring the spurious readiness notifications, this |
465 | On the positive side, ignoring the spurious readiness notifications, this |
452 | backend actually performed to specification in all tests and is fully |
466 | backend actually performed to specification in all tests and is fully |
453 | embeddable, which is a rare feat among the OS-specific backends. |
467 | embeddable, which is a rare feat among the OS-specific backends. |
|
|
468 | |
|
|
469 | This backend maps C<EV_READ> and C<EV_WRITE> in the same way as |
|
|
470 | C<EVBACKEND_POLL>. |
454 | |
471 | |
455 | =item C<EVBACKEND_ALL> |
472 | =item C<EVBACKEND_ALL> |
456 | |
473 | |
457 | Try all backends (even potentially broken ones that wouldn't be tried |
474 | Try all backends (even potentially broken ones that wouldn't be tried |
458 | with C<EVFLAG_AUTO>). Since this is a mask, you can do stuff such as |
475 | with C<EVFLAG_AUTO>). Since this is a mask, you can do stuff such as |
… | |
… | |
573 | received events and started processing them. This timestamp does not |
590 | received events and started processing them. This timestamp does not |
574 | change as long as callbacks are being processed, and this is also the base |
591 | change as long as callbacks are being processed, and this is also the base |
575 | time used for relative timers. You can treat it as the timestamp of the |
592 | time used for relative timers. You can treat it as the timestamp of the |
576 | event occurring (or more correctly, libev finding out about it). |
593 | event occurring (or more correctly, libev finding out about it). |
577 | |
594 | |
|
|
595 | =item ev_now_update (loop) |
|
|
596 | |
|
|
597 | Establishes the current time by querying the kernel, updating the time |
|
|
598 | returned by C<ev_now ()> in the progress. This is a costly operation and |
|
|
599 | is usually done automatically within C<ev_loop ()>. |
|
|
600 | |
|
|
601 | This function is rarely useful, but when some event callback runs for a |
|
|
602 | very long time without entering the event loop, updating libev's idea of |
|
|
603 | the current time is a good idea. |
|
|
604 | |
|
|
605 | See also "The special problem of time updates" in the C<ev_timer> section. |
|
|
606 | |
578 | =item ev_loop (loop, int flags) |
607 | =item ev_loop (loop, int flags) |
579 | |
608 | |
580 | Finally, this is it, the event handler. This function usually is called |
609 | Finally, this is it, the event handler. This function usually is called |
581 | after you initialised all your watchers and you want to start handling |
610 | after you initialised all your watchers and you want to start handling |
582 | events. |
611 | events. |
… | |
… | |
604 | |
633 | |
605 | Here are the gory details of what C<ev_loop> does: |
634 | Here are the gory details of what C<ev_loop> does: |
606 | |
635 | |
607 | - Before the first iteration, call any pending watchers. |
636 | - Before the first iteration, call any pending watchers. |
608 | * If EVFLAG_FORKCHECK was used, check for a fork. |
637 | * If EVFLAG_FORKCHECK was used, check for a fork. |
609 | - If a fork was detected, queue and call all fork watchers. |
638 | - If a fork was detected (by any means), queue and call all fork watchers. |
610 | - Queue and call all prepare watchers. |
639 | - Queue and call all prepare watchers. |
611 | - If we have been forked, recreate the kernel state. |
640 | - If we have been forked, detach and recreate the kernel state |
|
|
641 | as to not disturb the other process. |
612 | - Update the kernel state with all outstanding changes. |
642 | - Update the kernel state with all outstanding changes. |
613 | - Update the "event loop time". |
643 | - Update the "event loop time" (ev_now ()). |
614 | - Calculate for how long to sleep or block, if at all |
644 | - Calculate for how long to sleep or block, if at all |
615 | (active idle watchers, EVLOOP_NONBLOCK or not having |
645 | (active idle watchers, EVLOOP_NONBLOCK or not having |
616 | any active watchers at all will result in not sleeping). |
646 | any active watchers at all will result in not sleeping). |
617 | - Sleep if the I/O and timer collect interval say so. |
647 | - Sleep if the I/O and timer collect interval say so. |
618 | - Block the process, waiting for any events. |
648 | - Block the process, waiting for any events. |
619 | - Queue all outstanding I/O (fd) events. |
649 | - Queue all outstanding I/O (fd) events. |
620 | - Update the "event loop time" and do time jump handling. |
650 | - Update the "event loop time" (ev_now ()), and do time jump adjustments. |
621 | - Queue all outstanding timers. |
651 | - Queue all outstanding timers. |
622 | - Queue all outstanding periodics. |
652 | - Queue all outstanding periodics. |
623 | - If no events are pending now, queue all idle watchers. |
653 | - Unless any events are pending now, queue all idle watchers. |
624 | - Queue all check watchers. |
654 | - Queue all check watchers. |
625 | - Call all queued watchers in reverse order (i.e. check watchers first). |
655 | - Call all queued watchers in reverse order (i.e. check watchers first). |
626 | Signals and child watchers are implemented as I/O watchers, and will |
656 | Signals and child watchers are implemented as I/O watchers, and will |
627 | be handled here by queueing them when their watcher gets executed. |
657 | be handled here by queueing them when their watcher gets executed. |
628 | - If ev_unloop has been called, or EVLOOP_ONESHOT or EVLOOP_NONBLOCK |
658 | - If ev_unloop has been called, or EVLOOP_ONESHOT or EVLOOP_NONBLOCK |
… | |
… | |
633 | anymore. |
663 | anymore. |
634 | |
664 | |
635 | ... queue jobs here, make sure they register event watchers as long |
665 | ... queue jobs here, make sure they register event watchers as long |
636 | ... as they still have work to do (even an idle watcher will do..) |
666 | ... as they still have work to do (even an idle watcher will do..) |
637 | ev_loop (my_loop, 0); |
667 | ev_loop (my_loop, 0); |
638 | ... jobs done. yeah! |
668 | ... jobs done or somebody called unloop. yeah! |
639 | |
669 | |
640 | =item ev_unloop (loop, how) |
670 | =item ev_unloop (loop, how) |
641 | |
671 | |
642 | Can be used to make a call to C<ev_loop> return early (but only after it |
672 | Can be used to make a call to C<ev_loop> return early (but only after it |
643 | has processed all outstanding events). The C<how> argument must be either |
673 | has processed all outstanding events). The C<how> argument must be either |
… | |
… | |
679 | =item ev_set_io_collect_interval (loop, ev_tstamp interval) |
709 | =item ev_set_io_collect_interval (loop, ev_tstamp interval) |
680 | |
710 | |
681 | =item ev_set_timeout_collect_interval (loop, ev_tstamp interval) |
711 | =item ev_set_timeout_collect_interval (loop, ev_tstamp interval) |
682 | |
712 | |
683 | These advanced functions influence the time that libev will spend waiting |
713 | These advanced functions influence the time that libev will spend waiting |
684 | for events. Both are by default C<0>, meaning that libev will try to |
714 | for events. Both time intervals are by default C<0>, meaning that libev |
685 | invoke timer/periodic callbacks and I/O callbacks with minimum latency. |
715 | will try to invoke timer/periodic callbacks and I/O callbacks with minimum |
|
|
716 | latency. |
686 | |
717 | |
687 | Setting these to a higher value (the C<interval> I<must> be >= C<0>) |
718 | Setting these to a higher value (the C<interval> I<must> be >= C<0>) |
688 | allows libev to delay invocation of I/O and timer/periodic callbacks to |
719 | allows libev to delay invocation of I/O and timer/periodic callbacks |
689 | increase efficiency of loop iterations. |
720 | to increase efficiency of loop iterations (or to increase power-saving |
|
|
721 | opportunities). |
690 | |
722 | |
691 | The background is that sometimes your program runs just fast enough to |
723 | The background is that sometimes your program runs just fast enough to |
692 | handle one (or very few) event(s) per loop iteration. While this makes |
724 | handle one (or very few) event(s) per loop iteration. While this makes |
693 | the program responsive, it also wastes a lot of CPU time to poll for new |
725 | the program responsive, it also wastes a lot of CPU time to poll for new |
694 | events, especially with backends like C<select ()> which have a high |
726 | events, especially with backends like C<select ()> which have a high |
… | |
… | |
709 | Many (busy) programs can usually benefit by setting the I/O collect |
741 | Many (busy) programs can usually benefit by setting the I/O collect |
710 | interval to a value near C<0.1> or so, which is often enough for |
742 | interval to a value near C<0.1> or so, which is often enough for |
711 | interactive servers (of course not for games), likewise for timeouts. It |
743 | interactive servers (of course not for games), likewise for timeouts. It |
712 | usually doesn't make much sense to set it to a lower value than C<0.01>, |
744 | usually doesn't make much sense to set it to a lower value than C<0.01>, |
713 | as this approaches the timing granularity of most systems. |
745 | as this approaches the timing granularity of most systems. |
|
|
746 | |
|
|
747 | Setting the I<timeout collect interval> can improve the opportunity for |
|
|
748 | saving power, as the program will "bundle" timer callback invocations that |
|
|
749 | are "near" in time together, by delaying some, thus reducing the number of |
|
|
750 | times the process sleeps and wakes up again. Another useful technique to |
|
|
751 | reduce iterations/wake-ups is to use C<ev_periodic> watchers and make sure |
|
|
752 | they fire on, say, one-second boundaries only. |
714 | |
753 | |
715 | =item ev_loop_verify (loop) |
754 | =item ev_loop_verify (loop) |
716 | |
755 | |
717 | This function only does something when C<EV_VERIFY> support has been |
756 | This function only does something when C<EV_VERIFY> support has been |
718 | compiled in. It tries to go through all internal structures and checks |
757 | compiled in. It tries to go through all internal structures and checks |
… | |
… | |
984 | { |
1023 | { |
985 | struct ev_io io; |
1024 | struct ev_io io; |
986 | int otherfd; |
1025 | int otherfd; |
987 | void *somedata; |
1026 | void *somedata; |
988 | struct whatever *mostinteresting; |
1027 | struct whatever *mostinteresting; |
989 | } |
1028 | }; |
|
|
1029 | |
|
|
1030 | ... |
|
|
1031 | struct my_io w; |
|
|
1032 | ev_io_init (&w.io, my_cb, fd, EV_READ); |
990 | |
1033 | |
991 | And since your callback will be called with a pointer to the watcher, you |
1034 | And since your callback will be called with a pointer to the watcher, you |
992 | can cast it back to your own type: |
1035 | can cast it back to your own type: |
993 | |
1036 | |
994 | static void my_cb (struct ev_loop *loop, struct ev_io *w_, int revents) |
1037 | static void my_cb (struct ev_loop *loop, struct ev_io *w_, int revents) |
… | |
… | |
998 | } |
1041 | } |
999 | |
1042 | |
1000 | More interesting and less C-conformant ways of casting your callback type |
1043 | More interesting and less C-conformant ways of casting your callback type |
1001 | instead have been omitted. |
1044 | instead have been omitted. |
1002 | |
1045 | |
1003 | Another common scenario is having some data structure with multiple |
1046 | Another common scenario is to use some data structure with multiple |
1004 | watchers: |
1047 | embedded watchers: |
1005 | |
1048 | |
1006 | struct my_biggy |
1049 | struct my_biggy |
1007 | { |
1050 | { |
1008 | int some_data; |
1051 | int some_data; |
1009 | ev_timer t1; |
1052 | ev_timer t1; |
1010 | ev_timer t2; |
1053 | ev_timer t2; |
1011 | } |
1054 | } |
1012 | |
1055 | |
1013 | In this case getting the pointer to C<my_biggy> is a bit more complicated, |
1056 | In this case getting the pointer to C<my_biggy> is a bit more |
1014 | you need to use C<offsetof>: |
1057 | complicated: Either you store the address of your C<my_biggy> struct |
|
|
1058 | in the C<data> member of the watcher, or you need to use some pointer |
|
|
1059 | arithmetic using C<offsetof> inside your watchers: |
1015 | |
1060 | |
1016 | #include <stddef.h> |
1061 | #include <stddef.h> |
1017 | |
1062 | |
1018 | static void |
1063 | static void |
1019 | t1_cb (EV_P_ struct ev_timer *w, int revents) |
1064 | t1_cb (EV_P_ struct ev_timer *w, int revents) |
… | |
… | |
1124 | C<EVBACKEND_POLL>. |
1169 | C<EVBACKEND_POLL>. |
1125 | |
1170 | |
1126 | =head3 The special problem of SIGPIPE |
1171 | =head3 The special problem of SIGPIPE |
1127 | |
1172 | |
1128 | While not really specific to libev, it is easy to forget about SIGPIPE: |
1173 | While not really specific to libev, it is easy to forget about SIGPIPE: |
1129 | when reading from a pipe whose other end has been closed, your program |
1174 | when writing to a pipe whose other end has been closed, your program gets |
1130 | gets send a SIGPIPE, which, by default, aborts your program. For most |
1175 | send a SIGPIPE, which, by default, aborts your program. For most programs |
1131 | programs this is sensible behaviour, for daemons, this is usually |
1176 | this is sensible behaviour, for daemons, this is usually undesirable. |
1132 | undesirable. |
|
|
1133 | |
1177 | |
1134 | So when you encounter spurious, unexplained daemon exits, make sure you |
1178 | So when you encounter spurious, unexplained daemon exits, make sure you |
1135 | ignore SIGPIPE (and maybe make sure you log the exit status of your daemon |
1179 | ignore SIGPIPE (and maybe make sure you log the exit status of your daemon |
1136 | somewhere, as that would have given you a big clue). |
1180 | somewhere, as that would have given you a big clue). |
1137 | |
1181 | |
… | |
… | |
1188 | times out after an hour and you reset your system clock to January last |
1232 | times out after an hour and you reset your system clock to January last |
1189 | year, it will still time out after (roughly) and hour. "Roughly" because |
1233 | year, it will still time out after (roughly) and hour. "Roughly" because |
1190 | detecting time jumps is hard, and some inaccuracies are unavoidable (the |
1234 | detecting time jumps is hard, and some inaccuracies are unavoidable (the |
1191 | monotonic clock option helps a lot here). |
1235 | monotonic clock option helps a lot here). |
1192 | |
1236 | |
|
|
1237 | The callback is guaranteed to be invoked only after its timeout has passed, |
|
|
1238 | but if multiple timers become ready during the same loop iteration then |
|
|
1239 | order of execution is undefined. |
|
|
1240 | |
|
|
1241 | =head3 The special problem of time updates |
|
|
1242 | |
|
|
1243 | Establishing the current time is a costly operation (it usually takes at |
|
|
1244 | least two system calls): EV therefore updates its idea of the current |
|
|
1245 | time only before and after C<ev_loop> polls for new events, which causes |
|
|
1246 | a growing difference between C<ev_now ()> and C<ev_time ()> when handling |
|
|
1247 | lots of events. |
|
|
1248 | |
1193 | The relative timeouts are calculated relative to the C<ev_now ()> |
1249 | The relative timeouts are calculated relative to the C<ev_now ()> |
1194 | time. This is usually the right thing as this timestamp refers to the time |
1250 | time. This is usually the right thing as this timestamp refers to the time |
1195 | of the event triggering whatever timeout you are modifying/starting. If |
1251 | of the event triggering whatever timeout you are modifying/starting. If |
1196 | you suspect event processing to be delayed and you I<need> to base the timeout |
1252 | you suspect event processing to be delayed and you I<need> to base the |
1197 | on the current time, use something like this to adjust for this: |
1253 | timeout on the current time, use something like this to adjust for this: |
1198 | |
1254 | |
1199 | ev_timer_set (&timer, after + ev_now () - ev_time (), 0.); |
1255 | ev_timer_set (&timer, after + ev_now () - ev_time (), 0.); |
1200 | |
1256 | |
1201 | The callback is guaranteed to be invoked only after its timeout has passed, |
1257 | If the event loop is suspended for a long time, you can also force an |
1202 | but if multiple timers become ready during the same loop iteration then |
1258 | update of the time returned by C<ev_now ()> by calling C<ev_now_update |
1203 | order of execution is undefined. |
1259 | ()>. |
1204 | |
1260 | |
1205 | =head3 Watcher-Specific Functions and Data Members |
1261 | =head3 Watcher-Specific Functions and Data Members |
1206 | |
1262 | |
1207 | =over 4 |
1263 | =over 4 |
1208 | |
1264 | |
… | |
… | |
1559 | handler, you can override it easily by installing your own handler for |
1615 | handler, you can override it easily by installing your own handler for |
1560 | C<SIGCHLD> after initialising the default loop, and making sure the |
1616 | C<SIGCHLD> after initialising the default loop, and making sure the |
1561 | default loop never gets destroyed. You are encouraged, however, to use an |
1617 | default loop never gets destroyed. You are encouraged, however, to use an |
1562 | event-based approach to child reaping and thus use libev's support for |
1618 | event-based approach to child reaping and thus use libev's support for |
1563 | that, so other libev users can use C<ev_child> watchers freely. |
1619 | that, so other libev users can use C<ev_child> watchers freely. |
|
|
1620 | |
|
|
1621 | =head3 Stopping the Child Watcher |
|
|
1622 | |
|
|
1623 | Currently, the child watcher never gets stopped, even when the |
|
|
1624 | child terminates, so normally one needs to stop the watcher in the |
|
|
1625 | callback. Future versions of libev might stop the watcher automatically |
|
|
1626 | when a child exit is detected. |
1564 | |
1627 | |
1565 | =head3 Watcher-Specific Functions and Data Members |
1628 | =head3 Watcher-Specific Functions and Data Members |
1566 | |
1629 | |
1567 | =over 4 |
1630 | =over 4 |
1568 | |
1631 | |
… | |
… | |
1662 | will be no polling. |
1725 | will be no polling. |
1663 | |
1726 | |
1664 | =head3 ABI Issues (Largefile Support) |
1727 | =head3 ABI Issues (Largefile Support) |
1665 | |
1728 | |
1666 | Libev by default (unless the user overrides this) uses the default |
1729 | Libev by default (unless the user overrides this) uses the default |
1667 | compilation environment, which means that on systems with optionally |
1730 | compilation environment, which means that on systems with large file |
1668 | disabled large file support, you get the 32 bit version of the stat |
1731 | support disabled by default, you get the 32 bit version of the stat |
1669 | structure. When using the library from programs that change the ABI to |
1732 | structure. When using the library from programs that change the ABI to |
1670 | use 64 bit file offsets the programs will fail. In that case you have to |
1733 | use 64 bit file offsets the programs will fail. In that case you have to |
1671 | compile libev with the same flags to get binary compatibility. This is |
1734 | compile libev with the same flags to get binary compatibility. This is |
1672 | obviously the case with any flags that change the ABI, but the problem is |
1735 | obviously the case with any flags that change the ABI, but the problem is |
1673 | most noticeably with ev_stat and large file support. |
1736 | most noticeably disabled with ev_stat and large file support. |
|
|
1737 | |
|
|
1738 | The solution for this is to lobby your distribution maker to make large |
|
|
1739 | file interfaces available by default (as e.g. FreeBSD does) and not |
|
|
1740 | optional. Libev cannot simply switch on large file support because it has |
|
|
1741 | to exchange stat structures with application programs compiled using the |
|
|
1742 | default compilation environment. |
1674 | |
1743 | |
1675 | =head3 Inotify |
1744 | =head3 Inotify |
1676 | |
1745 | |
1677 | When C<inotify (7)> support has been compiled into libev (generally only |
1746 | When C<inotify (7)> support has been compiled into libev (generally only |
1678 | available on Linux) and present at runtime, it will be used to speed up |
1747 | available on Linux) and present at runtime, it will be used to speed up |
… | |
… | |
2626 | libev. EV is developed together with libev. Apart from the EV core module, |
2695 | libev. EV is developed together with libev. Apart from the EV core module, |
2627 | there are additional modules that implement libev-compatible interfaces |
2696 | there are additional modules that implement libev-compatible interfaces |
2628 | to C<libadns> (C<EV::ADNS>), C<Net::SNMP> (C<Net::SNMP::EV>) and the |
2697 | to C<libadns> (C<EV::ADNS>), C<Net::SNMP> (C<Net::SNMP::EV>) and the |
2629 | C<libglib> event core (C<Glib::EV> and C<EV::Glib>). |
2698 | C<libglib> event core (C<Glib::EV> and C<EV::Glib>). |
2630 | |
2699 | |
2631 | It can be found and installed via CPAN, its homepage is found at |
2700 | It can be found and installed via CPAN, its homepage is at |
2632 | L<http://software.schmorp.de/pkg/EV>. |
2701 | L<http://software.schmorp.de/pkg/EV>. |
|
|
2702 | |
|
|
2703 | =item Python |
|
|
2704 | |
|
|
2705 | Python bindings can be found at L<http://code.google.com/p/pyev/>. It |
|
|
2706 | seems to be quite complete and well-documented. Note, however, that the |
|
|
2707 | patch they require for libev is outright dangerous as it breaks the ABI |
|
|
2708 | for everybody else, and therefore, should never be applied in an installed |
|
|
2709 | libev (if python requires an incompatible ABI then it needs to embed |
|
|
2710 | libev). |
2633 | |
2711 | |
2634 | =item Ruby |
2712 | =item Ruby |
2635 | |
2713 | |
2636 | Tony Arcieri has written a ruby extension that offers access to a subset |
2714 | Tony Arcieri has written a ruby extension that offers access to a subset |
2637 | of the libev API and adds file handle abstractions, asynchronous DNS and |
2715 | of the libev API and adds file handle abstractions, asynchronous DNS and |
… | |
… | |
2639 | L<http://rev.rubyforge.org/>. |
2717 | L<http://rev.rubyforge.org/>. |
2640 | |
2718 | |
2641 | =item D |
2719 | =item D |
2642 | |
2720 | |
2643 | Leandro Lucarella has written a D language binding (F<ev.d>) for libev, to |
2721 | Leandro Lucarella has written a D language binding (F<ev.d>) for libev, to |
2644 | be found at L<http://git.llucax.com.ar/?p=software/ev.d.git;a=summary>. |
2722 | be found at L<http://proj.llucax.com.ar/wiki/evd>. |
2645 | |
2723 | |
2646 | =back |
2724 | =back |
2647 | |
2725 | |
2648 | |
2726 | |
2649 | =head1 MACRO MAGIC |
2727 | =head1 MACRO MAGIC |
… | |
… | |
3162 | |
3240 | |
3163 | =head1 THREADS AND COROUTINES |
3241 | =head1 THREADS AND COROUTINES |
3164 | |
3242 | |
3165 | =head2 THREADS |
3243 | =head2 THREADS |
3166 | |
3244 | |
3167 | Libev itself is completely thread-safe, but it uses no locking. This |
3245 | Libev itself is thread-safe (unless the opposite is specifically |
|
|
3246 | documented for a function), but it uses no locking itself. This means that |
3168 | means that you can use as many loops as you want in parallel, as long as |
3247 | you can use as many loops as you want in parallel, as long as only one |
3169 | only one thread ever calls into one libev function with the same loop |
3248 | thread ever calls into one libev function with the same loop parameter: |
3170 | parameter. |
3249 | libev guarentees that different event loops share no data structures that |
|
|
3250 | need locking. |
3171 | |
3251 | |
3172 | Or put differently: calls with different loop parameters can be done in |
3252 | Or to put it differently: calls with different loop parameters can be done |
3173 | parallel from multiple threads, calls with the same loop parameter must be |
3253 | concurrently from multiple threads, calls with the same loop parameter |
3174 | done serially (but can be done from different threads, as long as only one |
3254 | must be done serially (but can be done from different threads, as long as |
3175 | thread ever is inside a call at any point in time, e.g. by using a mutex |
3255 | only one thread ever is inside a call at any point in time, e.g. by using |
3176 | per loop). |
3256 | a mutex per loop). |
3177 | |
3257 | |
3178 | If you want to know which design is best for your problem, then I cannot |
3258 | Specifically to support threads (and signal handlers), libev implements |
3179 | help you but by giving some generic advice: |
3259 | so-called C<ev_async> watchers, which allow some limited form of |
|
|
3260 | concurrency on the same event loop. |
|
|
3261 | |
|
|
3262 | If you want to know which design (one loop, locking, or multiple loops |
|
|
3263 | without or something else still) is best for your problem, then I cannot |
|
|
3264 | help you. I can give some generic advice however: |
3180 | |
3265 | |
3181 | =over 4 |
3266 | =over 4 |
3182 | |
3267 | |
3183 | =item * most applications have a main thread: use the default libev loop |
3268 | =item * most applications have a main thread: use the default libev loop |
3184 | in that thread, or create a separate thread running only the default loop. |
3269 | in that thread, or create a separate thread running only the default loop. |
… | |
… | |
3196 | |
3281 | |
3197 | Choosing a model is hard - look around, learn, know that usually you can do |
3282 | Choosing a model is hard - look around, learn, know that usually you can do |
3198 | better than you currently do :-) |
3283 | better than you currently do :-) |
3199 | |
3284 | |
3200 | =item * often you need to talk to some other thread which blocks in the |
3285 | =item * often you need to talk to some other thread which blocks in the |
|
|
3286 | event loop. |
|
|
3287 | |
3201 | event loop - C<ev_async> watchers can be used to wake them up from other |
3288 | C<ev_async> watchers can be used to wake them up from other threads safely |
3202 | threads safely (or from signal contexts...). |
3289 | (or from signal contexts...). |
|
|
3290 | |
|
|
3291 | An example use would be to communicate signals or other events that only |
|
|
3292 | work in the default loop by registering the signal watcher with the |
|
|
3293 | default loop and triggering an C<ev_async> watcher from the default loop |
|
|
3294 | watcher callback into the event loop interested in the signal. |
3203 | |
3295 | |
3204 | =back |
3296 | =back |
3205 | |
3297 | |
3206 | =head2 COROUTINES |
3298 | =head2 COROUTINES |
3207 | |
3299 | |
… | |
… | |
3210 | coroutines (e.g. you can call C<ev_loop> on the same loop from two |
3302 | coroutines (e.g. you can call C<ev_loop> on the same loop from two |
3211 | different coroutines and switch freely between both coroutines running the |
3303 | different coroutines and switch freely between both coroutines running the |
3212 | loop, as long as you don't confuse yourself). The only exception is that |
3304 | loop, as long as you don't confuse yourself). The only exception is that |
3213 | you must not do this from C<ev_periodic> reschedule callbacks. |
3305 | you must not do this from C<ev_periodic> reschedule callbacks. |
3214 | |
3306 | |
3215 | Care has been invested into making sure that libev does not keep local |
3307 | Care has been taken to ensure that libev does not keep local state inside |
3216 | state inside C<ev_loop>, and other calls do not usually allow coroutine |
3308 | C<ev_loop>, and other calls do not usually allow coroutine switches. |
3217 | switches. |
|
|
3218 | |
3309 | |
3219 | |
3310 | |
3220 | =head1 COMPLEXITIES |
3311 | =head1 COMPLEXITIES |
3221 | |
3312 | |
3222 | In this section the complexities of (many of) the algorithms used inside |
3313 | In this section the complexities of (many of) the algorithms used inside |
… | |
… | |
3317 | more than a hundred or so sockets, then likely it needs to use a totally |
3408 | more than a hundred or so sockets, then likely it needs to use a totally |
3318 | different implementation for windows, as libev offers the POSIX readiness |
3409 | different implementation for windows, as libev offers the POSIX readiness |
3319 | notification model, which cannot be implemented efficiently on windows |
3410 | notification model, which cannot be implemented efficiently on windows |
3320 | (Microsoft monopoly games). |
3411 | (Microsoft monopoly games). |
3321 | |
3412 | |
|
|
3413 | A typical way to use libev under windows is to embed it (see the embedding |
|
|
3414 | section for details) and use the following F<evwrap.h> header file instead |
|
|
3415 | of F<ev.h>: |
|
|
3416 | |
|
|
3417 | #define EV_STANDALONE /* keeps ev from requiring config.h */ |
|
|
3418 | #define EV_SELECT_IS_WINSOCKET 1 /* configure libev for windows select */ |
|
|
3419 | |
|
|
3420 | #include "ev.h" |
|
|
3421 | |
|
|
3422 | And compile the following F<evwrap.c> file into your project (make sure |
|
|
3423 | you do I<not> compile the F<ev.c> or any other embedded soruce files!): |
|
|
3424 | |
|
|
3425 | #include "evwrap.h" |
|
|
3426 | #include "ev.c" |
|
|
3427 | |
3322 | =over 4 |
3428 | =over 4 |
3323 | |
3429 | |
3324 | =item The winsocket select function |
3430 | =item The winsocket select function |
3325 | |
3431 | |
3326 | The winsocket C<select> function doesn't follow POSIX in that it |
3432 | The winsocket C<select> function doesn't follow POSIX in that it |
3327 | requires socket I<handles> and not socket I<file descriptors> (it is |
3433 | requires socket I<handles> and not socket I<file descriptors> (it is |
3328 | also extremely buggy). This makes select very inefficient, and also |
3434 | also extremely buggy). This makes select very inefficient, and also |
3329 | requires a mapping from file descriptors to socket handles. See the |
3435 | requires a mapping from file descriptors to socket handles (the Microsoft |
|
|
3436 | C runtime provides the function C<_open_osfhandle> for this). See the |
3330 | discussion of the C<EV_SELECT_USE_FD_SET>, C<EV_SELECT_IS_WINSOCKET> and |
3437 | discussion of the C<EV_SELECT_USE_FD_SET>, C<EV_SELECT_IS_WINSOCKET> and |
3331 | C<EV_FD_TO_WIN32_HANDLE> preprocessor symbols for more info. |
3438 | C<EV_FD_TO_WIN32_HANDLE> preprocessor symbols for more info. |
3332 | |
3439 | |
3333 | The configuration for a "naked" win32 using the Microsoft runtime |
3440 | The configuration for a "naked" win32 using the Microsoft runtime |
3334 | libraries and raw winsocket select is: |
3441 | libraries and raw winsocket select is: |