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

Comparing libev/ev.pod (file contents):
Revision 1.149 by root, Fri May 2 08:36:20 2008 UTC vs.
Revision 1.150 by root, Tue May 6 23:34:16 2008 UTC

… …
1610as even with OS-supported change notifications, this can be 1610as even with OS-supported change notifications, this can be
1611resource-intensive. 1611resource-intensive.
1612 1612
1613At the time of this writing, only the Linux inotify interface is 1613At the time of this writing, only the Linux inotify interface is
1614implemented (implementing kqueue support is left as an exercise for the 1614implemented (implementing kqueue support is left as an exercise for the
1615reader, note, however, that the author sees no way of implementing ev_stat
1615reader). Inotify will be used to give hints only and should not change the 1616semantics with kqueue). Inotify will be used to give hints only and should
1616semantics of C<ev_stat> watchers, which means that libev sometimes needs 1617not change the semantics of C<ev_stat> watchers, which means that libev
1617to fall back to regular polling again even with inotify, but changes are 1618sometimes needs to fall back to regular polling again even with inotify,
1618usually detected immediately, and if the file exists there will be no 1619but changes are usually detected immediately, and if the file exists there
1619polling. 1620will be no polling.
1620 1621
1621=head3 ABI Issues (Largefile Support) 1622=head3 ABI Issues (Largefile Support)
1622 1623
1623Libev by default (unless the user overrides this) uses the default 1624Libev by default (unless the user overrides this) uses the default
1624compilation environment, which means that on systems with optionally 1625compilation environment, which means that on systems with optionally
… …
1649 1650
1650The C<stat ()> syscall only supports full-second resolution portably, and 1651The C<stat ()> syscall only supports full-second resolution portably, and
1651even on systems where the resolution is higher, many filesystems still 1652even on systems where the resolution is higher, many filesystems still
1652only support whole seconds. 1653only support whole seconds.
1653 1654
1654That means that, if the time is the only thing that changes, you might 1655That means that, if the time is the only thing that changes, you can
1655miss updates: on the first update, C<ev_stat> detects a change and calls 1656easily miss updates: on the first update, C<ev_stat> detects a change and
1656your callback, which does something. When there is another update within 1657calls your callback, which does something. When there is another update
1657the same second, C<ev_stat> will be unable to detect it. 1658within the same second, C<ev_stat> will be unable to detect it as the stat
1659data does not change.
1658 1660
1659The solution to this is to delay acting on a change for a second (or till 1661The solution to this is to delay acting on a change for slightly more
1660the next second boundary), using a roughly one-second delay C<ev_timer> 1662than second (or till slightly after the next full second boundary), using
1661(C<ev_timer_set (w, 0., 1.01); ev_timer_again (loop, w)>). The C<.01> 1663a roughly one-second-delay C<ev_timer> (e.g. C<ev_timer_set (w, 0., 1.02);
1662is added to work around small timing inconsistencies of some operating 1664ev_timer_again (loop, w)>).
1663systems. 1665
1666The C<.02> offset is added to work around small timing inconsistencies
1667of some operating systems (where the second counter of the current time
1668might be be delayed. One such system is the Linux kernel, where a call to
1669C<gettimeofday> might return a timestamp with a full second later than
1670a subsequent C<time> call - if the equivalent of C<time ()> is used to
1671update file times then there will be a small window where the kernel uses
1672the previous second to update file times but libev might already execute
1673the timer callback).
1664 1674
1665=head3 Watcher-Specific Functions and Data Members 1675=head3 Watcher-Specific Functions and Data Members
1666 1676
1667=over 4 1677=over 4
1668 1678
… …
1674C<path>. The C<interval> is a hint on how quickly a change is expected to 1684C<path>. The C<interval> is a hint on how quickly a change is expected to
1675be detected and should normally be specified as C<0> to let libev choose 1685be detected and should normally be specified as C<0> to let libev choose
1676a suitable value. The memory pointed to by C<path> must point to the same 1686a suitable value. The memory pointed to by C<path> must point to the same
1677path for as long as the watcher is active. 1687path for as long as the watcher is active.
1678 1688
1679The callback will be receive C<EV_STAT> when a change was detected, 1689The callback will receive C<EV_STAT> when a change was detected, relative
1680relative to the attributes at the time the watcher was started (or the 1690to the attributes at the time the watcher was started (or the last change
1681last change was detected). 1691was detected).
1682 1692
1683=item ev_stat_stat (loop, ev_stat *) 1693=item ev_stat_stat (loop, ev_stat *)
1684 1694
1685Updates the stat buffer immediately with new values. If you change the 1695Updates the stat buffer immediately with new values. If you change the
1686watched path in your callback, you could call this fucntion to avoid 1696watched path in your callback, you could call this function to avoid
1687detecting this change (while introducing a race condition). Can also be 1697detecting this change (while introducing a race condition if you are not
1688useful simply to find out the new values. 1698the only one changing the path). Can also be useful simply to find out the
1699new values.
1689 1700
1690=item ev_statdata attr [read-only] 1701=item ev_statdata attr [read-only]
1691 1702
1692The most-recently detected attributes of the file. Although the type is of 1703The most-recently detected attributes of the file. Although the type is
1693C<ev_statdata>, this is usually the (or one of the) C<struct stat> types 1704C<ev_statdata>, this is usually the (or one of the) C<struct stat> types
1694suitable for your system. If the C<st_nlink> member is C<0>, then there 1705suitable for your system, but you can only rely on the POSIX-standardised
1706members to be present. If the C<st_nlink> member is C<0>, then there was
1695was some error while C<stat>ing the file. 1707some error while C<stat>ing the file.
1696 1708
1697=item ev_statdata prev [read-only] 1709=item ev_statdata prev [read-only]
1698 1710
1699The previous attributes of the file. The callback gets invoked whenever 1711The previous attributes of the file. The callback gets invoked whenever
1700C<prev> != C<attr>. 1712C<prev> != C<attr>, or, more precisely, one or more of these members
1713differ: C<st_dev>, C<st_ino>, C<st_mode>, C<st_nlink>, C<st_uid>,
1714C<st_gid>, C<st_rdev>, C<st_size>, C<st_atime>, C<st_mtime>, C<st_ctime>.
1701 1715
1702=item ev_tstamp interval [read-only] 1716=item ev_tstamp interval [read-only]
1703 1717
1704The specified interval. 1718The specified interval.
1705 1719
… …
1759 } 1773 }
1760 1774
1761 ... 1775 ...
1762 ev_stat_init (&passwd, stat_cb, "/etc/passwd", 0.); 1776 ev_stat_init (&passwd, stat_cb, "/etc/passwd", 0.);
1763 ev_stat_start (loop, &passwd); 1777 ev_stat_start (loop, &passwd);
1764 ev_timer_init (&timer, timer_cb, 0., 1.01); 1778 ev_timer_init (&timer, timer_cb, 0., 1.02);
1765 1779
1766 1780
1767=head2 C<ev_idle> - when you've got nothing better to do... 1781=head2 C<ev_idle> - when you've got nothing better to do...
1768 1782
1769Idle watchers trigger events when no other events of the same or higher 1783Idle watchers trigger events when no other events of the same or higher
… …
1857 1871
1858It is recommended to give C<ev_check> watchers highest (C<EV_MAXPRI>) 1872It is recommended to give C<ev_check> watchers highest (C<EV_MAXPRI>)
1859priority, to ensure that they are being run before any other watchers 1873priority, to ensure that they are being run before any other watchers
1860after the poll. Also, C<ev_check> watchers (and C<ev_prepare> watchers, 1874after the poll. Also, C<ev_check> watchers (and C<ev_prepare> watchers,
1861too) should not activate ("feed") events into libev. While libev fully 1875too) should not activate ("feed") events into libev. While libev fully
1862supports this, they will be called before other C<ev_check> watchers 1876supports this, they might get executed before other C<ev_check> watchers
1863did their job. As C<ev_check> watchers are often used to embed other 1877did their job. As C<ev_check> watchers are often used to embed other
1864(non-libev) event loops those other event loops might be in an unusable 1878(non-libev) event loops those other event loops might be in an unusable
1865state until their C<ev_check> watcher ran (always remind yourself to 1879state until their C<ev_check> watcher ran (always remind yourself to
1866coexist peacefully with others). 1880coexist peacefully with others).
1867 1881
… …
1882=head3 Examples 1896=head3 Examples
1883 1897
1884There are a number of principal ways to embed other event loops or modules 1898There are a number of principal ways to embed other event loops or modules
1885into libev. Here are some ideas on how to include libadns into libev 1899into libev. Here are some ideas on how to include libadns into libev
1886(there is a Perl module named C<EV::ADNS> that does this, which you could 1900(there is a Perl module named C<EV::ADNS> that does this, which you could
1887use for an actually working example. Another Perl module named C<EV::Glib> 1901use as a working example. Another Perl module named C<EV::Glib> embeds a
1888embeds a Glib main context into libev, and finally, C<Glib::EV> embeds EV 1902Glib main context into libev, and finally, C<Glib::EV> embeds EV into the
1889into the Glib event loop). 1903Glib event loop).
1890 1904
1891Method 1: Add IO watchers and a timeout watcher in a prepare handler, 1905Method 1: Add IO watchers and a timeout watcher in a prepare handler,
1892and in a check watcher, destroy them and call into libadns. What follows 1906and in a check watcher, destroy them and call into libadns. What follows
1893is pseudo-code only of course. This requires you to either use a low 1907is pseudo-code only of course. This requires you to either use a low
1894priority for the check watcher or use C<ev_clear_pending> explicitly, as 1908priority for the check watcher or use C<ev_clear_pending> explicitly, as
… …
3202model. Libev still offers limited functionality on this platform in 3216model. Libev still offers limited functionality on this platform in
3203the form of the C<EVBACKEND_SELECT> backend, and only supports socket 3217the form of the C<EVBACKEND_SELECT> backend, and only supports socket
3204descriptors. This only applies when using Win32 natively, not when using 3218descriptors. This only applies when using Win32 natively, not when using
3205e.g. cygwin. 3219e.g. cygwin.
3206 3220
3221Lifting these limitations would basically require the full
3222re-implementation of the I/O system. If you are into these kinds of
3223things, then note that glib does exactly that for you in a very portable
3224way (note also that glib is the slowest event library known to man).
3225
3207There is no supported compilation method available on windows except 3226There is no supported compilation method available on windows except
3208embedding it into other applications. 3227embedding it into other applications.
3209 3228
3210Due to the many, low, and arbitrary limits on the win32 platform and the 3229Due to the many, low, and arbitrary limits on the win32 platform and
3211abysmal performance of winsockets, using a large number of sockets is not 3230the abysmal performance of winsockets, using a large number of sockets
3212recommended (and not reasonable). If your program needs to use more than 3231is not recommended (and not reasonable). If your program needs to use
3213a hundred or so sockets, then likely it needs to use a totally different 3232more than a hundred or so sockets, then likely it needs to use a totally
3214implementation for windows, as libev offers the POSIX model, which cannot 3233different implementation for windows, as libev offers the POSIX readyness
3215be implemented efficiently on windows (microsoft monopoly games). 3234notification model, which cannot be implemented efficiently on windows
3235(microsoft monopoly games).
3216 3236
3217=over 4 3237=over 4
3218 3238
3219=item The winsocket select function 3239=item The winsocket select function
3220 3240
… …
3234Note that winsockets handling of fd sets is O(n), so you can easily get a 3254Note that winsockets handling of fd sets is O(n), so you can easily get a
3235complexity in the O(n²) range when using win32. 3255complexity in the O(n²) range when using win32.
3236 3256
3237=item Limited number of file descriptors 3257=item Limited number of file descriptors
3238 3258
3239Windows has numerous arbitrary (and low) limits on things. Early versions 3259Windows has numerous arbitrary (and low) limits on things.
3240of winsocket's select only supported waiting for a max. of C<64> handles 3260
3261Early versions of winsocket's select only supported waiting for a maximum
3241(probably owning to the fact that all windows kernels can only wait for 3262of C<64> handles (probably owning to the fact that all windows kernels
3242C<64> things at the same time internally; microsoft recommends spawning a 3263can only wait for C<64> things at the same time internally; microsoft
3243chain of threads and wait for 63 handles and the previous thread in each). 3264recommends spawning a chain of threads and wait for 63 handles and the
3265previous thread in each. Great).
3244 3266
3245Newer versions support more handles, but you need to define C<FD_SETSIZE> 3267Newer versions support more handles, but you need to define C<FD_SETSIZE>
3246to some high number (e.g. C<2048>) before compiling the winsocket select 3268to some high number (e.g. C<2048>) before compiling the winsocket select
3247call (which might be in libev or elsewhere, for example, perl does its own 3269call (which might be in libev or elsewhere, for example, perl does its own
3248select emulation on windows). 3270select emulation on windows).
… …
3287 3309
3288The most portable way to handle signals is to block signals in all threads 3310The most portable way to handle signals is to block signals in all threads
3289except the initial one, and run the default loop in the initial thread as 3311except the initial one, and run the default loop in the initial thread as
3290well. 3312well.
3291 3313
3314=item C<long> must be large enough for common memory allocation sizes
3315
3316To improve portability and simplify using libev, libev uses C<long>
3317internally instead of C<size_t> when allocating its data structures. On
3318non-POSIX systems (Microsoft...) this might be unexpectedly low, but
3319is still at least 31 bits everywhere, which is enough for hundreds of
3320millions of watchers.
3321
3322=item C<double> must hold a time value in seconds with enough accuracy
3323
3324The type C<double> is used to represent timestamps. It is required to have
3325at least 51 bits of mantissa, which is good enough for at least into the
3326year 4000. This requirement is fulfilled by implementations implementing
3327IEEE 754 (basically all existing ones).
3328
3292=back 3329=back
3293 3330
3294If you know of other additional requirements drop me a note. 3331If you know of other additional requirements drop me a note.
3295 3332
3296 3333

Diff Legend

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