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