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

Comparing libev/ev.pod (file contents):
Revision 1.148 by root, Thu Apr 24 01:42:11 2008 UTC vs.
Revision 1.152 by root, Wed May 7 14:45:17 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
… …
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
… …
2966defined to be C<0>, then they are not. 2980defined to be C<0>, then they are not.
2967 2981
2968=item EV_MINIMAL 2982=item EV_MINIMAL
2969 2983
2970If you need to shave off some kilobytes of code at the expense of some 2984If you need to shave off some kilobytes of code at the expense of some
2971speed, define this symbol to C<1>. Currently only used for gcc to override 2985speed, define this symbol to C<1>. Currently this is used to override some
2972some inlining decisions, saves roughly 30% codesize of amd64. 2986inlining decisions, saves roughly 30% codesize of amd64. It also selects a
2987much smaller 2-heap for timer management over the default 4-heap.
2973 2988
2974=item EV_PID_HASHSIZE 2989=item EV_PID_HASHSIZE
2975 2990
2976C<ev_child> watchers use a small hash table to distribute workload by 2991C<ev_child> watchers use a small hash table to distribute workload by
2977pid. The default size is C<16> (or C<1> with C<EV_MINIMAL>), usually more 2992pid. The default size is C<16> (or C<1> with C<EV_MINIMAL>), usually more
… …
3162correct watcher to remove. The lists are usually short (you don't usually 3177correct watcher to remove. The lists are usually short (you don't usually
3163have many watchers waiting for the same fd or signal). 3178have many watchers waiting for the same fd or signal).
3164 3179
3165=item Finding the next timer in each loop iteration: O(1) 3180=item Finding the next timer in each loop iteration: O(1)
3166 3181
3167By virtue of using a binary heap, the next timer is always found at the 3182By virtue of using a binary or 4-heap, the next timer is always found at a
3168beginning of the storage array. 3183fixed position in the storage array.
3169 3184
3170=item Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd) 3185=item Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd)
3171 3186
3172A change means an I/O watcher gets started or stopped, which requires 3187A change means an I/O watcher gets started or stopped, which requires
3173libev to recalculate its status (and possibly tell the kernel, depending 3188libev to recalculate its status (and possibly tell the kernel, depending
… …
3202model. Libev still offers limited functionality on this platform in 3217model. Libev still offers limited functionality on this platform in
3203the form of the C<EVBACKEND_SELECT> backend, and only supports socket 3218the form of the C<EVBACKEND_SELECT> backend, and only supports socket
3204descriptors. This only applies when using Win32 natively, not when using 3219descriptors. This only applies when using Win32 natively, not when using
3205e.g. cygwin. 3220e.g. cygwin.
3206 3221
3222Lifting these limitations would basically require the full
3223re-implementation of the I/O system. If you are into these kinds of
3224things, then note that glib does exactly that for you in a very portable
3225way (note also that glib is the slowest event library known to man).
3226
3207There is no supported compilation method available on windows except 3227There is no supported compilation method available on windows except
3208embedding it into other applications. 3228embedding it into other applications.
3209 3229
3210Due to the many, low, and arbitrary limits on the win32 platform and the 3230Due to the many, low, and arbitrary limits on the win32 platform and
3211abysmal performance of winsockets, using a large number of sockets is not 3231the abysmal performance of winsockets, using a large number of sockets
3212recommended (and not reasonable). If your program needs to use more than 3232is 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 3233more 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 3234different implementation for windows, as libev offers the POSIX readyness
3215be implemented efficiently on windows (microsoft monopoly games). 3235notification model, which cannot be implemented efficiently on windows
3236(microsoft monopoly games).
3216 3237
3217=over 4 3238=over 4
3218 3239
3219=item The winsocket select function 3240=item The winsocket select function
3220 3241
… …
3234Note that winsockets handling of fd sets is O(n), so you can easily get a 3255Note that winsockets handling of fd sets is O(n), so you can easily get a
3235complexity in the O(n²) range when using win32. 3256complexity in the O(n²) range when using win32.
3236 3257
3237=item Limited number of file descriptors 3258=item Limited number of file descriptors
3238 3259
3239Windows has numerous arbitrary (and low) limits on things. Early versions 3260Windows has numerous arbitrary (and low) limits on things.
3240of winsocket's select only supported waiting for a max. of C<64> handles 3261
3262Early 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 3263of C<64> handles (probably owning to the fact that all windows kernels
3242C<64> things at the same time internally; microsoft recommends spawning a 3264can 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). 3265recommends spawning a chain of threads and wait for 63 handles and the
3266previous thread in each. Great).
3244 3267
3245Newer versions support more handles, but you need to define C<FD_SETSIZE> 3268Newer 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 3269to 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 3270call (which might be in libev or elsewhere, for example, perl does its own
3248select emulation on windows). 3271select emulation on windows).
… …
3287 3310
3288The most portable way to handle signals is to block signals in all threads 3311The 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 3312except the initial one, and run the default loop in the initial thread as
3290well. 3313well.
3291 3314
3315=item C<long> must be large enough for common memory allocation sizes
3316
3317To improve portability and simplify using libev, libev uses C<long>
3318internally instead of C<size_t> when allocating its data structures. On
3319non-POSIX systems (Microsoft...) this might be unexpectedly low, but
3320is still at least 31 bits everywhere, which is enough for hundreds of
3321millions of watchers.
3322
3323=item C<double> must hold a time value in seconds with enough accuracy
3324
3325The type C<double> is used to represent timestamps. It is required to
3326have at least 51 bits of mantissa (and 9 bits of exponent), which is good
3327enough for at least into the year 4000. This requirement is fulfilled by
3328implementations implementing IEEE 754 (basically all existing ones).
3329
3292=back 3330=back
3293 3331
3294If you know of other additional requirements drop me a note. 3332If you know of other additional requirements drop me a note.
3295 3333
3296 3334

Diff Legend

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