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.162 by root, Mon May 26 03:54:40 2008 UTC

… …
64 64
65=head1 DESCRIPTION 65=head1 DESCRIPTION
66 66
67The newest version of this document is also available as an html-formatted 67The newest version of this document is also available as an html-formatted
68web page you might find easier to navigate when reading it for the first 68web page you might find easier to navigate when reading it for the first
69time: L<http://cvs.schmorp.de/libev/ev.html>. 69time: L<http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod>.
70 70
71Libev is an event loop: you register interest in certain events (such as a 71Libev is an event loop: you register interest in certain events (such as a
72file descriptor being readable or a timeout occurring), and it will manage 72file descriptor being readable or a timeout occurring), and it will manage
73these event sources and provide your program with events. 73these event sources and provide your program with events.
74 74
… …
113Libev represents time as a single floating point number, representing the 113Libev represents time as a single floating point number, representing the
114(fractional) number of seconds since the (POSIX) epoch (somewhere near 114(fractional) number of seconds since the (POSIX) epoch (somewhere near
115the beginning of 1970, details are complicated, don't ask). This type is 115the beginning of 1970, details are complicated, don't ask). This type is
116called C<ev_tstamp>, which is what you should use too. It usually aliases 116called C<ev_tstamp>, which is what you should use too. It usually aliases
117to the C<double> type in C, and when you need to do any calculations on 117to the C<double> type in C, and when you need to do any calculations on
118it, you should treat it as some floatingpoint value. Unlike the name 118it, you should treat it as some floating point value. Unlike the name
119component C<stamp> might indicate, it is also used for time differences 119component C<stamp> might indicate, it is also used for time differences
120throughout libev. 120throughout libev.
121
122=head1 ERROR HANDLING
123
124Libev knows three classes of errors: operating system errors, usage errors
125and internal errors (bugs).
126
127When libev catches an operating system error it cannot handle (for example
128a system call indicating a condition libev cannot fix), it calls the callback
129set via C<ev_set_syserr_cb>, which is supposed to fix the problem or
130abort. The default is to print a diagnostic message and to call C<abort
131()>.
132
133When libev detects a usage error such as a negative timer interval, then
134it will print a diagnostic message and abort (via the C<assert> mechanism,
135so C<NDEBUG> will disable this checking): these are programming errors in
136the libev caller and need to be fixed there.
137
138Libev also has a few internal error-checking C<assert>ions, and also has
139extensive consistency checking code. These do not trigger under normal
140circumstances, as they indicate either a bug in libev or worse.
141
121 142
122=head1 GLOBAL FUNCTIONS 143=head1 GLOBAL FUNCTIONS
123 144
124These functions can be called anytime, even before initialising the 145These functions can be called anytime, even before initialising the
125library in any way. 146library in any way.
… …
134 155
135=item ev_sleep (ev_tstamp interval) 156=item ev_sleep (ev_tstamp interval)
136 157
137Sleep for the given interval: The current thread will be blocked until 158Sleep for the given interval: The current thread will be blocked until
138either it is interrupted or the given time interval has passed. Basically 159either it is interrupted or the given time interval has passed. Basically
139this is a subsecond-resolution C<sleep ()>. 160this is a sub-second-resolution C<sleep ()>.
140 161
141=item int ev_version_major () 162=item int ev_version_major ()
142 163
143=item int ev_version_minor () 164=item int ev_version_minor ()
144 165
… …
179=item unsigned int ev_recommended_backends () 200=item unsigned int ev_recommended_backends ()
180 201
181Return the set of all backends compiled into this binary of libev and also 202Return the set of all backends compiled into this binary of libev and also
182recommended for this platform. This set is often smaller than the one 203recommended for this platform. This set is often smaller than the one
183returned by C<ev_supported_backends>, as for example kqueue is broken on 204returned by C<ev_supported_backends>, as for example kqueue is broken on
184most BSDs and will not be autodetected unless you explicitly request it 205most BSDs and will not be auto-detected unless you explicitly request it
185(assuming you know what you are doing). This is the set of backends that 206(assuming you know what you are doing). This is the set of backends that
186libev will probe for if you specify no backends explicitly. 207libev will probe for if you specify no backends explicitly.
187 208
188=item unsigned int ev_embeddable_backends () 209=item unsigned int ev_embeddable_backends ()
189 210
… …
231 ... 252 ...
232 ev_set_allocator (persistent_realloc); 253 ev_set_allocator (persistent_realloc);
233 254
234=item ev_set_syserr_cb (void (*cb)(const char *msg)); 255=item ev_set_syserr_cb (void (*cb)(const char *msg));
235 256
236Set the callback function to call on a retryable syscall error (such 257Set the callback function to call on a retryable system call error (such
237as failed select, poll, epoll_wait). The message is a printable string 258as failed select, poll, epoll_wait). The message is a printable string
238indicating the system call or subsystem causing the problem. If this 259indicating the system call or subsystem causing the problem. If this
239callback is set, then libev will expect it to remedy the sitution, no 260callback is set, then libev will expect it to remedy the situation, no
240matter what, when it returns. That is, libev will generally retry the 261matter what, when it returns. That is, libev will generally retry the
241requested operation, or, if the condition doesn't go away, do bad stuff 262requested operation, or, if the condition doesn't go away, do bad stuff
242(such as abort). 263(such as abort).
243 264
244Example: This is basically the same thing that libev does internally, too. 265Example: This is basically the same thing that libev does internally, too.
… …
277from multiple threads, you have to lock (note also that this is unlikely, 298from multiple threads, you have to lock (note also that this is unlikely,
278as loops cannot bes hared easily between threads anyway). 299as loops cannot bes hared easily between threads anyway).
279 300
280The default loop is the only loop that can handle C<ev_signal> and 301The default loop is the only loop that can handle C<ev_signal> and
281C<ev_child> watchers, and to do this, it always registers a handler 302C<ev_child> watchers, and to do this, it always registers a handler
282for C<SIGCHLD>. If this is a problem for your app you can either 303for C<SIGCHLD>. If this is a problem for your application you can either
283create a dynamic loop with C<ev_loop_new> that doesn't do that, or you 304create a dynamic loop with C<ev_loop_new> that doesn't do that, or you
284can simply overwrite the C<SIGCHLD> signal handler I<after> calling 305can simply overwrite the C<SIGCHLD> signal handler I<after> calling
285C<ev_default_init>. 306C<ev_default_init>.
286 307
287The flags argument can be used to specify special behaviour or specific 308The flags argument can be used to specify special behaviour or specific
… …
296The default flags value. Use this if you have no clue (it's the right 317The default flags value. Use this if you have no clue (it's the right
297thing, believe me). 318thing, believe me).
298 319
299=item C<EVFLAG_NOENV> 320=item C<EVFLAG_NOENV>
300 321
301If this flag bit is ored into the flag value (or the program runs setuid 322If this flag bit is or'ed into the flag value (or the program runs setuid
302or setgid) then libev will I<not> look at the environment variable 323or setgid) then libev will I<not> look at the environment variable
303C<LIBEV_FLAGS>. Otherwise (the default), this environment variable will 324C<LIBEV_FLAGS>. Otherwise (the default), this environment variable will
304override the flags completely if it is found in the environment. This is 325override the flags completely if it is found in the environment. This is
305useful to try out specific backends to test their performance, or to work 326useful to try out specific backends to test their performance, or to work
306around bugs. 327around bugs.
… …
313 334
314This works by calling C<getpid ()> on every iteration of the loop, 335This works by calling C<getpid ()> on every iteration of the loop,
315and thus this might slow down your event loop if you do a lot of loop 336and thus this might slow down your event loop if you do a lot of loop
316iterations and little real work, but is usually not noticeable (on my 337iterations and little real work, but is usually not noticeable (on my
317GNU/Linux system for example, C<getpid> is actually a simple 5-insn sequence 338GNU/Linux system for example, C<getpid> is actually a simple 5-insn sequence
318without a syscall and thus I<very> fast, but my GNU/Linux system also has 339without a system call and thus I<very> fast, but my GNU/Linux system also has
319C<pthread_atfork> which is even faster). 340C<pthread_atfork> which is even faster).
320 341
321The big advantage of this flag is that you can forget about fork (and 342The big advantage of this flag is that you can forget about fork (and
322forget about forgetting to tell libev about forking) when you use this 343forget about forgetting to tell libev about forking) when you use this
323flag. 344flag.
324 345
325This flag setting cannot be overriden or specified in the C<LIBEV_FLAGS> 346This flag setting cannot be overridden or specified in the C<LIBEV_FLAGS>
326environment variable. 347environment variable.
327 348
328=item C<EVBACKEND_SELECT> (value 1, portable select backend) 349=item C<EVBACKEND_SELECT> (value 1, portable select backend)
329 350
330This is your standard select(2) backend. Not I<completely> standard, as 351This is your standard select(2) backend. Not I<completely> standard, as
… …
332but if that fails, expect a fairly low limit on the number of fds when 353but if that fails, expect a fairly low limit on the number of fds when
333using this backend. It doesn't scale too well (O(highest_fd)), but its 354using this backend. It doesn't scale too well (O(highest_fd)), but its
334usually the fastest backend for a low number of (low-numbered :) fds. 355usually the fastest backend for a low number of (low-numbered :) fds.
335 356
336To get good performance out of this backend you need a high amount of 357To get good performance out of this backend you need a high amount of
337parallelity (most of the file descriptors should be busy). If you are 358parallelism (most of the file descriptors should be busy). If you are
338writing a server, you should C<accept ()> in a loop to accept as many 359writing a server, you should C<accept ()> in a loop to accept as many
339connections as possible during one iteration. You might also want to have 360connections as possible during one iteration. You might also want to have
340a look at C<ev_set_io_collect_interval ()> to increase the amount of 361a look at C<ev_set_io_collect_interval ()> to increase the amount of
341readyness notifications you get per iteration. 362readiness notifications you get per iteration.
342 363
343=item C<EVBACKEND_POLL> (value 2, poll backend, available everywhere except on windows) 364=item C<EVBACKEND_POLL> (value 2, poll backend, available everywhere except on windows)
344 365
345And this is your standard poll(2) backend. It's more complicated 366And this is your standard poll(2) backend. It's more complicated
346than select, but handles sparse fds better and has no artificial 367than select, but handles sparse fds better and has no artificial
… …
354For few fds, this backend is a bit little slower than poll and select, 375For few fds, this backend is a bit little slower than poll and select,
355but it scales phenomenally better. While poll and select usually scale 376but it scales phenomenally better. While poll and select usually scale
356like O(total_fds) where n is the total number of fds (or the highest fd), 377like O(total_fds) where n is the total number of fds (or the highest fd),
357epoll scales either O(1) or O(active_fds). The epoll design has a number 378epoll scales either O(1) or O(active_fds). The epoll design has a number
358of shortcomings, such as silently dropping events in some hard-to-detect 379of shortcomings, such as silently dropping events in some hard-to-detect
359cases and requiring a syscall per fd change, no fork support and bad 380cases and requiring a system call per fd change, no fork support and bad
360support for dup. 381support for dup.
361 382
362While stopping, setting and starting an I/O watcher in the same iteration 383While stopping, setting and starting an I/O watcher in the same iteration
363will result in some caching, there is still a syscall per such incident 384will result in some caching, there is still a system call per such incident
364(because the fd could point to a different file description now), so its 385(because the fd could point to a different file description now), so its
365best to avoid that. Also, C<dup ()>'ed file descriptors might not work 386best to avoid that. Also, C<dup ()>'ed file descriptors might not work
366very well if you register events for both fds. 387very well if you register events for both fds.
367 388
368Please note that epoll sometimes generates spurious notifications, so you 389Please note that epoll sometimes generates spurious notifications, so you
… …
371 392
372Best performance from this backend is achieved by not unregistering all 393Best performance from this backend is achieved by not unregistering all
373watchers for a file descriptor until it has been closed, if possible, i.e. 394watchers for a file descriptor until it has been closed, if possible, i.e.
374keep at least one watcher active per fd at all times. 395keep at least one watcher active per fd at all times.
375 396
376While nominally embeddeble in other event loops, this feature is broken in 397While nominally embeddable in other event loops, this feature is broken in
377all kernel versions tested so far. 398all kernel versions tested so far.
378 399
379=item C<EVBACKEND_KQUEUE> (value 8, most BSD clones) 400=item C<EVBACKEND_KQUEUE> (value 8, most BSD clones)
380 401
381Kqueue deserves special mention, as at the time of this writing, it 402Kqueue deserves special mention, as at the time of this writing, it
382was broken on all BSDs except NetBSD (usually it doesn't work reliably 403was broken on all BSDs except NetBSD (usually it doesn't work reliably
383with anything but sockets and pipes, except on Darwin, where of course 404with anything but sockets and pipes, except on Darwin, where of course
384it's completely useless). For this reason it's not being "autodetected" 405it's completely useless). For this reason it's not being "auto-detected"
385unless you explicitly specify it explicitly in the flags (i.e. using 406unless you explicitly specify it explicitly in the flags (i.e. using
386C<EVBACKEND_KQUEUE>) or libev was compiled on a known-to-be-good (-enough) 407C<EVBACKEND_KQUEUE>) or libev was compiled on a known-to-be-good (-enough)
387system like NetBSD. 408system like NetBSD.
388 409
389You still can embed kqueue into a normal poll or select backend and use it 410You still can embed kqueue into a normal poll or select backend and use it
… …
391the target platform). See C<ev_embed> watchers for more info. 412the target platform). See C<ev_embed> watchers for more info.
392 413
393It scales in the same way as the epoll backend, but the interface to the 414It scales in the same way as the epoll backend, but the interface to the
394kernel is more efficient (which says nothing about its actual speed, of 415kernel is more efficient (which says nothing about its actual speed, of
395course). While stopping, setting and starting an I/O watcher does never 416course). While stopping, setting and starting an I/O watcher does never
396cause an extra syscall as with C<EVBACKEND_EPOLL>, it still adds up to 417cause an extra system call as with C<EVBACKEND_EPOLL>, it still adds up to
397two event changes per incident, support for C<fork ()> is very bad and it 418two event changes per incident, support for C<fork ()> is very bad and it
398drops fds silently in similarly hard-to-detect cases. 419drops fds silently in similarly hard-to-detect cases.
399 420
400This backend usually performs well under most conditions. 421This backend usually performs well under most conditions.
401 422
… …
416=item C<EVBACKEND_PORT> (value 32, Solaris 10) 437=item C<EVBACKEND_PORT> (value 32, Solaris 10)
417 438
418This uses the Solaris 10 event port mechanism. As with everything on Solaris, 439This uses the Solaris 10 event port mechanism. As with everything on Solaris,
419it's really slow, but it still scales very well (O(active_fds)). 440it's really slow, but it still scales very well (O(active_fds)).
420 441
421Please note that solaris event ports can deliver a lot of spurious 442Please note that Solaris event ports can deliver a lot of spurious
422notifications, so you need to use non-blocking I/O or other means to avoid 443notifications, so you need to use non-blocking I/O or other means to avoid
423blocking when no data (or space) is available. 444blocking when no data (or space) is available.
424 445
425While this backend scales well, it requires one system call per active 446While this backend scales well, it requires one system call per active
426file descriptor per loop iteration. For small and medium numbers of file 447file descriptor per loop iteration. For small and medium numbers of file
427descriptors a "slow" C<EVBACKEND_SELECT> or C<EVBACKEND_POLL> backend 448descriptors a "slow" C<EVBACKEND_SELECT> or C<EVBACKEND_POLL> backend
428might perform better. 449might perform better.
429 450
430On the positive side, ignoring the spurious readyness notifications, this 451On the positive side, ignoring the spurious readiness notifications, this
431backend actually performed to specification in all tests and is fully 452backend actually performed to specification in all tests and is fully
432embeddable, which is a rare feat among the OS-specific backends. 453embeddable, which is a rare feat among the OS-specific backends.
433 454
434=item C<EVBACKEND_ALL> 455=item C<EVBACKEND_ALL>
435 456
… …
439 460
440It is definitely not recommended to use this flag. 461It is definitely not recommended to use this flag.
441 462
442=back 463=back
443 464
444If one or more of these are ored into the flags value, then only these 465If one or more of these are or'ed into the flags value, then only these
445backends will be tried (in the reverse order as listed here). If none are 466backends will be tried (in the reverse order as listed here). If none are
446specified, all backends in C<ev_recommended_backends ()> will be tried. 467specified, all backends in C<ev_recommended_backends ()> will be tried.
447 468
448The most typical usage is like this: 469The most typical usage is like this:
449 470
… …
481=item ev_default_destroy () 502=item ev_default_destroy ()
482 503
483Destroys the default loop again (frees all memory and kernel state 504Destroys the default loop again (frees all memory and kernel state
484etc.). None of the active event watchers will be stopped in the normal 505etc.). None of the active event watchers will be stopped in the normal
485sense, so e.g. C<ev_is_active> might still return true. It is your 506sense, so e.g. C<ev_is_active> might still return true. It is your
486responsibility to either stop all watchers cleanly yoursef I<before> 507responsibility to either stop all watchers cleanly yourself I<before>
487calling this function, or cope with the fact afterwards (which is usually 508calling this function, or cope with the fact afterwards (which is usually
488the easiest thing, you can just ignore the watchers and/or C<free ()> them 509the easiest thing, you can just ignore the watchers and/or C<free ()> them
489for example). 510for example).
490 511
491Note that certain global state, such as signal state, will not be freed by 512Note that certain global state, such as signal state, will not be freed by
… …
572A flags value of C<EVLOOP_NONBLOCK> will look for new events, will handle 593A flags value of C<EVLOOP_NONBLOCK> will look for new events, will handle
573those events and any outstanding ones, but will not block your process in 594those events and any outstanding ones, but will not block your process in
574case there are no events and will return after one iteration of the loop. 595case there are no events and will return after one iteration of the loop.
575 596
576A flags value of C<EVLOOP_ONESHOT> will look for new events (waiting if 597A flags value of C<EVLOOP_ONESHOT> will look for new events (waiting if
577neccessary) and will handle those and any outstanding ones. It will block 598necessary) and will handle those and any outstanding ones. It will block
578your process until at least one new event arrives, and will return after 599your process until at least one new event arrives, and will return after
579one iteration of the loop. This is useful if you are waiting for some 600one iteration of the loop. This is useful if you are waiting for some
580external event in conjunction with something not expressible using other 601external event in conjunction with something not expressible using other
581libev watchers. However, a pair of C<ev_prepare>/C<ev_check> watchers is 602libev watchers. However, a pair of C<ev_prepare>/C<ev_check> watchers is
582usually a better approach for this kind of thing. 603usually a better approach for this kind of thing.
… …
683to spend more time collecting timeouts, at the expense of increased 704to spend more time collecting timeouts, at the expense of increased
684latency (the watcher callback will be called later). C<ev_io> watchers 705latency (the watcher callback will be called later). C<ev_io> watchers
685will not be affected. Setting this to a non-null value will not introduce 706will not be affected. Setting this to a non-null value will not introduce
686any overhead in libev. 707any overhead in libev.
687 708
688Many (busy) programs can usually benefit by setting the io collect 709Many (busy) programs can usually benefit by setting the I/O collect
689interval to a value near C<0.1> or so, which is often enough for 710interval to a value near C<0.1> or so, which is often enough for
690interactive servers (of course not for games), likewise for timeouts. It 711interactive servers (of course not for games), likewise for timeouts. It
691usually doesn't make much sense to set it to a lower value than C<0.01>, 712usually doesn't make much sense to set it to a lower value than C<0.01>,
692as this approsaches the timing granularity of most systems. 713as this approaches the timing granularity of most systems.
714
715=item ev_loop_verify (loop)
716
717This function only does something when C<EV_VERIFY> support has been
718compiled in. It tries to go through all internal structures and checks
719them for validity. If anything is found to be inconsistent, it will print
720an error message to standard error and call C<abort ()>.
721
722This can be used to catch bugs inside libev itself: under normal
723circumstances, this function will never abort as of course libev keeps its
724data structures consistent.
693 725
694=back 726=back
695 727
696 728
697=head1 ANATOMY OF A WATCHER 729=head1 ANATOMY OF A WATCHER
… …
717watcher structures (and it is usually a bad idea to do this on the stack, 749watcher structures (and it is usually a bad idea to do this on the stack,
718although this can sometimes be quite valid). 750although this can sometimes be quite valid).
719 751
720Each watcher structure must be initialised by a call to C<ev_init 752Each watcher structure must be initialised by a call to C<ev_init
721(watcher *, callback)>, which expects a callback to be provided. This 753(watcher *, callback)>, which expects a callback to be provided. This
722callback gets invoked each time the event occurs (or, in the case of io 754callback gets invoked each time the event occurs (or, in the case of I/O
723watchers, each time the event loop detects that the file descriptor given 755watchers, each time the event loop detects that the file descriptor given
724is readable and/or writable). 756is readable and/or writable).
725 757
726Each watcher type has its own C<< ev_<type>_set (watcher *, ...) >> macro 758Each watcher type has its own C<< ev_<type>_set (watcher *, ...) >> macro
727with arguments specific to this watcher type. There is also a macro 759with arguments specific to this watcher type. There is also a macro
… …
803 835
804The given async watcher has been asynchronously notified (see C<ev_async>). 836The given async watcher has been asynchronously notified (see C<ev_async>).
805 837
806=item C<EV_ERROR> 838=item C<EV_ERROR>
807 839
808An unspecified error has occured, the watcher has been stopped. This might 840An unspecified error has occurred, the watcher has been stopped. This might
809happen because the watcher could not be properly started because libev 841happen because the watcher could not be properly started because libev
810ran out of memory, a file descriptor was found to be closed or any other 842ran out of memory, a file descriptor was found to be closed or any other
811problem. You best act on it by reporting the problem and somehow coping 843problem. You best act on it by reporting the problem and somehow coping
812with the watcher being stopped. 844with the watcher being stopped.
813 845
814Libev will usually signal a few "dummy" events together with an error, 846Libev will usually signal a few "dummy" events together with an error,
815for example it might indicate that a fd is readable or writable, and if 847for example it might indicate that a fd is readable or writable, and if
816your callbacks is well-written it can just attempt the operation and cope 848your callbacks is well-written it can just attempt the operation and cope
817with the error from read() or write(). This will not work in multithreaded 849with the error from read() or write(). This will not work in multi-threaded
818programs, though, so beware. 850programs, though, so beware.
819 851
820=back 852=back
821 853
822=head2 GENERIC WATCHER FUNCTIONS 854=head2 GENERIC WATCHER FUNCTIONS
… …
852Although some watcher types do not have type-specific arguments 884Although some watcher types do not have type-specific arguments
853(e.g. C<ev_prepare>) you still need to call its C<set> macro. 885(e.g. C<ev_prepare>) you still need to call its C<set> macro.
854 886
855=item C<ev_TYPE_init> (ev_TYPE *watcher, callback, [args]) 887=item C<ev_TYPE_init> (ev_TYPE *watcher, callback, [args])
856 888
857This convinience macro rolls both C<ev_init> and C<ev_TYPE_set> macro 889This convenience macro rolls both C<ev_init> and C<ev_TYPE_set> macro
858calls into a single call. This is the most convinient method to initialise 890calls into a single call. This is the most convenient method to initialise
859a watcher. The same limitations apply, of course. 891a watcher. The same limitations apply, of course.
860 892
861=item C<ev_TYPE_start> (loop *, ev_TYPE *watcher) 893=item C<ev_TYPE_start> (loop *, ev_TYPE *watcher)
862 894
863Starts (activates) the given watcher. Only active watchers will receive 895Starts (activates) the given watcher. Only active watchers will receive
… …
1032If you must do this, then force the use of a known-to-be-good backend 1064If you must do this, then force the use of a known-to-be-good backend
1033(at the time of this writing, this includes only C<EVBACKEND_SELECT> and 1065(at the time of this writing, this includes only C<EVBACKEND_SELECT> and
1034C<EVBACKEND_POLL>). 1066C<EVBACKEND_POLL>).
1035 1067
1036Another thing you have to watch out for is that it is quite easy to 1068Another thing you have to watch out for is that it is quite easy to
1037receive "spurious" readyness notifications, that is your callback might 1069receive "spurious" readiness notifications, that is your callback might
1038be called with C<EV_READ> but a subsequent C<read>(2) will actually block 1070be called with C<EV_READ> but a subsequent C<read>(2) will actually block
1039because there is no data. Not only are some backends known to create a 1071because there is no data. Not only are some backends known to create a
1040lot of those (for example solaris ports), it is very easy to get into 1072lot of those (for example Solaris ports), it is very easy to get into
1041this situation even with a relatively standard program structure. Thus 1073this situation even with a relatively standard program structure. Thus
1042it is best to always use non-blocking I/O: An extra C<read>(2) returning 1074it is best to always use non-blocking I/O: An extra C<read>(2) returning
1043C<EAGAIN> is far preferable to a program hanging until some data arrives. 1075C<EAGAIN> is far preferable to a program hanging until some data arrives.
1044 1076
1045If you cannot run the fd in non-blocking mode (for example you should not 1077If you cannot run the fd in non-blocking mode (for example you should not
1046play around with an Xlib connection), then you have to seperately re-test 1078play around with an Xlib connection), then you have to separately re-test
1047whether a file descriptor is really ready with a known-to-be good interface 1079whether a file descriptor is really ready with a known-to-be good interface
1048such as poll (fortunately in our Xlib example, Xlib already does this on 1080such as poll (fortunately in our Xlib example, Xlib already does this on
1049its own, so its quite safe to use). 1081its own, so its quite safe to use).
1050 1082
1051=head3 The special problem of disappearing file descriptors 1083=head3 The special problem of disappearing file descriptors
… …
1111=item ev_io_init (ev_io *, callback, int fd, int events) 1143=item ev_io_init (ev_io *, callback, int fd, int events)
1112 1144
1113=item ev_io_set (ev_io *, int fd, int events) 1145=item ev_io_set (ev_io *, int fd, int events)
1114 1146
1115Configures an C<ev_io> watcher. The C<fd> is the file descriptor to 1147Configures an C<ev_io> watcher. The C<fd> is the file descriptor to
1116rceeive events for and events is either C<EV_READ>, C<EV_WRITE> or 1148receive events for and events is either C<EV_READ>, C<EV_WRITE> or
1117C<EV_READ | EV_WRITE> to receive the given events. 1149C<EV_READ | EV_WRITE> to receive the given events.
1118 1150
1119=item int fd [read-only] 1151=item int fd [read-only]
1120 1152
1121The file descriptor being watched. 1153The file descriptor being watched.
… …
1151 1183
1152Timer watchers are simple relative timers that generate an event after a 1184Timer watchers are simple relative timers that generate an event after a
1153given time, and optionally repeating in regular intervals after that. 1185given time, and optionally repeating in regular intervals after that.
1154 1186
1155The timers are based on real time, that is, if you register an event that 1187The timers are based on real time, that is, if you register an event that
1156times out after an hour and you reset your system clock to last years 1188times out after an hour and you reset your system clock to January last
1157time, it will still time out after (roughly) and hour. "Roughly" because 1189year, it will still time out after (roughly) and hour. "Roughly" because
1158detecting time jumps is hard, and some inaccuracies are unavoidable (the 1190detecting time jumps is hard, and some inaccuracies are unavoidable (the
1159monotonic clock option helps a lot here). 1191monotonic clock option helps a lot here).
1160 1192
1161The relative timeouts are calculated relative to the C<ev_now ()> 1193The relative timeouts are calculated relative to the C<ev_now ()>
1162time. This is usually the right thing as this timestamp refers to the time 1194time. This is usually the right thing as this timestamp refers to the time
… …
1164you suspect event processing to be delayed and you I<need> to base the timeout 1196you suspect event processing to be delayed and you I<need> to base the timeout
1165on the current time, use something like this to adjust for this: 1197on the current time, use something like this to adjust for this:
1166 1198
1167 ev_timer_set (&timer, after + ev_now () - ev_time (), 0.); 1199 ev_timer_set (&timer, after + ev_now () - ev_time (), 0.);
1168 1200
1169The callback is guarenteed to be invoked only when its timeout has passed, 1201The callback is guaranteed to be invoked only after its timeout has passed,
1170but if multiple timers become ready during the same loop iteration then 1202but if multiple timers become ready during the same loop iteration then
1171order of execution is undefined. 1203order of execution is undefined.
1172 1204
1173=head3 Watcher-Specific Functions and Data Members 1205=head3 Watcher-Specific Functions and Data Members
1174 1206
… …
1176 1208
1177=item ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat) 1209=item ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat)
1178 1210
1179=item ev_timer_set (ev_timer *, ev_tstamp after, ev_tstamp repeat) 1211=item ev_timer_set (ev_timer *, ev_tstamp after, ev_tstamp repeat)
1180 1212
1181Configure the timer to trigger after C<after> seconds. If C<repeat> is 1213Configure the timer to trigger after C<after> seconds. If C<repeat>
1182C<0.>, then it will automatically be stopped. If it is positive, then the 1214is C<0.>, then it will automatically be stopped once the timeout is
1183timer will automatically be configured to trigger again C<repeat> seconds 1215reached. If it is positive, then the timer will automatically be
1184later, again, and again, until stopped manually. 1216configured to trigger again C<repeat> seconds later, again, and again,
1217until stopped manually.
1185 1218
1186The timer itself will do a best-effort at avoiding drift, that is, if you 1219The timer itself will do a best-effort at avoiding drift, that is, if
1187configure a timer to trigger every 10 seconds, then it will trigger at 1220you configure a timer to trigger every 10 seconds, then it will normally
1188exactly 10 second intervals. If, however, your program cannot keep up with 1221trigger at exactly 10 second intervals. If, however, your program cannot
1189the timer (because it takes longer than those 10 seconds to do stuff) the 1222keep up with the timer (because it takes longer than those 10 seconds to
1190timer will not fire more than once per event loop iteration. 1223do stuff) the timer will not fire more than once per event loop iteration.
1191 1224
1192=item ev_timer_again (loop, ev_timer *) 1225=item ev_timer_again (loop, ev_timer *)
1193 1226
1194This will act as if the timer timed out and restart it again if it is 1227This will act as if the timer timed out and restart it again if it is
1195repeating. The exact semantics are: 1228repeating. The exact semantics are:
1196 1229
1197If the timer is pending, its pending status is cleared. 1230If the timer is pending, its pending status is cleared.
1198 1231
1199If the timer is started but nonrepeating, stop it (as if it timed out). 1232If the timer is started but non-repeating, stop it (as if it timed out).
1200 1233
1201If the timer is repeating, either start it if necessary (with the 1234If the timer is repeating, either start it if necessary (with the
1202C<repeat> value), or reset the running timer to the C<repeat> value. 1235C<repeat> value), or reset the running timer to the C<repeat> value.
1203 1236
1204This sounds a bit complicated, but here is a useful and typical 1237This sounds a bit complicated, but here is a useful and typical
1205example: Imagine you have a tcp connection and you want a so-called idle 1238example: Imagine you have a TCP connection and you want a so-called idle
1206timeout, that is, you want to be called when there have been, say, 60 1239timeout, that is, you want to be called when there have been, say, 60
1207seconds of inactivity on the socket. The easiest way to do this is to 1240seconds of inactivity on the socket. The easiest way to do this is to
1208configure an C<ev_timer> with a C<repeat> value of C<60> and then call 1241configure an C<ev_timer> with a C<repeat> value of C<60> and then call
1209C<ev_timer_again> each time you successfully read or write some data. If 1242C<ev_timer_again> each time you successfully read or write some data. If
1210you go into an idle state where you do not expect data to travel on the 1243you go into an idle state where you do not expect data to travel on the
… …
1271 1304
1272Periodic watchers are also timers of a kind, but they are very versatile 1305Periodic watchers are also timers of a kind, but they are very versatile
1273(and unfortunately a bit complex). 1306(and unfortunately a bit complex).
1274 1307
1275Unlike C<ev_timer>'s, they are not based on real time (or relative time) 1308Unlike C<ev_timer>'s, they are not based on real time (or relative time)
1276but on wallclock time (absolute time). You can tell a periodic watcher 1309but on wall clock time (absolute time). You can tell a periodic watcher
1277to trigger "at" some specific point in time. For example, if you tell a 1310to trigger after some specific point in time. For example, if you tell a
1278periodic watcher to trigger in 10 seconds (by specifiying e.g. C<ev_now () 1311periodic watcher to trigger in 10 seconds (by specifying e.g. C<ev_now ()
1279+ 10.>) and then reset your system clock to the last year, then it will 1312+ 10.>, that is, an absolute time not a delay) and then reset your system
1313clock to January of the previous year, then it will take more than year
1280take a year to trigger the event (unlike an C<ev_timer>, which would trigger 1314to trigger the event (unlike an C<ev_timer>, which would still trigger
1281roughly 10 seconds later). 1315roughly 10 seconds later as it uses a relative timeout).
1282 1316
1283They can also be used to implement vastly more complex timers, such as 1317C<ev_periodic>s can also be used to implement vastly more complex timers,
1284triggering an event on each midnight, local time or other, complicated, 1318such as triggering an event on each "midnight, local time", or other
1285rules. 1319complicated, rules.
1286 1320
1287As with timers, the callback is guarenteed to be invoked only when the 1321As with timers, the callback is guaranteed to be invoked only when the
1288time (C<at>) has been passed, but if multiple periodic timers become ready 1322time (C<at>) has passed, but if multiple periodic timers become ready
1289during the same loop iteration then order of execution is undefined. 1323during the same loop iteration then order of execution is undefined.
1290 1324
1291=head3 Watcher-Specific Functions and Data Members 1325=head3 Watcher-Specific Functions and Data Members
1292 1326
1293=over 4 1327=over 4
… …
1301 1335
1302=over 4 1336=over 4
1303 1337
1304=item * absolute timer (at = time, interval = reschedule_cb = 0) 1338=item * absolute timer (at = time, interval = reschedule_cb = 0)
1305 1339
1306In this configuration the watcher triggers an event at the wallclock time 1340In this configuration the watcher triggers an event after the wall clock
1307C<at> and doesn't repeat. It will not adjust when a time jump occurs, 1341time C<at> has passed and doesn't repeat. It will not adjust when a time
1308that is, if it is to be run at January 1st 2011 then it will run when the 1342jump occurs, that is, if it is to be run at January 1st 2011 then it will
1309system time reaches or surpasses this time. 1343run when the system time reaches or surpasses this time.
1310 1344
1311=item * repeating interval timer (at = offset, interval > 0, reschedule_cb = 0) 1345=item * repeating interval timer (at = offset, interval > 0, reschedule_cb = 0)
1312 1346
1313In this mode the watcher will always be scheduled to time out at the next 1347In this mode the watcher will always be scheduled to time out at the next
1314C<at + N * interval> time (for some integer N, which can also be negative) 1348C<at + N * interval> time (for some integer N, which can also be negative)
1315and then repeat, regardless of any time jumps. 1349and then repeat, regardless of any time jumps.
1316 1350
1317This can be used to create timers that do not drift with respect to system 1351This can be used to create timers that do not drift with respect to system
1318time: 1352time, for example, here is a C<ev_periodic> that triggers each hour, on
1353the hour:
1319 1354
1320 ev_periodic_set (&periodic, 0., 3600., 0); 1355 ev_periodic_set (&periodic, 0., 3600., 0);
1321 1356
1322This doesn't mean there will always be 3600 seconds in between triggers, 1357This doesn't mean there will always be 3600 seconds in between triggers,
1323but only that the the callback will be called when the system time shows a 1358but only that the callback will be called when the system time shows a
1324full hour (UTC), or more correctly, when the system time is evenly divisible 1359full hour (UTC), or more correctly, when the system time is evenly divisible
1325by 3600. 1360by 3600.
1326 1361
1327Another way to think about it (for the mathematically inclined) is that 1362Another way to think about it (for the mathematically inclined) is that
1328C<ev_periodic> will try to run the callback in this mode at the next possible 1363C<ev_periodic> will try to run the callback in this mode at the next possible
1329time where C<time = at (mod interval)>, regardless of any time jumps. 1364time where C<time = at (mod interval)>, regardless of any time jumps.
1330 1365
1331For numerical stability it is preferable that the C<at> value is near 1366For numerical stability it is preferable that the C<at> value is near
1332C<ev_now ()> (the current time), but there is no range requirement for 1367C<ev_now ()> (the current time), but there is no range requirement for
1333this value. 1368this value, and in fact is often specified as zero.
1369
1370Note also that there is an upper limit to how often a timer can fire (CPU
1371speed for example), so if C<interval> is very small then timing stability
1372will of course deteriorate. Libev itself tries to be exact to be about one
1373millisecond (if the OS supports it and the machine is fast enough).
1334 1374
1335=item * manual reschedule mode (at and interval ignored, reschedule_cb = callback) 1375=item * manual reschedule mode (at and interval ignored, reschedule_cb = callback)
1336 1376
1337In this mode the values for C<interval> and C<at> are both being 1377In this mode the values for C<interval> and C<at> are both being
1338ignored. Instead, each time the periodic watcher gets scheduled, the 1378ignored. Instead, each time the periodic watcher gets scheduled, the
1339reschedule callback will be called with the watcher as first, and the 1379reschedule callback will be called with the watcher as first, and the
1340current time as second argument. 1380current time as second argument.
1341 1381
1342NOTE: I<This callback MUST NOT stop or destroy any periodic watcher, 1382NOTE: I<This callback MUST NOT stop or destroy any periodic watcher,
1343ever, or make any event loop modifications>. If you need to stop it, 1383ever, or make ANY event loop modifications whatsoever>.
1344return C<now + 1e30> (or so, fudge fudge) and stop it afterwards (e.g. by
1345starting an C<ev_prepare> watcher, which is legal).
1346 1384
1385If you need to stop it, return C<now + 1e30> (or so, fudge fudge) and stop
1386it afterwards (e.g. by starting an C<ev_prepare> watcher, which is the
1387only event loop modification you are allowed to do).
1388
1347Its prototype is C<ev_tstamp (*reschedule_cb)(struct ev_periodic *w, 1389The callback prototype is C<ev_tstamp (*reschedule_cb)(struct ev_periodic
1348ev_tstamp now)>, e.g.: 1390*w, ev_tstamp now)>, e.g.:
1349 1391
1350 static ev_tstamp my_rescheduler (struct ev_periodic *w, ev_tstamp now) 1392 static ev_tstamp my_rescheduler (struct ev_periodic *w, ev_tstamp now)
1351 { 1393 {
1352 return now + 60.; 1394 return now + 60.;
1353 } 1395 }
… …
1355It must return the next time to trigger, based on the passed time value 1397It must return the next time to trigger, based on the passed time value
1356(that is, the lowest time value larger than to the second argument). It 1398(that is, the lowest time value larger than to the second argument). It
1357will usually be called just before the callback will be triggered, but 1399will usually be called just before the callback will be triggered, but
1358might be called at other times, too. 1400might be called at other times, too.
1359 1401
1360NOTE: I<< This callback must always return a time that is later than the 1402NOTE: I<< This callback must always return a time that is higher than or
1361passed C<now> value >>. Not even C<now> itself will do, it I<must> be larger. 1403equal to the passed C<now> value >>.
1362 1404
1363This can be used to create very complex timers, such as a timer that 1405This can be used to create very complex timers, such as a timer that
1364triggers on each midnight, local time. To do this, you would calculate the 1406triggers on "next midnight, local time". To do this, you would calculate the
1365next midnight after C<now> and return the timestamp value for this. How 1407next midnight after C<now> and return the timestamp value for this. How
1366you do this is, again, up to you (but it is not trivial, which is the main 1408you do this is, again, up to you (but it is not trivial, which is the main
1367reason I omitted it as an example). 1409reason I omitted it as an example).
1368 1410
1369=back 1411=back
… …
1373Simply stops and restarts the periodic watcher again. This is only useful 1415Simply stops and restarts the periodic watcher again. This is only useful
1374when you changed some parameters or the reschedule callback would return 1416when 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 1417a different time than the last time it was called (e.g. in a crond like
1376program when the crontabs have changed). 1418program when the crontabs have changed).
1377 1419
1420=item ev_tstamp ev_periodic_at (ev_periodic *)
1421
1422When active, returns the absolute time that the watcher is supposed to
1423trigger next.
1424
1378=item ev_tstamp offset [read-write] 1425=item ev_tstamp offset [read-write]
1379 1426
1380When repeating, this contains the offset value, otherwise this is the 1427When repeating, this contains the offset value, otherwise this is the
1381absolute point in time (the C<at> value passed to C<ev_periodic_set>). 1428absolute point in time (the C<at> value passed to C<ev_periodic_set>).
1382 1429
… …
1393 1440
1394The current reschedule callback, or C<0>, if this functionality is 1441The current reschedule callback, or C<0>, if this functionality is
1395switched off. Can be changed any time, but changes only take effect when 1442switched off. Can be changed any time, but changes only take effect when
1396the periodic timer fires or C<ev_periodic_again> is being called. 1443the periodic timer fires or C<ev_periodic_again> is being called.
1397 1444
1398=item ev_tstamp at [read-only]
1399
1400When active, contains the absolute time that the watcher is supposed to
1401trigger next.
1402
1403=back 1445=back
1404 1446
1405=head3 Examples 1447=head3 Examples
1406 1448
1407Example: Call a callback every hour, or, more precisely, whenever the 1449Example: Call a callback every hour, or, more precisely, whenever the
1408system clock is divisible by 3600. The callback invocation times have 1450system clock is divisible by 3600. The callback invocation times have
1409potentially a lot of jittering, but good long-term stability. 1451potentially a lot of jitter, but good long-term stability.
1410 1452
1411 static void 1453 static void
1412 clock_cb (struct ev_loop *loop, struct ev_io *w, int revents) 1454 clock_cb (struct ev_loop *loop, struct ev_io *w, int revents)
1413 { 1455 {
1414 ... its now a full hour (UTC, or TAI or whatever your clock follows) 1456 ... its now a full hour (UTC, or TAI or whatever your clock follows)
… …
1451as you don't register any with libev). Similarly, when the last signal 1493as you don't register any with libev). Similarly, when the last signal
1452watcher for a signal is stopped libev will reset the signal handler to 1494watcher for a signal is stopped libev will reset the signal handler to
1453SIG_DFL (regardless of what it was set to before). 1495SIG_DFL (regardless of what it was set to before).
1454 1496
1455If possible and supported, libev will install its handlers with 1497If possible and supported, libev will install its handlers with
1456C<SA_RESTART> behaviour enabled, so syscalls should not be unduly 1498C<SA_RESTART> behaviour enabled, so system calls should not be unduly
1457interrupted. If you have a problem with syscalls getting interrupted by 1499interrupted. If you have a problem with system calls getting interrupted by
1458signals you can block all signals in an C<ev_check> watcher and unblock 1500signals you can block all signals in an C<ev_check> watcher and unblock
1459them in an C<ev_prepare> watcher. 1501them in an C<ev_prepare> watcher.
1460 1502
1461=head3 Watcher-Specific Functions and Data Members 1503=head3 Watcher-Specific Functions and Data Members
1462 1504
… …
1497is permissible to install a child watcher I<after> the child has been 1539is permissible to install a child watcher I<after> the child has been
1498forked (which implies it might have already exited), as long as the event 1540forked (which implies it might have already exited), as long as the event
1499loop isn't entered (or is continued from a watcher). 1541loop isn't entered (or is continued from a watcher).
1500 1542
1501Only the default event loop is capable of handling signals, and therefore 1543Only the default event loop is capable of handling signals, and therefore
1502you can only rgeister child watchers in the default event loop. 1544you can only register child watchers in the default event loop.
1503 1545
1504=head3 Process Interaction 1546=head3 Process Interaction
1505 1547
1506Libev grabs C<SIGCHLD> as soon as the default event loop is 1548Libev grabs C<SIGCHLD> as soon as the default event loop is
1507initialised. This is necessary to guarantee proper behaviour even if 1549initialised. This is necessary to guarantee proper behaviour even if
1508the first child watcher is started after the child exits. The occurance 1550the first child watcher is started after the child exits. The occurrence
1509of C<SIGCHLD> is recorded asynchronously, but child reaping is done 1551of C<SIGCHLD> is recorded asynchronously, but child reaping is done
1510synchronously as part of the event loop processing. Libev always reaps all 1552synchronously as part of the event loop processing. Libev always reaps all
1511children, even ones not watched. 1553children, even ones not watched.
1512 1554
1513=head3 Overriding the Built-In Processing 1555=head3 Overriding the Built-In Processing
… …
1582 } 1624 }
1583 1625
1584 1626
1585=head2 C<ev_stat> - did the file attributes just change? 1627=head2 C<ev_stat> - did the file attributes just change?
1586 1628
1587This watches a filesystem path for attribute changes. That is, it calls 1629This watches a file system path for attribute changes. That is, it calls
1588C<stat> regularly (or when the OS says it changed) and sees if it changed 1630C<stat> regularly (or when the OS says it changed) and sees if it changed
1589compared to the last time, invoking the callback if it did. 1631compared to the last time, invoking the callback if it did.
1590 1632
1591The path does not need to exist: changing from "path exists" to "path does 1633The path does not need to exist: changing from "path exists" to "path does
1592not exist" is a status change like any other. The condition "path does 1634not exist" is a status change like any other. The condition "path does
… …
1610as even with OS-supported change notifications, this can be 1652as even with OS-supported change notifications, this can be
1611resource-intensive. 1653resource-intensive.
1612 1654
1613At the time of this writing, only the Linux inotify interface is 1655At the time of this writing, only the Linux inotify interface is
1614implemented (implementing kqueue support is left as an exercise for the 1656implemented (implementing kqueue support is left as an exercise for the
1657reader, 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 1658semantics with kqueue). Inotify will be used to give hints only and should
1616semantics of C<ev_stat> watchers, which means that libev sometimes needs 1659not 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 1660sometimes needs to fall back to regular polling again even with inotify,
1618usually detected immediately, and if the file exists there will be no 1661but changes are usually detected immediately, and if the file exists there
1619polling. 1662will be no polling.
1620 1663
1621=head3 ABI Issues (Largefile Support) 1664=head3 ABI Issues (Largefile Support)
1622 1665
1623Libev by default (unless the user overrides this) uses the default 1666Libev by default (unless the user overrides this) uses the default
1624compilation environment, which means that on systems with optionally 1667compilation environment, which means that on systems with optionally
1625disabled large file support, you get the 32 bit version of the stat 1668disabled large file support, you get the 32 bit version of the stat
1626structure. When using the library from programs that change the ABI to 1669structure. When using the library from programs that change the ABI to
1627use 64 bit file offsets the programs will fail. In that case you have to 1670use 64 bit file offsets the programs will fail. In that case you have to
1628compile libev with the same flags to get binary compatibility. This is 1671compile libev with the same flags to get binary compatibility. This is
1629obviously the case with any flags that change the ABI, but the problem is 1672obviously the case with any flags that change the ABI, but the problem is
1630most noticably with ev_stat and largefile support. 1673most noticeably with ev_stat and large file support.
1631 1674
1632=head3 Inotify 1675=head3 Inotify
1633 1676
1634When C<inotify (7)> support has been compiled into libev (generally only 1677When 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 1678available on Linux) and present at runtime, it will be used to speed up
… …
1645implement this functionality, due to the requirement of having a file 1688implement this functionality, due to the requirement of having a file
1646descriptor open on the object at all times). 1689descriptor open on the object at all times).
1647 1690
1648=head3 The special problem of stat time resolution 1691=head3 The special problem of stat time resolution
1649 1692
1650The C<stat ()> syscall only supports full-second resolution portably, and 1693The C<stat ()> system call only supports full-second resolution portably, and
1651even on systems where the resolution is higher, many filesystems still 1694even on systems where the resolution is higher, many file systems still
1652only support whole seconds. 1695only support whole seconds.
1653 1696
1654That means that, if the time is the only thing that changes, you might 1697That 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 1698easily miss updates: on the first update, C<ev_stat> detects a change and
1656your callback, which does something. When there is another update within 1699calls your callback, which does something. When there is another update
1657the same second, C<ev_stat> will be unable to detect it. 1700within the same second, C<ev_stat> will be unable to detect it as the stat
1701data does not change.
1658 1702
1659The solution to this is to delay acting on a change for a second (or till 1703The 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> 1704than a 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> 1705a 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 1706ev_timer_again (loop, w)>).
1663systems. 1707
1708The C<.02> offset is added to work around small timing inconsistencies
1709of some operating systems (where the second counter of the current time
1710might be be delayed. One such system is the Linux kernel, where a call to
1711C<gettimeofday> might return a timestamp with a full second later than
1712a subsequent C<time> call - if the equivalent of C<time ()> is used to
1713update file times then there will be a small window where the kernel uses
1714the previous second to update file times but libev might already execute
1715the timer callback).
1664 1716
1665=head3 Watcher-Specific Functions and Data Members 1717=head3 Watcher-Specific Functions and Data Members
1666 1718
1667=over 4 1719=over 4
1668 1720
… …
1674C<path>. The C<interval> is a hint on how quickly a change is expected to 1726C<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 1727be 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 1728a suitable value. The memory pointed to by C<path> must point to the same
1677path for as long as the watcher is active. 1729path for as long as the watcher is active.
1678 1730
1679The callback will be receive C<EV_STAT> when a change was detected, 1731The 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 1732to the attributes at the time the watcher was started (or the last change
1681last change was detected). 1733was detected).
1682 1734
1683=item ev_stat_stat (loop, ev_stat *) 1735=item ev_stat_stat (loop, ev_stat *)
1684 1736
1685Updates the stat buffer immediately with new values. If you change the 1737Updates the stat buffer immediately with new values. If you change the
1686watched path in your callback, you could call this fucntion to avoid 1738watched path in your callback, you could call this function to avoid
1687detecting this change (while introducing a race condition). Can also be 1739detecting this change (while introducing a race condition if you are not
1688useful simply to find out the new values. 1740the only one changing the path). Can also be useful simply to find out the
1741new values.
1689 1742
1690=item ev_statdata attr [read-only] 1743=item ev_statdata attr [read-only]
1691 1744
1692The most-recently detected attributes of the file. Although the type is of 1745The 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 1746C<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 1747suitable for your system, but you can only rely on the POSIX-standardised
1748members to be present. If the C<st_nlink> member is C<0>, then there was
1695was some error while C<stat>ing the file. 1749some error while C<stat>ing the file.
1696 1750
1697=item ev_statdata prev [read-only] 1751=item ev_statdata prev [read-only]
1698 1752
1699The previous attributes of the file. The callback gets invoked whenever 1753The previous attributes of the file. The callback gets invoked whenever
1700C<prev> != C<attr>. 1754C<prev> != C<attr>, or, more precisely, one or more of these members
1755differ: C<st_dev>, C<st_ino>, C<st_mode>, C<st_nlink>, C<st_uid>,
1756C<st_gid>, C<st_rdev>, C<st_size>, C<st_atime>, C<st_mtime>, C<st_ctime>.
1701 1757
1702=item ev_tstamp interval [read-only] 1758=item ev_tstamp interval [read-only]
1703 1759
1704The specified interval. 1760The specified interval.
1705 1761
1706=item const char *path [read-only] 1762=item const char *path [read-only]
1707 1763
1708The filesystem path that is being watched. 1764The file system path that is being watched.
1709 1765
1710=back 1766=back
1711 1767
1712=head3 Examples 1768=head3 Examples
1713 1769
… …
1759 } 1815 }
1760 1816
1761 ... 1817 ...
1762 ev_stat_init (&passwd, stat_cb, "/etc/passwd", 0.); 1818 ev_stat_init (&passwd, stat_cb, "/etc/passwd", 0.);
1763 ev_stat_start (loop, &passwd); 1819 ev_stat_start (loop, &passwd);
1764 ev_timer_init (&timer, timer_cb, 0., 1.01); 1820 ev_timer_init (&timer, timer_cb, 0., 1.02);
1765 1821
1766 1822
1767=head2 C<ev_idle> - when you've got nothing better to do... 1823=head2 C<ev_idle> - when you've got nothing better to do...
1768 1824
1769Idle watchers trigger events when no other events of the same or higher 1825Idle watchers trigger events when no other events of the same or higher
… …
1839 1895
1840This is done by examining in each prepare call which file descriptors need 1896This is done by examining in each prepare call which file descriptors need
1841to be watched by the other library, registering C<ev_io> watchers for 1897to be watched by the other library, registering C<ev_io> watchers for
1842them and starting an C<ev_timer> watcher for any timeouts (many libraries 1898them and starting an C<ev_timer> watcher for any timeouts (many libraries
1843provide just this functionality). Then, in the check watcher you check for 1899provide just this functionality). Then, in the check watcher you check for
1844any events that occured (by checking the pending status of all watchers 1900any events that occurred (by checking the pending status of all watchers
1845and stopping them) and call back into the library. The I/O and timer 1901and stopping them) and call back into the library. The I/O and timer
1846callbacks will never actually be called (but must be valid nevertheless, 1902callbacks will never actually be called (but must be valid nevertheless,
1847because you never know, you know?). 1903because you never know, you know?).
1848 1904
1849As another example, the Perl Coro module uses these hooks to integrate 1905As another example, the Perl Coro module uses these hooks to integrate
… …
1857 1913
1858It is recommended to give C<ev_check> watchers highest (C<EV_MAXPRI>) 1914It is recommended to give C<ev_check> watchers highest (C<EV_MAXPRI>)
1859priority, to ensure that they are being run before any other watchers 1915priority, to ensure that they are being run before any other watchers
1860after the poll. Also, C<ev_check> watchers (and C<ev_prepare> watchers, 1916after the poll. Also, C<ev_check> watchers (and C<ev_prepare> watchers,
1861too) should not activate ("feed") events into libev. While libev fully 1917too) should not activate ("feed") events into libev. While libev fully
1862supports this, they will be called before other C<ev_check> watchers 1918supports 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 1919did 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 1920(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 1921state until their C<ev_check> watcher ran (always remind yourself to
1866coexist peacefully with others). 1922coexist peacefully with others).
1867 1923
… …
1882=head3 Examples 1938=head3 Examples
1883 1939
1884There are a number of principal ways to embed other event loops or modules 1940There 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 1941into 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 1942(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> 1943use 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 1944Glib main context into libev, and finally, C<Glib::EV> embeds EV into the
1889into the Glib event loop). 1945Glib event loop).
1890 1946
1891Method 1: Add IO watchers and a timeout watcher in a prepare handler, 1947Method 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 1948and 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 1949is 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 1950priority for the check watcher or use C<ev_clear_pending> explicitly, as
… …
1951 2007
1952Method 2: This would be just like method 1, but you run C<adns_afterpoll> 2008Method 2: This would be just like method 1, but you run C<adns_afterpoll>
1953in the prepare watcher and would dispose of the check watcher. 2009in the prepare watcher and would dispose of the check watcher.
1954 2010
1955Method 3: If the module to be embedded supports explicit event 2011Method 3: If the module to be embedded supports explicit event
1956notification (adns does), you can also make use of the actual watcher 2012notification (libadns does), you can also make use of the actual watcher
1957callbacks, and only destroy/create the watchers in the prepare watcher. 2013callbacks, and only destroy/create the watchers in the prepare watcher.
1958 2014
1959 static void 2015 static void
1960 timer_cb (EV_P_ ev_timer *w, int revents) 2016 timer_cb (EV_P_ ev_timer *w, int revents)
1961 { 2017 {
… …
1976 } 2032 }
1977 2033
1978 // do not ever call adns_afterpoll 2034 // do not ever call adns_afterpoll
1979 2035
1980Method 4: Do not use a prepare or check watcher because the module you 2036Method 4: Do not use a prepare or check watcher because the module you
1981want to embed is too inflexible to support it. Instead, youc na override 2037want to embed is too inflexible to support it. Instead, you can override
1982their poll function. The drawback with this solution is that the main 2038their poll function. The drawback with this solution is that the main
1983loop is now no longer controllable by EV. The C<Glib::EV> module does 2039loop is now no longer controllable by EV. The C<Glib::EV> module does
1984this. 2040this.
1985 2041
1986 static gint 2042 static gint
… …
2070 2126
2071Configures the watcher to embed the given loop, which must be 2127Configures the watcher to embed the given loop, which must be
2072embeddable. If the callback is C<0>, then C<ev_embed_sweep> will be 2128embeddable. If the callback is C<0>, then C<ev_embed_sweep> will be
2073invoked automatically, otherwise it is the responsibility of the callback 2129invoked automatically, otherwise it is the responsibility of the callback
2074to invoke it (it will continue to be called until the sweep has been done, 2130to invoke it (it will continue to be called until the sweep has been done,
2075if you do not want thta, you need to temporarily stop the embed watcher). 2131if you do not want that, you need to temporarily stop the embed watcher).
2076 2132
2077=item ev_embed_sweep (loop, ev_embed *) 2133=item ev_embed_sweep (loop, ev_embed *)
2078 2134
2079Make a single, non-blocking sweep over the embedded loop. This works 2135Make a single, non-blocking sweep over the embedded loop. This works
2080similarly to C<ev_loop (embedded_loop, EVLOOP_NONBLOCK)>, but in the most 2136similarly to C<ev_loop (embedded_loop, EVLOOP_NONBLOCK)>, but in the most
2081apropriate way for embedded loops. 2137appropriate way for embedded loops.
2082 2138
2083=item struct ev_loop *other [read-only] 2139=item struct ev_loop *other [read-only]
2084 2140
2085The embedded event loop. 2141The embedded event loop.
2086 2142
… …
2088 2144
2089=head3 Examples 2145=head3 Examples
2090 2146
2091Example: Try to get an embeddable event loop and embed it into the default 2147Example: Try to get an embeddable event loop and embed it into the default
2092event loop. If that is not possible, use the default loop. The default 2148event loop. If that is not possible, use the default loop. The default
2093loop is stored in C<loop_hi>, while the mebeddable loop is stored in 2149loop is stored in C<loop_hi>, while the embeddable loop is stored in
2094C<loop_lo> (which is C<loop_hi> in the acse no embeddable loop can be 2150C<loop_lo> (which is C<loop_hi> in the case no embeddable loop can be
2095used). 2151used).
2096 2152
2097 struct ev_loop *loop_hi = ev_default_init (0); 2153 struct ev_loop *loop_hi = ev_default_init (0);
2098 struct ev_loop *loop_lo = 0; 2154 struct ev_loop *loop_lo = 0;
2099 struct ev_embed embed; 2155 struct ev_embed embed;
… …
2193 2249
2194=item queueing from a signal handler context 2250=item queueing from a signal handler context
2195 2251
2196To implement race-free queueing, you simply add to the queue in the signal 2252To implement race-free queueing, you simply add to the queue in the signal
2197handler but you block the signal handler in the watcher callback. Here is an example that does that for 2253handler but you block the signal handler in the watcher callback. Here is an example that does that for
2198some fictitiuous SIGUSR1 handler: 2254some fictitious SIGUSR1 handler:
2199 2255
2200 static ev_async mysig; 2256 static ev_async mysig;
2201 2257
2202 static void 2258 static void
2203 sigusr1_handler (void) 2259 sigusr1_handler (void)
… …
2277=item ev_async_send (loop, ev_async *) 2333=item ev_async_send (loop, ev_async *)
2278 2334
2279Sends/signals/activates the given C<ev_async> watcher, that is, feeds 2335Sends/signals/activates the given C<ev_async> watcher, that is, feeds
2280an C<EV_ASYNC> event on the watcher into the event loop. Unlike 2336an C<EV_ASYNC> event on the watcher into the event loop. Unlike
2281C<ev_feed_event>, this call is safe to do in other threads, signal or 2337C<ev_feed_event>, this call is safe to do in other threads, signal or
2282similar contexts (see the dicusssion of C<EV_ATOMIC_T> in the embedding 2338similar contexts (see the discussion of C<EV_ATOMIC_T> in the embedding
2283section below on what exactly this means). 2339section below on what exactly this means).
2284 2340
2285This call incurs the overhead of a syscall only once per loop iteration, 2341This call incurs the overhead of a system call only once per loop iteration,
2286so while the overhead might be noticable, it doesn't apply to repeated 2342so while the overhead might be noticeable, it doesn't apply to repeated
2287calls to C<ev_async_send>. 2343calls to C<ev_async_send>.
2288 2344
2289=item bool = ev_async_pending (ev_async *) 2345=item bool = ev_async_pending (ev_async *)
2290 2346
2291Returns a non-zero value when C<ev_async_send> has been called on the 2347Returns a non-zero value when C<ev_async_send> has been called on the
… …
2293event loop. 2349event loop.
2294 2350
2295C<ev_async_send> sets a flag in the watcher and wakes up the loop. When 2351C<ev_async_send> sets a flag in the watcher and wakes up the loop. When
2296the loop iterates next and checks for the watcher to have become active, 2352the loop iterates next and checks for the watcher to have become active,
2297it will reset the flag again. C<ev_async_pending> can be used to very 2353it will reset the flag again. C<ev_async_pending> can be used to very
2298quickly check wether invoking the loop might be a good idea. 2354quickly check whether invoking the loop might be a good idea.
2299 2355
2300Not that this does I<not> check wether the watcher itself is pending, only 2356Not that this does I<not> check whether the watcher itself is pending, only
2301wether it has been requested to make this watcher pending. 2357whether it has been requested to make this watcher pending.
2302 2358
2303=back 2359=back
2304 2360
2305 2361
2306=head1 OTHER FUNCTIONS 2362=head1 OTHER FUNCTIONS
… …
2317or timeout without having to allocate/configure/start/stop/free one or 2373or timeout without having to allocate/configure/start/stop/free one or
2318more watchers yourself. 2374more watchers yourself.
2319 2375
2320If C<fd> is less than 0, then no I/O watcher will be started and events 2376If C<fd> is less than 0, then no I/O watcher will be started and events
2321is being ignored. Otherwise, an C<ev_io> watcher for the given C<fd> and 2377is being ignored. Otherwise, an C<ev_io> watcher for the given C<fd> and
2322C<events> set will be craeted and started. 2378C<events> set will be created and started.
2323 2379
2324If C<timeout> is less than 0, then no timeout watcher will be 2380If C<timeout> is less than 0, then no timeout watcher will be
2325started. Otherwise an C<ev_timer> watcher with after = C<timeout> (and 2381started. Otherwise an C<ev_timer> watcher with after = C<timeout> (and
2326repeat = 0) will be started. While C<0> is a valid timeout, it is of 2382repeat = 0) will be started. While C<0> is a valid timeout, it is of
2327dubious value. 2383dubious value.
… …
2352Feed an event on the given fd, as if a file descriptor backend detected 2408Feed an event on the given fd, as if a file descriptor backend detected
2353the given events it. 2409the given events it.
2354 2410
2355=item ev_feed_signal_event (ev_loop *loop, int signum) 2411=item ev_feed_signal_event (ev_loop *loop, int signum)
2356 2412
2357Feed an event as if the given signal occured (C<loop> must be the default 2413Feed an event as if the given signal occurred (C<loop> must be the default
2358loop!). 2414loop!).
2359 2415
2360=back 2416=back
2361 2417
2362 2418
… …
2391=back 2447=back
2392 2448
2393=head1 C++ SUPPORT 2449=head1 C++ SUPPORT
2394 2450
2395Libev comes with some simplistic wrapper classes for C++ that mainly allow 2451Libev comes with some simplistic wrapper classes for C++ that mainly allow
2396you to use some convinience methods to start/stop watchers and also change 2452you to use some convenience methods to start/stop watchers and also change
2397the callback model to a model using method callbacks on objects. 2453the callback model to a model using method callbacks on objects.
2398 2454
2399To use it, 2455To use it,
2400 2456
2401 #include <ev++.h> 2457 #include <ev++.h>
… …
2502=item w->set (struct ev_loop *) 2558=item w->set (struct ev_loop *)
2503 2559
2504Associates a different C<struct ev_loop> with this watcher. You can only 2560Associates a different C<struct ev_loop> with this watcher. You can only
2505do this when the watcher is inactive (and not pending either). 2561do this when the watcher is inactive (and not pending either).
2506 2562
2507=item w->set ([args]) 2563=item w->set ([arguments])
2508 2564
2509Basically the same as C<ev_TYPE_set>, with the same args. Must be 2565Basically the same as C<ev_TYPE_set>, with the same arguments. Must be
2510called at least once. Unlike the C counterpart, an active watcher gets 2566called at least once. Unlike the C counterpart, an active watcher gets
2511automatically stopped and restarted when reconfiguring it with this 2567automatically stopped and restarted when reconfiguring it with this
2512method. 2568method.
2513 2569
2514=item w->start () 2570=item w->start ()
… …
2556 2612
2557 2613
2558=head1 OTHER LANGUAGE BINDINGS 2614=head1 OTHER LANGUAGE BINDINGS
2559 2615
2560Libev does not offer other language bindings itself, but bindings for a 2616Libev does not offer other language bindings itself, but bindings for a
2561numbe rof languages exist in the form of third-party packages. If you know 2617number of languages exist in the form of third-party packages. If you know
2562any interesting language binding in addition to the ones listed here, drop 2618any interesting language binding in addition to the ones listed here, drop
2563me a note. 2619me a note.
2564 2620
2565=over 4 2621=over 4
2566 2622
… …
2576L<http://software.schmorp.de/pkg/EV>. 2632L<http://software.schmorp.de/pkg/EV>.
2577 2633
2578=item Ruby 2634=item Ruby
2579 2635
2580Tony Arcieri has written a ruby extension that offers access to a subset 2636Tony Arcieri has written a ruby extension that offers access to a subset
2581of the libev API and adds filehandle abstractions, asynchronous DNS and 2637of the libev API and adds file handle abstractions, asynchronous DNS and
2582more on top of it. It can be found via gem servers. Its homepage is at 2638more on top of it. It can be found via gem servers. Its homepage is at
2583L<http://rev.rubyforge.org/>. 2639L<http://rev.rubyforge.org/>.
2584 2640
2585=item D 2641=item D
2586 2642
… …
2590=back 2646=back
2591 2647
2592 2648
2593=head1 MACRO MAGIC 2649=head1 MACRO MAGIC
2594 2650
2595Libev can be compiled with a variety of options, the most fundamantal 2651Libev can be compiled with a variety of options, the most fundamental
2596of which is C<EV_MULTIPLICITY>. This option determines whether (most) 2652of which is C<EV_MULTIPLICITY>. This option determines whether (most)
2597functions and callbacks have an initial C<struct ev_loop *> argument. 2653functions and callbacks have an initial C<struct ev_loop *> argument.
2598 2654
2599To make it easier to write programs that cope with either variant, the 2655To make it easier to write programs that cope with either variant, the
2600following macros are defined: 2656following macros are defined:
… …
2674libev somewhere in your source tree). 2730libev somewhere in your source tree).
2675 2731
2676=head2 FILESETS 2732=head2 FILESETS
2677 2733
2678Depending on what features you need you need to include one or more sets of files 2734Depending on what features you need you need to include one or more sets of files
2679in your app. 2735in your application.
2680 2736
2681=head3 CORE EVENT LOOP 2737=head3 CORE EVENT LOOP
2682 2738
2683To include only the libev core (all the C<ev_*> functions), with manual 2739To include only the libev core (all the C<ev_*> functions), with manual
2684configuration (no autoconf): 2740configuration (no autoconf):
… …
2735 event.h 2791 event.h
2736 event.c 2792 event.c
2737 2793
2738=head3 AUTOCONF SUPPORT 2794=head3 AUTOCONF SUPPORT
2739 2795
2740Instead of using C<EV_STANDALONE=1> and providing your config in 2796Instead of using C<EV_STANDALONE=1> and providing your configuration in
2741whatever way you want, you can also C<m4_include([libev.m4])> in your 2797whatever way you want, you can also C<m4_include([libev.m4])> in your
2742F<configure.ac> and leave C<EV_STANDALONE> undefined. F<ev.c> will then 2798F<configure.ac> and leave C<EV_STANDALONE> undefined. F<ev.c> will then
2743include F<config.h> and configure itself accordingly. 2799include F<config.h> and configure itself accordingly.
2744 2800
2745For this of course you need the m4 file: 2801For this of course you need the m4 file:
… …
2747 libev.m4 2803 libev.m4
2748 2804
2749=head2 PREPROCESSOR SYMBOLS/MACROS 2805=head2 PREPROCESSOR SYMBOLS/MACROS
2750 2806
2751Libev can be configured via a variety of preprocessor symbols you have to 2807Libev can be configured via a variety of preprocessor symbols you have to
2752define before including any of its files. The default in the absense of 2808define before including any of its files. The default in the absence of
2753autoconf is noted for every option. 2809autoconf is noted for every option.
2754 2810
2755=over 4 2811=over 4
2756 2812
2757=item EV_STANDALONE 2813=item EV_STANDALONE
… …
2763F<event.h> that are not directly supported by the libev core alone. 2819F<event.h> that are not directly supported by the libev core alone.
2764 2820
2765=item EV_USE_MONOTONIC 2821=item EV_USE_MONOTONIC
2766 2822
2767If defined to be C<1>, libev will try to detect the availability of the 2823If defined to be C<1>, libev will try to detect the availability of the
2768monotonic clock option at both compiletime and runtime. Otherwise no use 2824monotonic clock option at both compile time and runtime. Otherwise no use
2769of the monotonic clock option will be attempted. If you enable this, you 2825of the monotonic clock option will be attempted. If you enable this, you
2770usually have to link against librt or something similar. Enabling it when 2826usually have to link against librt or something similar. Enabling it when
2771the functionality isn't available is safe, though, although you have 2827the functionality isn't available is safe, though, although you have
2772to make sure you link against any libraries where the C<clock_gettime> 2828to make sure you link against any libraries where the C<clock_gettime>
2773function is hiding in (often F<-lrt>). 2829function is hiding in (often F<-lrt>).
2774 2830
2775=item EV_USE_REALTIME 2831=item EV_USE_REALTIME
2776 2832
2777If defined to be C<1>, libev will try to detect the availability of the 2833If defined to be C<1>, libev will try to detect the availability of the
2778realtime clock option at compiletime (and assume its availability at 2834real-time clock option at compile time (and assume its availability at
2779runtime if successful). Otherwise no use of the realtime clock option will 2835runtime if successful). Otherwise no use of the real-time clock option will
2780be attempted. This effectively replaces C<gettimeofday> by C<clock_get 2836be attempted. This effectively replaces C<gettimeofday> by C<clock_get
2781(CLOCK_REALTIME, ...)> and will not normally affect correctness. See the 2837(CLOCK_REALTIME, ...)> and will not normally affect correctness. See the
2782note about libraries in the description of C<EV_USE_MONOTONIC>, though. 2838note about libraries in the description of C<EV_USE_MONOTONIC>, though.
2783 2839
2784=item EV_USE_NANOSLEEP 2840=item EV_USE_NANOSLEEP
… …
27952.7 or newer, otherwise disabled. 28512.7 or newer, otherwise disabled.
2796 2852
2797=item EV_USE_SELECT 2853=item EV_USE_SELECT
2798 2854
2799If undefined or defined to be C<1>, libev will compile in support for the 2855If undefined or defined to be C<1>, libev will compile in support for the
2800C<select>(2) backend. No attempt at autodetection will be done: if no 2856C<select>(2) backend. No attempt at auto-detection will be done: if no
2801other method takes over, select will be it. Otherwise the select backend 2857other method takes over, select will be it. Otherwise the select backend
2802will not be compiled in. 2858will not be compiled in.
2803 2859
2804=item EV_SELECT_USE_FD_SET 2860=item EV_SELECT_USE_FD_SET
2805 2861
2806If defined to C<1>, then the select backend will use the system C<fd_set> 2862If defined to C<1>, then the select backend will use the system C<fd_set>
2807structure. This is useful if libev doesn't compile due to a missing 2863structure. This is useful if libev doesn't compile due to a missing
2808C<NFDBITS> or C<fd_mask> definition or it misguesses the bitset layout on 2864C<NFDBITS> or C<fd_mask> definition or it mis-guesses the bitset layout on
2809exotic systems. This usually limits the range of file descriptors to some 2865exotic systems. This usually limits the range of file descriptors to some
2810low limit such as 1024 or might have other limitations (winsocket only 2866low limit such as 1024 or might have other limitations (winsocket only
2811allows 64 sockets). The C<FD_SETSIZE> macro, set before compilation, might 2867allows 64 sockets). The C<FD_SETSIZE> macro, set before compilation, might
2812influence the size of the C<fd_set> used. 2868influence the size of the C<fd_set> used.
2813 2869
… …
2862otherwise another method will be used as fallback. This is the preferred 2918otherwise another method will be used as fallback. This is the preferred
2863backend for Solaris 10 systems. 2919backend for Solaris 10 systems.
2864 2920
2865=item EV_USE_DEVPOLL 2921=item EV_USE_DEVPOLL
2866 2922
2867reserved for future expansion, works like the USE symbols above. 2923Reserved for future expansion, works like the USE symbols above.
2868 2924
2869=item EV_USE_INOTIFY 2925=item EV_USE_INOTIFY
2870 2926
2871If defined to be C<1>, libev will compile in support for the Linux inotify 2927If defined to be C<1>, libev will compile in support for the Linux inotify
2872interface to speed up C<ev_stat> watchers. Its actual availability will 2928interface to speed up C<ev_stat> watchers. Its actual availability will
… …
2879access is atomic with respect to other threads or signal contexts. No such 2935access is atomic with respect to other threads or signal contexts. No such
2880type is easily found in the C language, so you can provide your own type 2936type is easily found in the C language, so you can provide your own type
2881that you know is safe for your purposes. It is used both for signal handler "locking" 2937that you know is safe for your purposes. It is used both for signal handler "locking"
2882as well as for signal and thread safety in C<ev_async> watchers. 2938as well as for signal and thread safety in C<ev_async> watchers.
2883 2939
2884In the absense of this define, libev will use C<sig_atomic_t volatile> 2940In the absence of this define, libev will use C<sig_atomic_t volatile>
2885(from F<signal.h>), which is usually good enough on most platforms. 2941(from F<signal.h>), which is usually good enough on most platforms.
2886 2942
2887=item EV_H 2943=item EV_H
2888 2944
2889The name of the F<ev.h> header file used to include it. The default if 2945The name of the F<ev.h> header file used to include it. The default if
… …
2928When doing priority-based operations, libev usually has to linearly search 2984When doing priority-based operations, libev usually has to linearly search
2929all the priorities, so having many of them (hundreds) uses a lot of space 2985all the priorities, so having many of them (hundreds) uses a lot of space
2930and time, so using the defaults of five priorities (-2 .. +2) is usually 2986and time, so using the defaults of five priorities (-2 .. +2) is usually
2931fine. 2987fine.
2932 2988
2933If your embedding app does not need any priorities, defining these both to 2989If your embedding application does not need any priorities, defining these both to
2934C<0> will save some memory and cpu. 2990C<0> will save some memory and CPU.
2935 2991
2936=item EV_PERIODIC_ENABLE 2992=item EV_PERIODIC_ENABLE
2937 2993
2938If undefined or defined to be C<1>, then periodic timers are supported. If 2994If undefined or defined to be C<1>, then periodic timers are supported. If
2939defined to be C<0>, then they are not. Disabling them saves a few kB of 2995defined to be C<0>, then they are not. Disabling them saves a few kB of
… …
2966defined to be C<0>, then they are not. 3022defined to be C<0>, then they are not.
2967 3023
2968=item EV_MINIMAL 3024=item EV_MINIMAL
2969 3025
2970If you need to shave off some kilobytes of code at the expense of some 3026If 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 3027speed, define this symbol to C<1>. Currently this is used to override some
2972some inlining decisions, saves roughly 30% codesize of amd64. 3028inlining decisions, saves roughly 30% code size on amd64. It also selects a
3029much smaller 2-heap for timer management over the default 4-heap.
2973 3030
2974=item EV_PID_HASHSIZE 3031=item EV_PID_HASHSIZE
2975 3032
2976C<ev_child> watchers use a small hash table to distribute workload by 3033C<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 3034pid. The default size is C<16> (or C<1> with C<EV_MINIMAL>), usually more
… …
2983C<ev_stat> watchers use a small hash table to distribute workload by 3040C<ev_stat> watchers use a small hash table to distribute workload by
2984inotify watch id. The default size is C<16> (or C<1> with C<EV_MINIMAL>), 3041inotify watch id. The default size is C<16> (or C<1> with C<EV_MINIMAL>),
2985usually more than enough. If you need to manage thousands of C<ev_stat> 3042usually more than enough. If you need to manage thousands of C<ev_stat>
2986watchers you might want to increase this value (I<must> be a power of 3043watchers you might want to increase this value (I<must> be a power of
2987two). 3044two).
3045
3046=item EV_USE_4HEAP
3047
3048Heaps are not very cache-efficient. To improve the cache-efficiency of the
3049timer and periodics heap, libev uses a 4-heap when this symbol is defined
3050to C<1>. The 4-heap uses more complicated (longer) code but has
3051noticeably faster performance with many (thousands) of watchers.
3052
3053The default is C<1> unless C<EV_MINIMAL> is set in which case it is C<0>
3054(disabled).
3055
3056=item EV_HEAP_CACHE_AT
3057
3058Heaps are not very cache-efficient. To improve the cache-efficiency of the
3059timer and periodics heap, libev can cache the timestamp (I<at>) within
3060the heap structure (selected by defining C<EV_HEAP_CACHE_AT> to C<1>),
3061which uses 8-12 bytes more per watcher and a few hundred bytes more code,
3062but avoids random read accesses on heap changes. This improves performance
3063noticeably with with many (hundreds) of watchers.
3064
3065The default is C<1> unless C<EV_MINIMAL> is set in which case it is C<0>
3066(disabled).
3067
3068=item EV_VERIFY
3069
3070Controls how much internal verification (see C<ev_loop_verify ()>) will
3071be done: If set to C<0>, no internal verification code will be compiled
3072in. If set to C<1>, then verification code will be compiled in, but not
3073called. If set to C<2>, then the internal verification code will be
3074called once per loop, which can slow down libev. If set to C<3>, then the
3075verification code will be called very frequently, which will slow down
3076libev considerably.
3077
3078The default is C<1>, unless C<EV_MINIMAL> is set, in which case it will be
3079C<0.>
2988 3080
2989=item EV_COMMON 3081=item EV_COMMON
2990 3082
2991By default, all watchers have a C<void *data> member. By redefining 3083By default, all watchers have a C<void *data> member. By redefining
2992this macro to a something else you can include more and other types of 3084this macro to a something else you can include more and other types of
… …
3012avoid the C<struct ev_loop *> as first argument in all cases, or to use 3104avoid the C<struct ev_loop *> as first argument in all cases, or to use
3013method calls instead of plain function calls in C++. 3105method calls instead of plain function calls in C++.
3014 3106
3015=head2 EXPORTED API SYMBOLS 3107=head2 EXPORTED API SYMBOLS
3016 3108
3017If you need to re-export the API (e.g. via a dll) and you need a list of 3109If you need to re-export the API (e.g. via a DLL) and you need a list of
3018exported symbols, you can use the provided F<Symbol.*> files which list 3110exported symbols, you can use the provided F<Symbol.*> files which list
3019all public symbols, one per line: 3111all public symbols, one per line:
3020 3112
3021 Symbols.ev for libev proper 3113 Symbols.ev for libev proper
3022 Symbols.event for the libevent emulation 3114 Symbols.event for the libevent emulation
3023 3115
3024This can also be used to rename all public symbols to avoid clashes with 3116This can also be used to rename all public symbols to avoid clashes with
3025multiple versions of libev linked together (which is obviously bad in 3117multiple versions of libev linked together (which is obviously bad in
3026itself, but sometimes it is inconvinient to avoid this). 3118itself, but sometimes it is inconvenient to avoid this).
3027 3119
3028A sed command like this will create wrapper C<#define>'s that you need to 3120A sed command like this will create wrapper C<#define>'s that you need to
3029include before including F<ev.h>: 3121include before including F<ev.h>:
3030 3122
3031 <Symbols.ev sed -e "s/.*/#define & myprefix_&/" >wrap.h 3123 <Symbols.ev sed -e "s/.*/#define & myprefix_&/" >wrap.h
… …
3070 3162
3071=head1 THREADS AND COROUTINES 3163=head1 THREADS AND COROUTINES
3072 3164
3073=head2 THREADS 3165=head2 THREADS
3074 3166
3075Libev itself is completely threadsafe, but it uses no locking. This 3167Libev itself is completely thread-safe, but it uses no locking. This
3076means that you can use as many loops as you want in parallel, as long as 3168means that you can use as many loops as you want in parallel, as long as
3077only one thread ever calls into one libev function with the same loop 3169only one thread ever calls into one libev function with the same loop
3078parameter. 3170parameter.
3079 3171
3080Or put differently: calls with different loop parameters can be done in 3172Or put differently: calls with different loop parameters can be done in
… …
3087help you but by giving some generic advice: 3179help you but by giving some generic advice:
3088 3180
3089=over 4 3181=over 4
3090 3182
3091=item * most applications have a main thread: use the default libev loop 3183=item * most applications have a main thread: use the default libev loop
3092in that thread, or create a seperate thread running only the default loop. 3184in that thread, or create a separate thread running only the default loop.
3093 3185
3094This helps integrating other libraries or software modules that use libev 3186This helps integrating other libraries or software modules that use libev
3095themselves and don't care/know about threading. 3187themselves and don't care/know about threading.
3096 3188
3097=item * one loop per thread is usually a good model. 3189=item * one loop per thread is usually a good model.
3098 3190
3099Doing this is almost never wrong, sometimes a better-performance model 3191Doing this is almost never wrong, sometimes a better-performance model
3100exists, but it is always a good start. 3192exists, but it is always a good start.
3101 3193
3102=item * other models exist, such as the leader/follower pattern, where one 3194=item * other models exist, such as the leader/follower pattern, where one
3103loop is handed through multiple threads in a kind of round-robbin fashion. 3195loop is handed through multiple threads in a kind of round-robin fashion.
3104 3196
3105Chosing a model is hard - look around, learn, know that usually you cna do 3197Choosing a model is hard - look around, learn, know that usually you can do
3106better than you currently do :-) 3198better than you currently do :-)
3107 3199
3108=item * often you need to talk to some other thread which blocks in the 3200=item * often you need to talk to some other thread which blocks in the
3109event loop - C<ev_async> watchers can be used to wake them up from other 3201event loop - C<ev_async> watchers can be used to wake them up from other
3110threads safely (or from signal contexts...). 3202threads safely (or from signal contexts...).
3111 3203
3112=back 3204=back
3113 3205
3114=head2 COROUTINES 3206=head2 COROUTINES
3115 3207
3116Libev is much more accomodating to coroutines ("cooperative threads"): 3208Libev is much more accommodating to coroutines ("cooperative threads"):
3117libev fully supports nesting calls to it's functions from different 3209libev fully supports nesting calls to it's functions from different
3118coroutines (e.g. you can call C<ev_loop> on the same loop from two 3210coroutines (e.g. you can call C<ev_loop> on the same loop from two
3119different coroutines and switch freely between both coroutines running the 3211different coroutines and switch freely between both coroutines running the
3120loop, as long as you don't confuse yourself). The only exception is that 3212loop, as long as you don't confuse yourself). The only exception is that
3121you must not do this from C<ev_periodic> reschedule callbacks. 3213you must not do this from C<ev_periodic> reschedule callbacks.
… …
3162correct watcher to remove. The lists are usually short (you don't usually 3254correct watcher to remove. The lists are usually short (you don't usually
3163have many watchers waiting for the same fd or signal). 3255have many watchers waiting for the same fd or signal).
3164 3256
3165=item Finding the next timer in each loop iteration: O(1) 3257=item Finding the next timer in each loop iteration: O(1)
3166 3258
3167By virtue of using a binary heap, the next timer is always found at the 3259By virtue of using a binary or 4-heap, the next timer is always found at a
3168beginning of the storage array. 3260fixed position in the storage array.
3169 3261
3170=item Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd) 3262=item Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd)
3171 3263
3172A change means an I/O watcher gets started or stopped, which requires 3264A change means an I/O watcher gets started or stopped, which requires
3173libev to recalculate its status (and possibly tell the kernel, depending 3265libev to recalculate its status (and possibly tell the kernel, depending
3174on backend and wether C<ev_io_set> was used). 3266on backend and whether C<ev_io_set> was used).
3175 3267
3176=item Activating one watcher (putting it into the pending state): O(1) 3268=item Activating one watcher (putting it into the pending state): O(1)
3177 3269
3178=item Priority handling: O(number_of_priorities) 3270=item Priority handling: O(number_of_priorities)
3179 3271
… …
3186 3278
3187=item Processing ev_async_send: O(number_of_async_watchers) 3279=item Processing ev_async_send: O(number_of_async_watchers)
3188 3280
3189=item Processing signals: O(max_signal_number) 3281=item Processing signals: O(max_signal_number)
3190 3282
3191Sending involves a syscall I<iff> there were no other C<ev_async_send> 3283Sending involves a system call I<iff> there were no other C<ev_async_send>
3192calls in the current loop iteration. Checking for async and signal events 3284calls in the current loop iteration. Checking for async and signal events
3193involves iterating over all running async watchers or all signal numbers. 3285involves iterating over all running async watchers or all signal numbers.
3194 3286
3195=back 3287=back
3196 3288
… …
3202model. Libev still offers limited functionality on this platform in 3294model. Libev still offers limited functionality on this platform in
3203the form of the C<EVBACKEND_SELECT> backend, and only supports socket 3295the form of the C<EVBACKEND_SELECT> backend, and only supports socket
3204descriptors. This only applies when using Win32 natively, not when using 3296descriptors. This only applies when using Win32 natively, not when using
3205e.g. cygwin. 3297e.g. cygwin.
3206 3298
3299Lifting these limitations would basically require the full
3300re-implementation of the I/O system. If you are into these kinds of
3301things, then note that glib does exactly that for you in a very portable
3302way (note also that glib is the slowest event library known to man).
3303
3207There is no supported compilation method available on windows except 3304There is no supported compilation method available on windows except
3208embedding it into other applications. 3305embedding it into other applications.
3209 3306
3307Not a libev limitation but worth mentioning: windows apparently doesn't
3308accept large writes: instead of resulting in a partial write, windows will
3309either accept everything or return C<ENOBUFS> if the buffer is too large,
3310so make sure you only write small amounts into your sockets (less than a
3311megabyte seems safe, but thsi apparently depends on the amount of memory
3312available).
3313
3210Due to the many, low, and arbitrary limits on the win32 platform and the 3314Due to the many, low, and arbitrary limits on the win32 platform and
3211abysmal performance of winsockets, using a large number of sockets is not 3315the abysmal performance of winsockets, using a large number of sockets
3212recommended (and not reasonable). If your program needs to use more than 3316is 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 3317more 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 3318different implementation for windows, as libev offers the POSIX readiness
3215be implemented efficiently on windows (microsoft monopoly games). 3319notification model, which cannot be implemented efficiently on windows
3320(Microsoft monopoly games).
3216 3321
3217=over 4 3322=over 4
3218 3323
3219=item The winsocket select function 3324=item The winsocket select function
3220 3325
3221The winsocket C<select> function doesn't follow POSIX in that it requires 3326The winsocket C<select> function doesn't follow POSIX in that it
3222socket I<handles> and not socket I<file descriptors>. This makes select 3327requires socket I<handles> and not socket I<file descriptors> (it is
3223very inefficient, and also requires a mapping from file descriptors 3328also extremely buggy). This makes select very inefficient, and also
3224to socket handles. See the discussion of the C<EV_SELECT_USE_FD_SET>, 3329requires a mapping from file descriptors to socket handles. See the
3225C<EV_SELECT_IS_WINSOCKET> and C<EV_FD_TO_WIN32_HANDLE> preprocessor 3330discussion of the C<EV_SELECT_USE_FD_SET>, C<EV_SELECT_IS_WINSOCKET> and
3226symbols for more info. 3331C<EV_FD_TO_WIN32_HANDLE> preprocessor symbols for more info.
3227 3332
3228The configuration for a "naked" win32 using the microsoft runtime 3333The configuration for a "naked" win32 using the Microsoft runtime
3229libraries and raw winsocket select is: 3334libraries and raw winsocket select is:
3230 3335
3231 #define EV_USE_SELECT 1 3336 #define EV_USE_SELECT 1
3232 #define EV_SELECT_IS_WINSOCKET 1 /* forces EV_SELECT_USE_FD_SET, too */ 3337 #define EV_SELECT_IS_WINSOCKET 1 /* forces EV_SELECT_USE_FD_SET, too */
3233 3338
3234Note that winsockets handling of fd sets is O(n), so you can easily get a 3339Note that winsockets handling of fd sets is O(n), so you can easily get a
3235complexity in the O(n²) range when using win32. 3340complexity in the O(n²) range when using win32.
3236 3341
3237=item Limited number of file descriptors 3342=item Limited number of file descriptors
3238 3343
3239Windows has numerous arbitrary (and low) limits on things. Early versions 3344Windows has numerous arbitrary (and low) limits on things.
3240of winsocket's select only supported waiting for a max. of C<64> handles 3345
3346Early 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 3347of C<64> handles (probably owning to the fact that all windows kernels
3242C<64> things at the same time internally; microsoft recommends spawning a 3348can 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). 3349recommends spawning a chain of threads and wait for 63 handles and the
3350previous thread in each. Great).
3244 3351
3245Newer versions support more handles, but you need to define C<FD_SETSIZE> 3352Newer 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 3353to 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 3354call (which might be in libev or elsewhere, for example, perl does its own
3248select emulation on windows). 3355select emulation on windows).
3249 3356
3250Another limit is the number of file descriptors in the microsoft runtime 3357Another limit is the number of file descriptors in the Microsoft runtime
3251libraries, which by default is C<64> (there must be a hidden I<64> fetish 3358libraries, which by default is C<64> (there must be a hidden I<64> fetish
3252or something like this inside microsoft). You can increase this by calling 3359or something like this inside Microsoft). You can increase this by calling
3253C<_setmaxstdio>, which can increase this limit to C<2048> (another 3360C<_setmaxstdio>, which can increase this limit to C<2048> (another
3254arbitrary limit), but is broken in many versions of the microsoft runtime 3361arbitrary limit), but is broken in many versions of the Microsoft runtime
3255libraries. 3362libraries.
3256 3363
3257This might get you to about C<512> or C<2048> sockets (depending on 3364This might get you to about C<512> or C<2048> sockets (depending on
3258windows version and/or the phase of the moon). To get more, you need to 3365windows version and/or the phase of the moon). To get more, you need to
3259wrap all I/O functions and provide your own fd management, but the cost of 3366wrap all I/O functions and provide your own fd management, but the cost of
… …
3287 3394
3288The most portable way to handle signals is to block signals in all threads 3395The 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 3396except the initial one, and run the default loop in the initial thread as
3290well. 3397well.
3291 3398
3399=item C<long> must be large enough for common memory allocation sizes
3400
3401To improve portability and simplify using libev, libev uses C<long>
3402internally instead of C<size_t> when allocating its data structures. On
3403non-POSIX systems (Microsoft...) this might be unexpectedly low, but
3404is still at least 31 bits everywhere, which is enough for hundreds of
3405millions of watchers.
3406
3407=item C<double> must hold a time value in seconds with enough accuracy
3408
3409The type C<double> is used to represent timestamps. It is required to
3410have at least 51 bits of mantissa (and 9 bits of exponent), which is good
3411enough for at least into the year 4000. This requirement is fulfilled by
3412implementations implementing IEEE 754 (basically all existing ones).
3413
3292=back 3414=back
3293 3415
3294If you know of other additional requirements drop me a note. 3416If you know of other additional requirements drop me a note.
3295 3417
3296 3418
3419=head1 COMPILER WARNINGS
3420
3421Depending on your compiler and compiler settings, you might get no or a
3422lot of warnings when compiling libev code. Some people are apparently
3423scared by this.
3424
3425However, these are unavoidable for many reasons. For one, each compiler
3426has different warnings, and each user has different tastes regarding
3427warning options. "Warn-free" code therefore cannot be a goal except when
3428targeting a specific compiler and compiler-version.
3429
3430Another reason is that some compiler warnings require elaborate
3431workarounds, or other changes to the code that make it less clear and less
3432maintainable.
3433
3434And of course, some compiler warnings are just plain stupid, or simply
3435wrong (because they don't actually warn about the condition their message
3436seems to warn about).
3437
3438While libev is written to generate as few warnings as possible,
3439"warn-free" code is not a goal, and it is recommended not to build libev
3440with any compiler warnings enabled unless you are prepared to cope with
3441them (e.g. by ignoring them). Remember that warnings are just that:
3442warnings, not errors, or proof of bugs.
3443
3444
3445=head1 VALGRIND
3446
3447Valgrind has a special section here because it is a popular tool that is
3448highly useful, but valgrind reports are very hard to interpret.
3449
3450If you think you found a bug (memory leak, uninitialised data access etc.)
3451in libev, then check twice: If valgrind reports something like:
3452
3453 ==2274== definitely lost: 0 bytes in 0 blocks.
3454 ==2274== possibly lost: 0 bytes in 0 blocks.
3455 ==2274== still reachable: 256 bytes in 1 blocks.
3456
3457Then there is no memory leak. Similarly, under some circumstances,
3458valgrind might report kernel bugs as if it were a bug in libev, or it
3459might be confused (it is a very good tool, but only a tool).
3460
3461If you are unsure about something, feel free to contact the mailing list
3462with the full valgrind report and an explanation on why you think this is
3463a bug in libev. However, don't be annoyed when you get a brisk "this is
3464no bug" answer and take the chance of learning how to interpret valgrind
3465properly.
3466
3467If you need, for some reason, empty reports from valgrind for your project
3468I suggest using suppression lists.
3469
3470
3297=head1 AUTHOR 3471=head1 AUTHOR
3298 3472
3299Marc Lehmann <libev@schmorp.de>. 3473Marc Lehmann <libev@schmorp.de>.
3300 3474

Diff Legend

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