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

Comparing libev/ev.pod (file contents):
Revision 1.97 by root, Sat Dec 22 05:48:02 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;
… …
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
… …
306=item C<EVBACKEND_SELECT> (value 1, portable select backend) 306=item C<EVBACKEND_SELECT> (value 1, portable select backend)
307 307
308This is your standard select(2) backend. Not I<completely> standard, as 308This is your standard select(2) backend. Not I<completely> standard, as
309libev 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,
310but 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
311using 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
312the 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.
313 320
314=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)
315 322
316And this is your standard poll(2) backend. It's more complicated than 323And this is your standard poll(2) backend. It's more complicated
317select, but handles sparse fds better and has no artificial limit on the 324than select, but handles sparse fds better and has no artificial
318number 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
319lot 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.
320 329
321=item C<EVBACKEND_EPOLL> (value 4, Linux) 330=item C<EVBACKEND_EPOLL> (value 4, Linux)
322 331
323For 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,
324but it scales phenomenally better. While poll and select usually scale 333but it scales phenomenally better. While poll and select usually scale
325like O(total_fds) where n is the total number of fds (or the highest fd), 334like O(total_fds) where n is the total number of fds (or the highest fd),
326epoll scales either O(1) or O(active_fds). The epoll design has a number 335epoll scales either O(1) or O(active_fds). The epoll design has a number
327of shortcomings, such as silently dropping events in some hard-to-detect 336of shortcomings, such as silently dropping events in some hard-to-detect
328cases and rewiring a syscall per fd change, no fork support and bad 337cases and rewiring a syscall per fd change, no fork support and bad
329support for dup: 338support for dup.
330 339
331While stopping, setting and starting an I/O watcher in the same iteration 340While stopping, setting and starting an I/O watcher in the same iteration
332will result in some caching, there is still a syscall per such incident 341will result in some caching, there is still a syscall per such incident
333(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
334best to avoid that. Also, C<dup ()>'ed file descriptors might not work 343best to avoid that. Also, C<dup ()>'ed file descriptors might not work
… …
336 345
337Please note that epoll sometimes generates spurious notifications, so you 346Please note that epoll sometimes generates spurious notifications, so you
338need 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
339(or space) is available. 348(or space) is available.
340 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
341=item C<EVBACKEND_KQUEUE> (value 8, most BSD clones) 357=item C<EVBACKEND_KQUEUE> (value 8, most BSD clones)
342 358
343Kqueue deserves special mention, as at the time of this writing, it 359Kqueue deserves special mention, as at the time of this writing, it
344was broken on I<all> BSDs (usually it doesn't work with anything but 360was broken on all BSDs except NetBSD (usually it doesn't work reliably
345sockets and pipes, except on Darwin, where of course it's completely 361with anything but sockets and pipes, except on Darwin, where of course
346useless. On NetBSD, it seems to work for all the FD types I tested, so it
347is used by default there). For this reason it's not being "autodetected" 362it's completely useless). For this reason it's not being "autodetected"
348unless you explicitly specify it explicitly in the flags (i.e. using 363unless you explicitly specify it explicitly in the flags (i.e. using
349C<EVBACKEND_KQUEUE>) or libev was compiled on a known-to-be-good (-enough) 364C<EVBACKEND_KQUEUE>) or libev was compiled on a known-to-be-good (-enough)
350system like NetBSD. 365system like NetBSD.
351 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.
370
352It 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
353kernel is more efficient (which says nothing about its actual speed, 372kernel is more efficient (which says nothing about its actual speed, of
354of course). While stopping, setting and starting an I/O watcher does 373course). While stopping, setting and starting an I/O watcher does never
355never cause an extra syscall as with epoll, it still adds up to two event 374cause an extra syscall as with C<EVBACKEND_EPOLL>, it still adds up to
356changes per incident, support for C<fork ()> is very bad and it drops fds 375two event changes per incident, support for C<fork ()> is very bad and it
357silently in similarly hard-to-detetc cases. 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.
358 386
359=item C<EVBACKEND_DEVPOLL> (value 16, Solaris 8) 387=item C<EVBACKEND_DEVPOLL> (value 16, Solaris 8)
360 388
361This 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.
362 393
363=item C<EVBACKEND_PORT> (value 32, Solaris 10) 394=item C<EVBACKEND_PORT> (value 32, Solaris 10)
364 395
365This uses the Solaris 10 event port mechanism. As with everything on Solaris, 396This uses the Solaris 10 event port mechanism. As with everything on Solaris,
366it'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)).
367 398
368Please note that solaris event ports can deliver a lot of spurious 399Please note that solaris event ports can deliver a lot of spurious
369notifications, 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
370blocking when no data (or space) is available. 401blocking when no data (or space) is available.
371 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.
407
372=item C<EVBACKEND_ALL> 408=item C<EVBACKEND_ALL>
373 409
374Try all backends (even potentially broken ones that wouldn't be tried 410Try all backends (even potentially broken ones that wouldn't be tried
375with 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
376C<EVBACKEND_ALL & ~EVBACKEND_KQUEUE>. 412C<EVBACKEND_ALL & ~EVBACKEND_KQUEUE>.
413
414It is definitely not recommended to use this flag.
377 415
378=back 416=back
379 417
380If 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
381backends 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
… …
596overhead for the actual polling but can deliver many events at once. 634overhead for the actual polling but can deliver many events at once.
597 635
598By setting a higher I<io collect interval> you allow libev to spend more 636By setting a higher I<io collect interval> you allow libev to spend more
599time collecting I/O events, so you can handle more events per iteration, 637time collecting I/O events, so you can handle more events per iteration,
600at the cost of increasing latency. Timeouts (both C<ev_periodic> and 638at the cost of increasing latency. Timeouts (both C<ev_periodic> and
601C<ev_timer>) will be not affected. 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.
602 641
603Likewise, by setting a higher I<timeout collect interval> you allow libev 642Likewise, by setting a higher I<timeout collect interval> you allow libev
604to spend more time collecting timeouts, at the expense of increased 643to spend more time collecting timeouts, at the expense of increased
605latency (the watcher callback will be called later). C<ev_io> watchers 644latency (the watcher callback will be called later). C<ev_io> watchers
606will not be affected. 645will not be affected. Setting this to a non-null value will not introduce
646any overhead in libev.
607 647
608Many programs can usually benefit by setting the io collect interval to 648Many (busy) programs can usually benefit by setting the io collect
609a value near C<0.1> or so, which is often enough for interactive servers 649interval to a value near C<0.1> or so, which is often enough for
610(of course not for games), likewise for timeouts. It usually doesn't make 650interactive servers (of course not for games), likewise for timeouts. It
611much sense to set it to a lower value than C<0.01>, as this approsaches 651usually doesn't make much sense to set it to a lower value than C<0.01>,
612the timing granularity of most systems. 652as this approsaches the timing granularity of most systems.
613 653
614=back 654=back
615 655
616 656
617=head1 ANATOMY OF A WATCHER 657=head1 ANATOMY OF A WATCHER
… …
943In 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
944fd 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
945descriptors 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
946required if you know what you are doing). 986required if you know what you are doing).
947 987
948You have to be careful with dup'ed file descriptors, though. Some backends
949(the linux epoll backend is a notable example) cannot handle dup'ed file
950descriptors correctly if you register interest in two or more fds pointing
951to the same underlying file/socket/etc. description (that is, they share
952the same underlying "file open").
953
954If 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
955(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
956C<EVBACKEND_POLL>). 990C<EVBACKEND_POLL>).
957 991
958Another 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
… …
992optimisations to libev. 1026optimisations to libev.
993 1027
994=head3 The special problem of dup'ed file descriptors 1028=head3 The special problem of dup'ed file descriptors
995 1029
996Some backends (e.g. epoll), cannot register events for file descriptors, 1030Some backends (e.g. epoll), cannot register events for file descriptors,
997but only events for the underlying file descriptions. That menas when you 1031but only events for the underlying file descriptions. That means when you
998have C<dup ()>'ed file descriptors and register events for them, only one 1032have C<dup ()>'ed file descriptors or weirder constellations, and register
999file descriptor might actually receive events. 1033events for them, only one file descriptor might actually receive events.
1000 1034
1001There is no workaorund possible except not registering events 1035There is no workaround possible except not registering events
1002for potentially C<dup ()>'ed file descriptors or to resort to 1036for potentially C<dup ()>'ed file descriptors, or to resort to
1003C<EVBACKEND_SELECT> or C<EVBACKEND_POLL>. 1037C<EVBACKEND_SELECT> or C<EVBACKEND_POLL>.
1004 1038
1005=head3 The special problem of fork 1039=head3 The special problem of fork
1006 1040
1007Some backends (epoll, kqueue) do not support C<fork ()> at all or exhibit 1041Some backends (epoll, kqueue) do not support C<fork ()> at all or exhibit
… …
1456semantics of C<ev_stat> watchers, which means that libev sometimes needs 1490semantics of C<ev_stat> watchers, which means that libev sometimes needs
1457to 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
1458usually detected immediately, and if the file exists there will be no 1492usually detected immediately, and if the file exists there will be no
1459polling. 1493polling.
1460 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
1461=head3 Watcher-Specific Functions and Data Members 1528=head3 Watcher-Specific Functions and Data Members
1462 1529
1463=over 4 1530=over 4
1464 1531
1465=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)
… …
1502=item const char *path [read-only] 1569=item const char *path [read-only]
1503 1570
1504The filesystem path that is being watched. 1571The filesystem path that is being watched.
1505 1572
1506=back 1573=back
1574
1575=head3 Examples
1507 1576
1508Example: Watch C</etc/passwd> for attribute changes. 1577Example: Watch C</etc/passwd> for attribute changes.
1509 1578
1510 static void 1579 static void
1511 passwd_cb (struct ev_loop *loop, ev_stat *w, int revents) 1580 passwd_cb (struct ev_loop *loop, ev_stat *w, int revents)
… …
1524 } 1593 }
1525 1594
1526 ... 1595 ...
1527 ev_stat passwd; 1596 ev_stat passwd;
1528 1597
1529 ev_stat_init (&passwd, passwd_cb, "/etc/passwd"); 1598 ev_stat_init (&passwd, passwd_cb, "/etc/passwd", 0.);
1530 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);
1531 1628
1532 1629
1533=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...
1534 1631
1535Idle 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
… …
1621 1718
1622It 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>)
1623priority, to ensure that they are being run before any other watchers 1720priority, to ensure that they are being run before any other watchers
1624after 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,
1625too) should not activate ("feed") events into libev. While libev fully 1722too) should not activate ("feed") events into libev. While libev fully
1626supports this, they will be called before other C<ev_check> watchers did 1723supports this, they will be called before other C<ev_check> watchers
1627their 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
1628loops 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
1629C<ev_check> watcher ran (always remind yourself to coexist peacefully with 1726state until their C<ev_check> watcher ran (always remind yourself to
1630others). 1727coexist peacefully with others).
1631 1728
1632=head3 Watcher-Specific Functions and Data Members 1729=head3 Watcher-Specific Functions and Data Members
1633 1730
1634=over 4 1731=over 4
1635 1732
… …
1774=head2 C<ev_embed> - when one backend isn't enough... 1871=head2 C<ev_embed> - when one backend isn't enough...
1775 1872
1776This is a rather advanced watcher type that lets you embed one event loop 1873This is a rather advanced watcher type that lets you embed one event loop
1777into another (currently only C<ev_io> events are supported in the embedded 1874into another (currently only C<ev_io> events are supported in the embedded
1778loop, other types of watchers might be handled in a delayed or incorrect 1875loop, other types of watchers might be handled in a delayed or incorrect
1779fashion and must not be used). (See portability notes, below). 1876fashion and must not be used).
1780 1877
1781There are primarily two reasons you would want that: work around bugs and 1878There are primarily two reasons you would want that: work around bugs and
1782prioritise I/O. 1879prioritise I/O.
1783 1880
1784As an example for a bug workaround, the kqueue backend might only support 1881As an example for a bug workaround, the kqueue backend might only support
… …
1839 ev_embed_start (loop_hi, &embed); 1936 ev_embed_start (loop_hi, &embed);
1840 } 1937 }
1841 else 1938 else
1842 loop_lo = loop_hi; 1939 loop_lo = loop_hi;
1843 1940
1844=head2 Portability notes
1845
1846Kqueue is nominally embeddable, but this is broken on all BSDs that I
1847tried, in various ways. Usually the embedded event loop will simply never
1848receive events, sometimes it will only trigger a few times, sometimes in a
1849loop. Epoll is also nominally embeddable, but many Linux kernel versions
1850will always eport the epoll fd as ready, even when no events are pending.
1851
1852While libev allows embedding these backends (they are contained in
1853C<ev_embeddable_backends ()>), take extreme care that it will actually
1854work.
1855
1856When in doubt, create a dynamic event loop forced to use sockets (this
1857usually works) and possibly another thread and a pipe or so to report to
1858your main event loop.
1859
1860=head3 Watcher-Specific Functions and Data Members 1941=head3 Watcher-Specific Functions and Data Members
1861 1942
1862=over 4 1943=over 4
1863 1944
1864=item ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop) 1945=item ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop)
… …
2414be detected at runtime. 2495be detected at runtime.
2415 2496
2416=item EV_H 2497=item EV_H
2417 2498
2418The 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
2419undefined 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
2420can 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.
2421 2502
2422=item EV_CONFIG_H 2503=item EV_CONFIG_H
2423 2504
2424If 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
2425F<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
2426C<EV_H>, above. 2507C<EV_H>, above.
2427 2508
2428=item EV_EVENT_H 2509=item EV_EVENT_H
2429 2510
2430Similarly 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
2431of 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">.
2432 2513
2433=item EV_PROTOTYPES 2514=item EV_PROTOTYPES
2434 2515
2435If 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
2436prototypes, but still define all the structs and other symbols. This is 2517prototypes, but still define all the structs and other symbols. This is
… …
2502than 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
2503increase this value (I<must> be a power of two). 2584increase this value (I<must> be a power of two).
2504 2585
2505=item EV_INOTIFY_HASHSIZE 2586=item EV_INOTIFY_HASHSIZE
2506 2587
2507C<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
2508inotify 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>),
2509usually 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>
2510watchers 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
2511two). 2592two).
2512 2593
… …
2608 2689
2609=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)
2610 2691
2611This 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
2612there are 100 watchers that would trigger before that then inserting will 2693there are 100 watchers that would trigger before that then inserting will
2613have to skip those 100 watchers. 2694have to skip roughly seven (C<ld 100>) of these watchers.
2614 2695
2615=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)
2616 2697
2617That means that for changing a timer costs less than removing/adding them 2698That means that changing a timer costs less than removing/adding them
2618as 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.
2619 2700
2620=item Starting io/check/prepare/idle/signal/child watchers: O(1) 2701=item Starting io/check/prepare/idle/signal/child watchers: O(1)
2621 2702
2622These 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
2623=item Stopping check/prepare/idle watchers: O(1) 2705=item Stopping check/prepare/idle watchers: O(1)
2624 2706
2625=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))
2626 2708
2627These 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
2628correct 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
2629have many watchers waiting for the same fd or signal). 2711have many watchers waiting for the same fd or signal).
2630 2712
2631=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.
2632 2717
2633=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)
2634 2719
2635A 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
2636libev 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).
2637 2723
2638=item Activating one watcher: O(1) 2724=item Activating one watcher (putting it into the pending state): O(1)
2639 2725
2640=item Priority handling: O(number_of_priorities) 2726=item Priority handling: O(number_of_priorities)
2641 2727
2642Priorities are implemented by allocating some space for each 2728Priorities are implemented by allocating some space for each
2643priority. When doing priority-based operations, libev usually has to 2729priority. When doing priority-based operations, libev usually has to
2644linearly search all the priorities. 2730linearly search all the priorities, but starting/stopping and activating
2731watchers becomes O(1) w.r.t. prioritiy handling.
2645 2732
2646=back 2733=back
2647 2734
2648 2735
2649=head1 AUTHOR 2736=head1 AUTHOR

Diff Legend

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