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

Comparing libev/ev.pod (file contents):
Revision 1.145 by root, Wed Apr 9 22:07:50 2008 UTC vs.
Revision 1.150 by root, Tue May 6 23:34:16 2008 UTC

… …
1373Simply stops and restarts the periodic watcher again. This is only useful 1373Simply stops and restarts the periodic watcher again. This is only useful
1374when you changed some parameters or the reschedule callback would return 1374when you changed some parameters or the reschedule callback would return
1375a different time than the last time it was called (e.g. in a crond like 1375a different time than the last time it was called (e.g. in a crond like
1376program when the crontabs have changed). 1376program when the crontabs have changed).
1377 1377
1378=item ev_tstamp ev_periodic_at (ev_periodic *)
1379
1380When active, returns the absolute time that the watcher is supposed to
1381trigger next.
1382
1378=item ev_tstamp offset [read-write] 1383=item ev_tstamp offset [read-write]
1379 1384
1380When repeating, this contains the offset value, otherwise this is the 1385When repeating, this contains the offset value, otherwise this is the
1381absolute point in time (the C<at> value passed to C<ev_periodic_set>). 1386absolute point in time (the C<at> value passed to C<ev_periodic_set>).
1382 1387
… …
1392=item ev_tstamp (*reschedule_cb)(struct ev_periodic *w, ev_tstamp now) [read-write] 1397=item ev_tstamp (*reschedule_cb)(struct ev_periodic *w, ev_tstamp now) [read-write]
1393 1398
1394The current reschedule callback, or C<0>, if this functionality is 1399The current reschedule callback, or C<0>, if this functionality is
1395switched off. Can be changed any time, but changes only take effect when 1400switched off. Can be changed any time, but changes only take effect when
1396the periodic timer fires or C<ev_periodic_again> is being called. 1401the periodic timer fires or C<ev_periodic_again> is being called.
1397
1398=item ev_tstamp at [read-only]
1399
1400When active, contains the absolute time that the watcher is supposed to
1401trigger next.
1402 1402
1403=back 1403=back
1404 1404
1405=head3 Examples 1405=head3 Examples
1406 1406
… …
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
… …
1634When C<inotify (7)> support has been compiled into libev (generally only 1635When C<inotify (7)> support has been compiled into libev (generally only
1635available on Linux) and present at runtime, it will be used to speed up 1636available on Linux) and present at runtime, it will be used to speed up
1636change detection where possible. The inotify descriptor will be created lazily 1637change detection where possible. The inotify descriptor will be created lazily
1637when the first C<ev_stat> watcher is being started. 1638when the first C<ev_stat> watcher is being started.
1638 1639
1639Inotify presense does not change the semantics of C<ev_stat> watchers 1640Inotify presence does not change the semantics of C<ev_stat> watchers
1640except that changes might be detected earlier, and in some cases, to avoid 1641except that changes might be detected earlier, and in some cases, to avoid
1641making regular C<stat> calls. Even in the presense of inotify support 1642making regular C<stat> calls. Even in the presence of inotify support
1642there are many cases where libev has to resort to regular C<stat> polling. 1643there are many cases where libev has to resort to regular C<stat> polling.
1643 1644
1644(There is no support for kqueue, as apparently it cannot be used to 1645(There is no support for kqueue, as apparently it cannot be used to
1645implement this functionality, due to the requirement of having a file 1646implement this functionality, due to the requirement of having a file
1646descriptor open on the object at all times). 1647descriptor open on the object at all times).
… …
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
… …
2378 2392
2379=item * Priorities are not currently supported. Initialising priorities 2393=item * Priorities are not currently supported. Initialising priorities
2380will fail and all watchers will have the same priority, even though there 2394will fail and all watchers will have the same priority, even though there
2381is an ev_pri field. 2395is an ev_pri field.
2382 2396
2397=item * In libevent, the last base created gets the signals, in libev, the
2398first base created (== the default loop) gets the signals.
2399
2383=item * Other members are not supported. 2400=item * Other members are not supported.
2384 2401
2385=item * The libev emulation is I<not> ABI compatible to libevent, you need 2402=item * The libev emulation is I<not> ABI compatible to libevent, you need
2386to use the libev header file and library. 2403to use the libev header file and library.
2387 2404
… …
3199model. Libev still offers limited functionality on this platform in 3216model. Libev still offers limited functionality on this platform in
3200the form of the C<EVBACKEND_SELECT> backend, and only supports socket 3217the form of the C<EVBACKEND_SELECT> backend, and only supports socket
3201descriptors. This only applies when using Win32 natively, not when using 3218descriptors. This only applies when using Win32 natively, not when using
3202e.g. cygwin. 3219e.g. cygwin.
3203 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
3204There is no supported compilation method available on windows except 3226There is no supported compilation method available on windows except
3205embedding it into other applications. 3227embedding it into other applications.
3206 3228
3207Due 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
3208abysmal performance of winsockets, using a large number of sockets is not 3230the abysmal performance of winsockets, using a large number of sockets
3209recommended (and not reasonable). If your program needs to use more than 3231is not recommended (and not reasonable). If your program needs to use
3210a 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
3211implementation for windows, as libev offers the POSIX model, which cannot 3233different implementation for windows, as libev offers the POSIX readyness
3212be implemented efficiently on windows (microsoft monopoly games). 3234notification model, which cannot be implemented efficiently on windows
3235(microsoft monopoly games).
3213 3236
3214=over 4 3237=over 4
3215 3238
3216=item The winsocket select function 3239=item The winsocket select function
3217 3240
… …
3231Note 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
3232complexity in the O(n²) range when using win32. 3255complexity in the O(n²) range when using win32.
3233 3256
3234=item Limited number of file descriptors 3257=item Limited number of file descriptors
3235 3258
3236Windows has numerous arbitrary (and low) limits on things. Early versions 3259Windows has numerous arbitrary (and low) limits on things.
3237of 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
3238(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
3239C<64> things at the same time internally; microsoft recommends spawning a 3263can only wait for C<64> things at the same time internally; microsoft
3240chain 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).
3241 3266
3242Newer 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>
3243to 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
3244call (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
3245select emulation on windows). 3270select emulation on windows).
… …
3257calling select (O(n²)) will likely make this unworkable. 3282calling select (O(n²)) will likely make this unworkable.
3258 3283
3259=back 3284=back
3260 3285
3261 3286
3287=head1 PORTABILITY REQUIREMENTS
3288
3289In addition to a working ISO-C implementation, libev relies on a few
3290additional extensions:
3291
3292=over 4
3293
3294=item C<sig_atomic_t volatile> must be thread-atomic as well
3295
3296The type C<sig_atomic_t volatile> (or whatever is defined as
3297C<EV_ATOMIC_T>) must be atomic w.r.t. accesses from different
3298threads. This is not part of the specification for C<sig_atomic_t>, but is
3299believed to be sufficiently portable.
3300
3301=item C<sigprocmask> must work in a threaded environment
3302
3303Libev uses C<sigprocmask> to temporarily block signals. This is not
3304allowed in a threaded program (C<pthread_sigmask> has to be used). Typical
3305pthread implementations will either allow C<sigprocmask> in the "main
3306thread" or will block signals process-wide, both behaviours would
3307be compatible with libev. Interaction between C<sigprocmask> and
3308C<pthread_sigmask> could complicate things, however.
3309
3310The most portable way to handle signals is to block signals in all threads
3311except the initial one, and run the default loop in the initial thread as
3312well.
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
3329=back
3330
3331If you know of other additional requirements drop me a note.
3332
3333
3262=head1 AUTHOR 3334=head1 AUTHOR
3263 3335
3264Marc Lehmann <libev@schmorp.de>. 3336Marc Lehmann <libev@schmorp.de>.
3265 3337

Diff Legend

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