X-Git-Url: https://git.llucax.com/software/libev.git/blobdiff_plain/fe7222913a6e42b65bfd92bc38479714316cfaf3..6fb30a67f78730c733f64429f327e360ea2acaf3:/ev.pod diff --git a/ev.pod b/ev.pod index 237bdb0..d3d9910 100644 --- a/ev.pod +++ b/ev.pod @@ -100,7 +100,9 @@ Libev represents time as a single floating point number, representing the the beginning of 1970, details are complicated, don't ask). This type is called C, which is what you should use too. It usually aliases to the C type in C, and when you need to do any calculations on -it, you should treat it as such. +it, you should treat it as some floatingpoint value. Unlike the name +component C might indicate, it is also used for time differences +throughout libev. =head1 GLOBAL FUNCTIONS @@ -119,14 +121,17 @@ you actually want to know. =item int ev_version_minor () -You can find out the major and minor version numbers of the library +You can find out the major and minor ABI version numbers of the library you linked against by calling the functions C and C. If you want, you can compare against the global symbols C and C, which specify the version of the library your program was compiled against. +These version numbers refer to the ABI version of the library, not the +release version. + Usually, it's a good idea to terminate if the major versions mismatch, -as this indicates an incompatible change. Minor versions are usually +as this indicates an incompatible change. Minor versions are usually compatible to older versions, so a larger minor version alone is usually not a problem. @@ -910,6 +915,30 @@ whether a file descriptor is really ready with a known-to-be good interface such as poll (fortunately in our Xlib example, Xlib already does this on its own, so its quite safe to use). +=head3 The special problem of disappearing file descriptors + +Some backends (e.g kqueue, epoll) need to be told about closing a file +descriptor (either by calling C explicitly or by any other means, +such as C). The reason is that you register interest in some file +descriptor, but when it goes away, the operating system will silently drop +this interest. If another file descriptor with the same number then is +registered with libev, there is no efficient way to see that this is, in +fact, a different file descriptor. + +To avoid having to explicitly tell libev about such cases, libev follows +the following policy: Each time C is being called, libev +will assume that this is potentially a new file descriptor, otherwise +it is assumed that the file descriptor stays the same. That means that +you I to call C (or C) when you change the +descriptor even if the file descriptor number itself did not change. + +This is how one would do it normally anyway, the important point is that +the libev application should not optimise around libev but should leave +optimisations to libev. + + +=head3 Watcher-Specific Functions + =over 4 =item ev_io_init (ev_io *, callback, int fd, int events) @@ -972,6 +1001,8 @@ The callback is guarenteed to be invoked only when its timeout has passed, but if multiple timers become ready during the same loop iteration then order of execution is undefined. +=head3 Watcher-Specific Functions and Data Members + =over 4 =item ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat) @@ -1076,16 +1107,18 @@ to trigger "at" some specific point in time. For example, if you tell a periodic watcher to trigger in 10 seconds (by specifiying e.g. C) and then reset your system clock to the last year, then it will take a year to trigger the event (unlike an C, which would trigger -roughly 10 seconds later and of course not if you reset your system time -again). +roughly 10 seconds later). They can also be used to implement vastly more complex timers, such as -triggering an event on eahc midnight, local time. +triggering an event on each midnight, local time or other, complicated, +rules. As with timers, the callback is guarenteed to be invoked only when the time (C) has been passed, but if multiple periodic timers become ready during the same loop iteration then order of execution is undefined. +=head3 Watcher-Specific Functions and Data Members + =over 4 =item ev_periodic_init (ev_periodic *, callback, ev_tstamp at, ev_tstamp interval, reschedule_cb) @@ -1097,18 +1130,18 @@ operation, and we will explain them from simplest to complex: =over 4 -=item * absolute timer (interval = reschedule_cb = 0) +=item * absolute timer (at = time, interval = reschedule_cb = 0) In this configuration the watcher triggers an event at the wallclock time C and doesn't repeat. It will not adjust when a time jump occurs, that is, if it is to be run at January 1st 2011 then it will run when the system time reaches or surpasses this time. -=item * non-repeating interval timer (interval > 0, reschedule_cb = 0) +=item * non-repeating interval timer (at = offset, interval > 0, reschedule_cb = 0) In this mode the watcher will always be scheduled to time out at the next -C time (for some integer N) and then repeat, regardless -of any time jumps. +C time (for some integer N, which can also be negative) +and then repeat, regardless of any time jumps. This can be used to create timers that do not drift with respect to system time: @@ -1124,7 +1157,11 @@ Another way to think about it (for the mathematically inclined) is that C will try to run the callback in this mode at the next possible time where C