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

Comparing libev/ev.pod (file contents):
Revision 1.88 by ayin, Tue Dec 18 13:06:18 2007 UTC vs.
Revision 1.110 by root, Tue Dec 25 07:05:45 2007 UTC

… …
4 4
5=head1 SYNOPSIS 5=head1 SYNOPSIS
6 6
7 #include <ev.h> 7 #include <ev.h>
8 8
9=head1 EXAMPLE PROGRAM 9=head2 EXAMPLE PROGRAM
10 10
11 #include <ev.h> 11 #include <ev.h>
12 12
13 ev_io stdin_watcher; 13 ev_io stdin_watcher;
14 ev_timer timeout_watcher; 14 ev_timer timeout_watcher;
… …
53The newest version of this document is also available as a html-formatted 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 54web page you might find easier to navigate when reading it for the first
55time: L<http://cvs.schmorp.de/libev/ev.html>. 55time: L<http://cvs.schmorp.de/libev/ev.html>.
56 56
57Libev 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
58file descriptor being readable or a timeout occuring), and it will manage 58file descriptor being readable or a timeout occurring), and it will manage
59these event sources and provide your program with events. 59these event sources and provide your program with events.
60 60
61To do this, it must take more or less complete control over your process 61To 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
63communicate events via a callback mechanism. 63communicate events via a callback mechanism.
… …
65You register interest in certain events by registering so-called I<event 65You register interest in certain events by registering so-called I<event
66watchers>, which are relatively small C structures you initialise with the 66watchers>, which are relatively small C structures you initialise with the
67details of the event, and then hand it over to libev by I<starting> the 67details of the event, and then hand it over to libev by I<starting> the
68watcher. 68watcher.
69 69
70=head1 FEATURES 70=head2 FEATURES
71 71
72Libev supports C<select>, C<poll>, the Linux-specific C<epoll>, the 72Libev supports C<select>, C<poll>, the Linux-specific C<epoll>, the
73BSD-specific C<kqueue> and the Solaris-specific event port mechanisms 73BSD-specific C<kqueue> and the Solaris-specific event port mechanisms
74for file descriptor events (C<ev_io>), the Linux C<inotify> interface 74for file descriptor events (C<ev_io>), the Linux C<inotify> interface
75(for C<ev_stat>), relative timers (C<ev_timer>), absolute timers 75(for C<ev_stat>), relative timers (C<ev_timer>), absolute timers
… …
82 82
83It also is quite fast (see this 83It also is quite fast (see this
84L<benchmark|http://libev.schmorp.de/bench.html> comparing it to libevent 84L<benchmark|http://libev.schmorp.de/bench.html> comparing it to libevent
85for example). 85for example).
86 86
87=head1 CONVENTIONS 87=head2 CONVENTIONS
88 88
89Libev is very configurable. In this manual the default configuration will 89Libev is very configurable. In this manual the default configuration will
90be described, which supports multiple event loops. For more info about 90be described, which supports multiple event loops. For more info about
91various configuration options please have a look at B<EMBED> section in 91various configuration options please have a look at B<EMBED> section in
92this manual. If libev was configured without support for multiple event 92this manual. If libev was configured without support for multiple event
93loops, then all functions taking an initial argument of name C<loop> 93loops, then all functions taking an initial argument of name C<loop>
94(which is always of type C<struct ev_loop *>) will not have this argument. 94(which is always of type C<struct ev_loop *>) will not have this argument.
95 95
96=head1 TIME REPRESENTATION 96=head2 TIME REPRESENTATION
97 97
98Libev represents time as a single floating point number, representing the 98Libev 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
100the beginning of 1970, details are complicated, don't ask). This type is 100the beginning of 1970, details are complicated, don't ask). This type is
101called C<ev_tstamp>, which is what you should use too. It usually aliases 101called C<ev_tstamp>, which is what you should use too. It usually aliases
… …
115 115
116Returns the current time as libev would use it. Please note that the 116Returns the current time as libev would use it. Please note that the
117C<ev_now> function is usually faster and also often returns the timestamp 117C<ev_now> function is usually faster and also often returns the timestamp
118you actually want to know. 118you actually want to know.
119 119
120=item ev_sleep (ev_tstamp interval)
121
122Sleep for the given interval: The current thread will be blocked until
123either it is interrupted or the given time interval has passed. Basically
124this is a subsecond-resolution C<sleep ()>.
125
120=item int ev_version_major () 126=item int ev_version_major ()
121 127
122=item int ev_version_minor () 128=item int ev_version_minor ()
123 129
124You can find out the major and minor ABI version numbers of the library 130You can find out the major and minor ABI version numbers of the library
… …
300=item C<EVBACKEND_SELECT> (value 1, portable select backend) 306=item C<EVBACKEND_SELECT> (value 1, portable select backend)
301 307
302This is your standard select(2) backend. Not I<completely> standard, as 308This is your standard select(2) backend. Not I<completely> standard, as
303libev tries to roll its own fd_set with no limits on the number of fds, 309libev tries to roll its own fd_set with no limits on the number of fds,
304but if that fails, expect a fairly low limit on the number of fds when 310but if that fails, expect a fairly low limit on the number of fds when
305using this backend. It doesn't scale too well (O(highest_fd)), but its usually 311using this backend. It doesn't scale too well (O(highest_fd)), but its
306the fastest backend for a low number of fds. 312usually the fastest backend for a low number of (low-numbered :) fds.
313
314To get good performance out of this backend you need a high amount of
315parallelity (most of the file descriptors should be busy). If you are
316writing a server, you should C<accept ()> in a loop to accept as many
317connections as possible during one iteration. You might also want to have
318a look at C<ev_set_io_collect_interval ()> to increase the amount of
319readyness notifications you get per iteration.
307 320
308=item C<EVBACKEND_POLL> (value 2, poll backend, available everywhere except on windows) 321=item C<EVBACKEND_POLL> (value 2, poll backend, available everywhere except on windows)
309 322
310And this is your standard poll(2) backend. It's more complicated than 323And this is your standard poll(2) backend. It's more complicated
311select, but handles sparse fds better and has no artificial limit on the 324than select, but handles sparse fds better and has no artificial
312number of fds you can use (except it will slow down considerably with a 325limit on the number of fds you can use (except it will slow down
313lot of inactive fds). It scales similarly to select, i.e. O(total_fds). 326considerably with a lot of inactive fds). It scales similarly to select,
327i.e. O(total_fds). See the entry for C<EVBACKEND_SELECT>, above, for
328performance tips.
314 329
315=item C<EVBACKEND_EPOLL> (value 4, Linux) 330=item C<EVBACKEND_EPOLL> (value 4, Linux)
316 331
317For few fds, this backend is a bit little slower than poll and select, 332For few fds, this backend is a bit little slower than poll and select,
318but it scales phenomenally better. While poll and select usually scale like 333but it scales phenomenally better. While poll and select usually scale
319O(total_fds) where n is the total number of fds (or the highest fd), epoll scales 334like O(total_fds) where n is the total number of fds (or the highest fd),
320either O(1) or O(active_fds). 335epoll scales either O(1) or O(active_fds). The epoll design has a number
336of shortcomings, such as silently dropping events in some hard-to-detect
337cases and rewiring a syscall per fd change, no fork support and bad
338support for dup.
321 339
322While stopping and starting an I/O watcher in the same iteration will 340While stopping, setting and starting an I/O watcher in the same iteration
323result in some caching, there is still a syscall per such incident 341will result in some caching, there is still a syscall per such incident
324(because the fd could point to a different file description now), so its 342(because the fd could point to a different file description now), so its
325best to avoid that. Also, dup()ed file descriptors might not work very 343best to avoid that. Also, C<dup ()>'ed file descriptors might not work
326well if you register events for both fds. 344very well if you register events for both fds.
327 345
328Please note that epoll sometimes generates spurious notifications, so you 346Please note that epoll sometimes generates spurious notifications, so you
329need to use non-blocking I/O or other means to avoid blocking when no data 347need to use non-blocking I/O or other means to avoid blocking when no data
330(or space) is available. 348(or space) is available.
331 349
350Best performance from this backend is achieved by not unregistering all
351watchers for a file descriptor until it has been closed, if possible, i.e.
352keep at least one watcher active per fd at all times.
353
354While nominally embeddeble in other event loops, this feature is broken in
355all kernel versions tested so far.
356
332=item C<EVBACKEND_KQUEUE> (value 8, most BSD clones) 357=item C<EVBACKEND_KQUEUE> (value 8, most BSD clones)
333 358
334Kqueue deserves special mention, as at the time of this writing, it 359Kqueue deserves special mention, as at the time of this writing, it
335was broken on all BSDs except NetBSD (usually it doesn't work with 360was broken on all BSDs except NetBSD (usually it doesn't work reliably
336anything but sockets and pipes, except on Darwin, where of course its 361with anything but sockets and pipes, except on Darwin, where of course
337completely useless). For this reason its not being "autodetected" 362it's completely useless). For this reason it's not being "autodetected"
338unless you explicitly specify it explicitly in the flags (i.e. using 363unless you explicitly specify it explicitly in the flags (i.e. using
339C<EVBACKEND_KQUEUE>). 364C<EVBACKEND_KQUEUE>) or libev was compiled on a known-to-be-good (-enough)
365system like NetBSD.
366
367You still can embed kqueue into a normal poll or select backend and use it
368only for sockets (after having made sure that sockets work with kqueue on
369the target platform). See C<ev_embed> watchers for more info.
340 370
341It scales in the same way as the epoll backend, but the interface to the 371It scales in the same way as the epoll backend, but the interface to the
342kernel is more efficient (which says nothing about its actual speed, of 372kernel is more efficient (which says nothing about its actual speed, of
343course). While starting and stopping an I/O watcher does not cause an 373course). While stopping, setting and starting an I/O watcher does never
344extra syscall as with epoll, it still adds up to four event changes per 374cause an extra syscall as with C<EVBACKEND_EPOLL>, it still adds up to
345incident, so its best to avoid that. 375two event changes per incident, support for C<fork ()> is very bad and it
376drops fds silently in similarly hard-to-detect cases.
377
378This backend usually performs well under most conditions.
379
380While nominally embeddable in other event loops, this doesn't work
381everywhere, so you might need to test for this. And since it is broken
382almost everywhere, you should only use it when you have a lot of sockets
383(for which it usually works), by embedding it into another event loop
384(e.g. C<EVBACKEND_SELECT> or C<EVBACKEND_POLL>) and using it only for
385sockets.
346 386
347=item C<EVBACKEND_DEVPOLL> (value 16, Solaris 8) 387=item C<EVBACKEND_DEVPOLL> (value 16, Solaris 8)
348 388
349This is not implemented yet (and might never be). 389This is not implemented yet (and might never be, unless you send me an
390implementation). According to reports, C</dev/poll> only supports sockets
391and is not embeddable, which would limit the usefulness of this backend
392immensely.
350 393
351=item C<EVBACKEND_PORT> (value 32, Solaris 10) 394=item C<EVBACKEND_PORT> (value 32, Solaris 10)
352 395
353This uses the Solaris 10 port mechanism. As with everything on Solaris, 396This uses the Solaris 10 event port mechanism. As with everything on Solaris,
354it's really slow, but it still scales very well (O(active_fds)). 397it's really slow, but it still scales very well (O(active_fds)).
355 398
356Please note that solaris ports can result in a lot of spurious 399Please note that solaris event ports can deliver a lot of spurious
357notifications, so you need to use non-blocking I/O or other means to avoid 400notifications, so you need to use non-blocking I/O or other means to avoid
358blocking when no data (or space) is available. 401blocking when no data (or space) is available.
402
403While this backend scales well, it requires one system call per active
404file descriptor per loop iteration. For small and medium numbers of file
405descriptors a "slow" C<EVBACKEND_SELECT> or C<EVBACKEND_POLL> backend
406might perform better.
359 407
360=item C<EVBACKEND_ALL> 408=item C<EVBACKEND_ALL>
361 409
362Try all backends (even potentially broken ones that wouldn't be tried 410Try all backends (even potentially broken ones that wouldn't be tried
363with C<EVFLAG_AUTO>). Since this is a mask, you can do stuff such as 411with C<EVFLAG_AUTO>). Since this is a mask, you can do stuff such as
364C<EVBACKEND_ALL & ~EVBACKEND_KQUEUE>. 412C<EVBACKEND_ALL & ~EVBACKEND_KQUEUE>.
413
414It is definitely not recommended to use this flag.
365 415
366=back 416=back
367 417
368If one or more of these are ored into the flags value, then only these 418If one or more of these are ored into the flags value, then only these
369backends will be tried (in the reverse order as given here). If none are 419backends will be tried (in the reverse order as given here). If none are
… …
469 519
470Returns the current "event loop time", which is the time the event loop 520Returns the current "event loop time", which is the time the event loop
471received events and started processing them. This timestamp does not 521received events and started processing them. This timestamp does not
472change as long as callbacks are being processed, and this is also the base 522change as long as callbacks are being processed, and this is also the base
473time used for relative timers. You can treat it as the timestamp of the 523time used for relative timers. You can treat it as the timestamp of the
474event occuring (or more correctly, libev finding out about it). 524event occurring (or more correctly, libev finding out about it).
475 525
476=item ev_loop (loop, int flags) 526=item ev_loop (loop, int flags)
477 527
478Finally, this is it, the event handler. This function usually is called 528Finally, this is it, the event handler. This function usually is called
479after you initialised all your watchers and you want to start handling 529after you initialised all your watchers and you want to start handling
… …
563Example: For some weird reason, unregister the above signal handler again. 613Example: For some weird reason, unregister the above signal handler again.
564 614
565 ev_ref (loop); 615 ev_ref (loop);
566 ev_signal_stop (loop, &exitsig); 616 ev_signal_stop (loop, &exitsig);
567 617
618=item ev_set_io_collect_interval (loop, ev_tstamp interval)
619
620=item ev_set_timeout_collect_interval (loop, ev_tstamp interval)
621
622These advanced functions influence the time that libev will spend waiting
623for events. Both are by default C<0>, meaning that libev will try to
624invoke timer/periodic callbacks and I/O callbacks with minimum latency.
625
626Setting these to a higher value (the C<interval> I<must> be >= C<0>)
627allows libev to delay invocation of I/O and timer/periodic callbacks to
628increase efficiency of loop iterations.
629
630The background is that sometimes your program runs just fast enough to
631handle one (or very few) event(s) per loop iteration. While this makes
632the program responsive, it also wastes a lot of CPU time to poll for new
633events, especially with backends like C<select ()> which have a high
634overhead for the actual polling but can deliver many events at once.
635
636By setting a higher I<io collect interval> you allow libev to spend more
637time collecting I/O events, so you can handle more events per iteration,
638at the cost of increasing latency. Timeouts (both C<ev_periodic> and
639C<ev_timer>) will be not affected. Setting this to a non-null value will
640introduce an additional C<ev_sleep ()> call into most loop iterations.
641
642Likewise, by setting a higher I<timeout collect interval> you allow libev
643to spend more time collecting timeouts, at the expense of increased
644latency (the watcher callback will be called later). C<ev_io> watchers
645will not be affected. Setting this to a non-null value will not introduce
646any overhead in libev.
647
648Many (busy) programs can usually benefit by setting the io collect
649interval to a value near C<0.1> or so, which is often enough for
650interactive servers (of course not for games), likewise for timeouts. It
651usually doesn't make much sense to set it to a lower value than C<0.01>,
652as this approsaches the timing granularity of most systems.
653
568=back 654=back
569 655
570 656
571=head1 ANATOMY OF A WATCHER 657=head1 ANATOMY OF A WATCHER
572 658
… …
897In general you can register as many read and/or write event watchers per 983In general you can register as many read and/or write event watchers per
898fd as you want (as long as you don't confuse yourself). Setting all file 984fd as you want (as long as you don't confuse yourself). Setting all file
899descriptors to non-blocking mode is also usually a good idea (but not 985descriptors to non-blocking mode is also usually a good idea (but not
900required if you know what you are doing). 986required if you know what you are doing).
901 987
902You have to be careful with dup'ed file descriptors, though. Some backends
903(the linux epoll backend is a notable example) cannot handle dup'ed file
904descriptors correctly if you register interest in two or more fds pointing
905to the same underlying file/socket/etc. description (that is, they share
906the same underlying "file open").
907
908If you must do this, then force the use of a known-to-be-good backend 988If you must do this, then force the use of a known-to-be-good backend
909(at the time of this writing, this includes only C<EVBACKEND_SELECT> and 989(at the time of this writing, this includes only C<EVBACKEND_SELECT> and
910C<EVBACKEND_POLL>). 990C<EVBACKEND_POLL>).
911 991
912Another thing you have to watch out for is that it is quite easy to 992Another thing you have to watch out for is that it is quite easy to
… …
924such as poll (fortunately in our Xlib example, Xlib already does this on 1004such as poll (fortunately in our Xlib example, Xlib already does this on
925its own, so its quite safe to use). 1005its own, so its quite safe to use).
926 1006
927=head3 The special problem of disappearing file descriptors 1007=head3 The special problem of disappearing file descriptors
928 1008
929Some backends (e.g kqueue, epoll) need to be told about closing a file 1009Some backends (e.g. kqueue, epoll) need to be told about closing a file
930descriptor (either by calling C<close> explicitly or by any other means, 1010descriptor (either by calling C<close> explicitly or by any other means,
931such as C<dup>). The reason is that you register interest in some file 1011such as C<dup>). The reason is that you register interest in some file
932descriptor, but when it goes away, the operating system will silently drop 1012descriptor, but when it goes away, the operating system will silently drop
933this interest. If another file descriptor with the same number then is 1013this interest. If another file descriptor with the same number then is
934registered with libev, there is no efficient way to see that this is, in 1014registered with libev, there is no efficient way to see that this is, in
… …
942descriptor even if the file descriptor number itself did not change. 1022descriptor even if the file descriptor number itself did not change.
943 1023
944This is how one would do it normally anyway, the important point is that 1024This is how one would do it normally anyway, the important point is that
945the libev application should not optimise around libev but should leave 1025the libev application should not optimise around libev but should leave
946optimisations to libev. 1026optimisations to libev.
1027
1028=head3 The special problem of dup'ed file descriptors
1029
1030Some backends (e.g. epoll), cannot register events for file descriptors,
1031but only events for the underlying file descriptions. That means when you
1032have C<dup ()>'ed file descriptors or weirder constellations, and register
1033events for them, only one file descriptor might actually receive events.
1034
1035There is no workaround possible except not registering events
1036for potentially C<dup ()>'ed file descriptors, or to resort to
1037C<EVBACKEND_SELECT> or C<EVBACKEND_POLL>.
1038
1039=head3 The special problem of fork
1040
1041Some backends (epoll, kqueue) do not support C<fork ()> at all or exhibit
1042useless behaviour. Libev fully supports fork, but needs to be told about
1043it in the child.
1044
1045To support fork in your programs, you either have to call
1046C<ev_default_fork ()> or C<ev_loop_fork ()> after a fork in the child,
1047enable C<EVFLAG_FORKCHECK>, or resort to C<EVBACKEND_SELECT> or
1048C<EVBACKEND_POLL>.
947 1049
948 1050
949=head3 Watcher-Specific Functions 1051=head3 Watcher-Specific Functions
950 1052
951=over 4 1053=over 4
… …
1388semantics of C<ev_stat> watchers, which means that libev sometimes needs 1490semantics of C<ev_stat> watchers, which means that libev sometimes needs
1389to fall back to regular polling again even with inotify, but changes are 1491to fall back to regular polling again even with inotify, but changes are
1390usually detected immediately, and if the file exists there will be no 1492usually detected immediately, and if the file exists there will be no
1391polling. 1493polling.
1392 1494
1495=head3 Inotify
1496
1497When C<inotify (7)> support has been compiled into libev (generally only
1498available on Linux) and present at runtime, it will be used to speed up
1499change detection where possible. The inotify descriptor will be created lazily
1500when the first C<ev_stat> watcher is being started.
1501
1502Inotify presense does not change the semantics of C<ev_stat> watchers
1503except that changes might be detected earlier, and in some cases, to avoid
1504making regular C<stat> calls. Even in the presense of inotify support
1505there are many cases where libev has to resort to regular C<stat> polling.
1506
1507(There is no support for kqueue, as apparently it cannot be used to
1508implement this functionality, due to the requirement of having a file
1509descriptor open on the object at all times).
1510
1511=head3 The special problem of stat time resolution
1512
1513The C<stat ()> syscall only supports full-second resolution portably, and
1514even on systems where the resolution is higher, many filesystems still
1515only support whole seconds.
1516
1517That means that, if the time is the only thing that changes, you might
1518miss updates: on the first update, C<ev_stat> detects a change and calls
1519your callback, which does something. When there is another update within
1520the same second, C<ev_stat> will be unable to detect it.
1521
1522The solution to this is to delay acting on a change for a second (or till
1523the next second boundary), using a roughly one-second delay C<ev_timer>
1524(C<ev_timer_set (w, 0., 1.01); ev_timer_again (loop, w)>). The C<.01>
1525is added to work around small timing inconsistencies of some operating
1526systems.
1527
1393=head3 Watcher-Specific Functions and Data Members 1528=head3 Watcher-Specific Functions and Data Members
1394 1529
1395=over 4 1530=over 4
1396 1531
1397=item ev_stat_init (ev_stat *, callback, const char *path, ev_tstamp interval) 1532=item ev_stat_init (ev_stat *, callback, const char *path, ev_tstamp interval)
… …
1434=item const char *path [read-only] 1569=item const char *path [read-only]
1435 1570
1436The filesystem path that is being watched. 1571The filesystem path that is being watched.
1437 1572
1438=back 1573=back
1574
1575=head3 Examples
1439 1576
1440Example: Watch C</etc/passwd> for attribute changes. 1577Example: Watch C</etc/passwd> for attribute changes.
1441 1578
1442 static void 1579 static void
1443 passwd_cb (struct ev_loop *loop, ev_stat *w, int revents) 1580 passwd_cb (struct ev_loop *loop, ev_stat *w, int revents)
… …
1456 } 1593 }
1457 1594
1458 ... 1595 ...
1459 ev_stat passwd; 1596 ev_stat passwd;
1460 1597
1461 ev_stat_init (&passwd, passwd_cb, "/etc/passwd"); 1598 ev_stat_init (&passwd, passwd_cb, "/etc/passwd", 0.);
1462 ev_stat_start (loop, &passwd); 1599 ev_stat_start (loop, &passwd);
1600
1601Example: Like above, but additionally use a one-second delay so we do not
1602miss updates (however, frequent updates will delay processing, too, so
1603one might do the work both on C<ev_stat> callback invocation I<and> on
1604C<ev_timer> callback invocation).
1605
1606 static ev_stat passwd;
1607 static ev_timer timer;
1608
1609 static void
1610 timer_cb (EV_P_ ev_timer *w, int revents)
1611 {
1612 ev_timer_stop (EV_A_ w);
1613
1614 /* now it's one second after the most recent passwd change */
1615 }
1616
1617 static void
1618 stat_cb (EV_P_ ev_stat *w, int revents)
1619 {
1620 /* reset the one-second timer */
1621 ev_timer_again (EV_A_ &timer);
1622 }
1623
1624 ...
1625 ev_stat_init (&passwd, stat_cb, "/etc/passwd", 0.);
1626 ev_stat_start (loop, &passwd);
1627 ev_timer_init (&timer, timer_cb, 0., 1.01);
1463 1628
1464 1629
1465=head2 C<ev_idle> - when you've got nothing better to do... 1630=head2 C<ev_idle> - when you've got nothing better to do...
1466 1631
1467Idle watchers trigger events when no other events of the same or higher 1632Idle watchers trigger events when no other events of the same or higher
… …
1553 1718
1554It is recommended to give C<ev_check> watchers highest (C<EV_MAXPRI>) 1719It is recommended to give C<ev_check> watchers highest (C<EV_MAXPRI>)
1555priority, to ensure that they are being run before any other watchers 1720priority, to ensure that they are being run before any other watchers
1556after the poll. Also, C<ev_check> watchers (and C<ev_prepare> watchers, 1721after the poll. Also, C<ev_check> watchers (and C<ev_prepare> watchers,
1557too) should not activate ("feed") events into libev. While libev fully 1722too) should not activate ("feed") events into libev. While libev fully
1558supports this, they will be called before other C<ev_check> watchers did 1723supports this, they will be called before other C<ev_check> watchers
1559their job. As C<ev_check> watchers are often used to embed other event 1724did their job. As C<ev_check> watchers are often used to embed other
1560loops those other event loops might be in an unusable state until their 1725(non-libev) event loops those other event loops might be in an unusable
1561C<ev_check> watcher ran (always remind yourself to coexist peacefully with 1726state until their C<ev_check> watcher ran (always remind yourself to
1562others). 1727coexist peacefully with others).
1563 1728
1564=head3 Watcher-Specific Functions and Data Members 1729=head3 Watcher-Specific Functions and Data Members
1565 1730
1566=over 4 1731=over 4
1567 1732
… …
1791 1956
1792Make a single, non-blocking sweep over the embedded loop. This works 1957Make a single, non-blocking sweep over the embedded loop. This works
1793similarly to C<ev_loop (embedded_loop, EVLOOP_NONBLOCK)>, but in the most 1958similarly to C<ev_loop (embedded_loop, EVLOOP_NONBLOCK)>, but in the most
1794apropriate way for embedded loops. 1959apropriate way for embedded loops.
1795 1960
1796=item struct ev_loop *loop [read-only] 1961=item struct ev_loop *other [read-only]
1797 1962
1798The embedded event loop. 1963The embedded event loop.
1799 1964
1800=back 1965=back
1801 1966
… …
2140Libev can (and often is) directly embedded into host 2305Libev can (and often is) directly embedded into host
2141applications. Examples of applications that embed it include the Deliantra 2306applications. Examples of applications that embed it include the Deliantra
2142Game Server, the EV perl module, the GNU Virtual Private Ethernet (gvpe) 2307Game Server, the EV perl module, the GNU Virtual Private Ethernet (gvpe)
2143and rxvt-unicode. 2308and rxvt-unicode.
2144 2309
2145The goal is to enable you to just copy the neecssary files into your 2310The goal is to enable you to just copy the necessary files into your
2146source directory without having to change even a single line in them, so 2311source directory without having to change even a single line in them, so
2147you can easily upgrade by simply copying (or having a checked-out copy of 2312you can easily upgrade by simply copying (or having a checked-out copy of
2148libev somewhere in your source tree). 2313libev somewhere in your source tree).
2149 2314
2150=head2 FILESETS 2315=head2 FILESETS
… …
2240 2405
2241If defined to be C<1>, libev will try to detect the availability of the 2406If defined to be C<1>, libev will try to detect the availability of the
2242monotonic clock option at both compiletime and runtime. Otherwise no use 2407monotonic clock option at both compiletime and runtime. Otherwise no use
2243of the monotonic clock option will be attempted. If you enable this, you 2408of the monotonic clock option will be attempted. If you enable this, you
2244usually have to link against librt or something similar. Enabling it when 2409usually have to link against librt or something similar. Enabling it when
2245the functionality isn't available is safe, though, althoguh you have 2410the functionality isn't available is safe, though, although you have
2246to make sure you link against any libraries where the C<clock_gettime> 2411to make sure you link against any libraries where the C<clock_gettime>
2247function is hiding in (often F<-lrt>). 2412function is hiding in (often F<-lrt>).
2248 2413
2249=item EV_USE_REALTIME 2414=item EV_USE_REALTIME
2250 2415
2251If defined to be C<1>, libev will try to detect the availability of the 2416If defined to be C<1>, libev will try to detect the availability of the
2252realtime clock option at compiletime (and assume its availability at 2417realtime clock option at compiletime (and assume its availability at
2253runtime if successful). Otherwise no use of the realtime clock option will 2418runtime if successful). Otherwise no use of the realtime clock option will
2254be attempted. This effectively replaces C<gettimeofday> by C<clock_get 2419be attempted. This effectively replaces C<gettimeofday> by C<clock_get
2255(CLOCK_REALTIME, ...)> and will not normally affect correctness. See tzhe note about libraries 2420(CLOCK_REALTIME, ...)> and will not normally affect correctness. See the
2256in the description of C<EV_USE_MONOTONIC>, though. 2421note about libraries in the description of C<EV_USE_MONOTONIC>, though.
2422
2423=item EV_USE_NANOSLEEP
2424
2425If defined to be C<1>, libev will assume that C<nanosleep ()> is available
2426and will use it for delays. Otherwise it will use C<select ()>.
2257 2427
2258=item EV_USE_SELECT 2428=item EV_USE_SELECT
2259 2429
2260If undefined or defined to be C<1>, libev will compile in support for the 2430If undefined or defined to be C<1>, libev will compile in support for the
2261C<select>(2) backend. No attempt at autodetection will be done: if no 2431C<select>(2) backend. No attempt at autodetection will be done: if no
… …
2325be detected at runtime. 2495be detected at runtime.
2326 2496
2327=item EV_H 2497=item EV_H
2328 2498
2329The name of the F<ev.h> header file used to include it. The default if 2499The name of the F<ev.h> header file used to include it. The default if
2330undefined is C<< <ev.h> >> in F<event.h> and C<"ev.h"> in F<ev.c>. This 2500undefined is C<"ev.h"> in F<event.h> and F<ev.c>. This can be used to
2331can be used to virtually rename the F<ev.h> header file in case of conflicts. 2501virtually rename the F<ev.h> header file in case of conflicts.
2332 2502
2333=item EV_CONFIG_H 2503=item EV_CONFIG_H
2334 2504
2335If C<EV_STANDALONE> isn't C<1>, this variable can be used to override 2505If C<EV_STANDALONE> isn't C<1>, this variable can be used to override
2336F<ev.c>'s idea of where to find the F<config.h> file, similarly to 2506F<ev.c>'s idea of where to find the F<config.h> file, similarly to
2337C<EV_H>, above. 2507C<EV_H>, above.
2338 2508
2339=item EV_EVENT_H 2509=item EV_EVENT_H
2340 2510
2341Similarly to C<EV_H>, this macro can be used to override F<event.c>'s idea 2511Similarly to C<EV_H>, this macro can be used to override F<event.c>'s idea
2342of how the F<event.h> header can be found. 2512of how the F<event.h> header can be found, the dfeault is C<"event.h">.
2343 2513
2344=item EV_PROTOTYPES 2514=item EV_PROTOTYPES
2345 2515
2346If defined to be C<0>, then F<ev.h> will not define any function 2516If defined to be C<0>, then F<ev.h> will not define any function
2347prototypes, but still define all the structs and other symbols. This is 2517prototypes, but still define all the structs and other symbols. This is
… …
2413than enough. If you need to manage thousands of children you might want to 2583than enough. If you need to manage thousands of children you might want to
2414increase this value (I<must> be a power of two). 2584increase this value (I<must> be a power of two).
2415 2585
2416=item EV_INOTIFY_HASHSIZE 2586=item EV_INOTIFY_HASHSIZE
2417 2587
2418C<ev_staz> watchers use a small hash table to distribute workload by 2588C<ev_stat> watchers use a small hash table to distribute workload by
2419inotify watch id. The default size is C<16> (or C<1> with C<EV_MINIMAL>), 2589inotify watch id. The default size is C<16> (or C<1> with C<EV_MINIMAL>),
2420usually more than enough. If you need to manage thousands of C<ev_stat> 2590usually more than enough. If you need to manage thousands of C<ev_stat>
2421watchers you might want to increase this value (I<must> be a power of 2591watchers you might want to increase this value (I<must> be a power of
2422two). 2592two).
2423 2593
… …
2440 2610
2441=item ev_set_cb (ev, cb) 2611=item ev_set_cb (ev, cb)
2442 2612
2443Can be used to change the callback member declaration in each watcher, 2613Can be used to change the callback member declaration in each watcher,
2444and the way callbacks are invoked and set. Must expand to a struct member 2614and the way callbacks are invoked and set. Must expand to a struct member
2445definition and a statement, respectively. See the F<ev.v> header file for 2615definition and a statement, respectively. See the F<ev.h> header file for
2446their default definitions. One possible use for overriding these is to 2616their default definitions. One possible use for overriding these is to
2447avoid the C<struct ev_loop *> as first argument in all cases, or to use 2617avoid the C<struct ev_loop *> as first argument in all cases, or to use
2448method calls instead of plain function calls in C++. 2618method calls instead of plain function calls in C++.
2619
2620=head2 EXPORTED API SYMBOLS
2621
2622If you need to re-export the API (e.g. via a dll) and you need a list of
2623exported symbols, you can use the provided F<Symbol.*> files which list
2624all public symbols, one per line:
2625
2626 Symbols.ev for libev proper
2627 Symbols.event for the libevent emulation
2628
2629This can also be used to rename all public symbols to avoid clashes with
2630multiple versions of libev linked together (which is obviously bad in
2631itself, but sometimes it is inconvinient to avoid this).
2632
2633A sed command like this will create wrapper C<#define>'s that you need to
2634include before including F<ev.h>:
2635
2636 <Symbols.ev sed -e "s/.*/#define & myprefix_&/" >wrap.h
2637
2638This would create a file F<wrap.h> which essentially looks like this:
2639
2640 #define ev_backend myprefix_ev_backend
2641 #define ev_check_start myprefix_ev_check_start
2642 #define ev_check_stop myprefix_ev_check_stop
2643 ...
2449 2644
2450=head2 EXAMPLES 2645=head2 EXAMPLES
2451 2646
2452For a real-world example of a program the includes libev 2647For a real-world example of a program the includes libev
2453verbatim, you can have a look at the EV perl module 2648verbatim, you can have a look at the EV perl module
… …
2494 2689
2495=item Starting and stopping timer/periodic watchers: O(log skipped_other_timers) 2690=item Starting and stopping timer/periodic watchers: O(log skipped_other_timers)
2496 2691
2497This means that, when you have a watcher that triggers in one hour and 2692This means that, when you have a watcher that triggers in one hour and
2498there are 100 watchers that would trigger before that then inserting will 2693there are 100 watchers that would trigger before that then inserting will
2499have to skip those 100 watchers. 2694have to skip roughly seven (C<ld 100>) of these watchers.
2500 2695
2501=item Changing timer/periodic watchers (by autorepeat, again): O(log skipped_other_timers) 2696=item Changing timer/periodic watchers (by autorepeat or calling again): O(log skipped_other_timers)
2502 2697
2503That means that for changing a timer costs less than removing/adding them 2698That means that changing a timer costs less than removing/adding them
2504as only the relative motion in the event queue has to be paid for. 2699as only the relative motion in the event queue has to be paid for.
2505 2700
2506=item Starting io/check/prepare/idle/signal/child watchers: O(1) 2701=item Starting io/check/prepare/idle/signal/child watchers: O(1)
2507 2702
2508These just add the watcher into an array or at the head of a list. 2703These just add the watcher into an array or at the head of a list.
2704
2509=item Stopping check/prepare/idle watchers: O(1) 2705=item Stopping check/prepare/idle watchers: O(1)
2510 2706
2511=item Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % EV_PID_HASHSIZE)) 2707=item Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % EV_PID_HASHSIZE))
2512 2708
2513These watchers are stored in lists then need to be walked to find the 2709These watchers are stored in lists then need to be walked to find the
2514correct watcher to remove. The lists are usually short (you don't usually 2710correct watcher to remove. The lists are usually short (you don't usually
2515have many watchers waiting for the same fd or signal). 2711have many watchers waiting for the same fd or signal).
2516 2712
2517=item Finding the next timer per loop iteration: O(1) 2713=item Finding the next timer in each loop iteration: O(1)
2714
2715By virtue of using a binary heap, the next timer is always found at the
2716beginning of the storage array.
2518 2717
2519=item Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd) 2718=item Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd)
2520 2719
2521A change means an I/O watcher gets started or stopped, which requires 2720A change means an I/O watcher gets started or stopped, which requires
2522libev to recalculate its status (and possibly tell the kernel). 2721libev to recalculate its status (and possibly tell the kernel, depending
2722on backend and wether C<ev_io_set> was used).
2523 2723
2524=item Activating one watcher: O(1) 2724=item Activating one watcher (putting it into the pending state): O(1)
2525 2725
2526=item Priority handling: O(number_of_priorities) 2726=item Priority handling: O(number_of_priorities)
2527 2727
2528Priorities are implemented by allocating some space for each 2728Priorities are implemented by allocating some space for each
2529priority. When doing priority-based operations, libev usually has to 2729priority. When doing priority-based operations, libev usually has to
2530linearly search all the priorities. 2730linearly search all the priorities, but starting/stopping and activating
2731watchers becomes O(1) w.r.t. prioritiy handling.
2531 2732
2532=back 2733=back
2533 2734
2534 2735
2535=head1 AUTHOR 2736=head1 AUTHOR

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines