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

Comparing libev/ev.pod (file contents):
Revision 1.144 by root, Mon Apr 7 12:33:29 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
… …
196See the description of C<ev_embed> watchers for more info. 217See the description of C<ev_embed> watchers for more info.
197 218
198=item ev_set_allocator (void *(*cb)(void *ptr, long size)) 219=item ev_set_allocator (void *(*cb)(void *ptr, long size))
199 220
200Sets the allocation function to use (the prototype is similar - the 221Sets the allocation function to use (the prototype is similar - the
201semantics is identical - to the realloc C function). It is used to 222semantics are identical to the C<realloc> C89/SuS/POSIX function). It is
202allocate and free memory (no surprises here). If it returns zero when 223used to allocate and free memory (no surprises here). If it returns zero
203memory needs to be allocated, the library might abort or take some 224when memory needs to be allocated (C<size != 0>), the library might abort
204potentially destructive action. The default is your system realloc 225or take some potentially destructive action.
205function. 226
227Since some systems (at least OpenBSD and Darwin) fail to implement
228correct C<realloc> semantics, libev will use a wrapper around the system
229C<realloc> and C<free> functions by default.
206 230
207You could override this function in high-availability programs to, say, 231You could override this function in high-availability programs to, say,
208free some memory if it cannot allocate memory, to use a special allocator, 232free some memory if it cannot allocate memory, to use a special allocator,
209or even to sleep a while and retry until some memory is available. 233or even to sleep a while and retry until some memory is available.
210 234
211Example: Replace the libev allocator with one that waits a bit and then 235Example: Replace the libev allocator with one that waits a bit and then
212retries). 236retries (example requires a standards-compliant C<realloc>).
213 237
214 static void * 238 static void *
215 persistent_realloc (void *ptr, size_t size) 239 persistent_realloc (void *ptr, size_t size)
216 { 240 {
217 for (;;) 241 for (;;)
… …
228 ... 252 ...
229 ev_set_allocator (persistent_realloc); 253 ev_set_allocator (persistent_realloc);
230 254
231=item ev_set_syserr_cb (void (*cb)(const char *msg)); 255=item ev_set_syserr_cb (void (*cb)(const char *msg));
232 256
233Set the callback function to call on a retryable syscall error (such 257Set the callback function to call on a retryable system call error (such
234as failed select, poll, epoll_wait). The message is a printable string 258as failed select, poll, epoll_wait). The message is a printable string
235indicating the system call or subsystem causing the problem. If this 259indicating the system call or subsystem causing the problem. If this
236callback 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
237matter what, when it returns. That is, libev will generally retry the 261matter what, when it returns. That is, libev will generally retry the
238requested 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
239(such as abort). 263(such as abort).
240 264
241Example: This is basically the same thing that libev does internally, too. 265Example: This is basically the same thing that libev does internally, too.
… …
274from 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,
275as loops cannot bes hared easily between threads anyway). 299as loops cannot bes hared easily between threads anyway).
276 300
277The 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
278C<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
279for 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
280create 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
281can simply overwrite the C<SIGCHLD> signal handler I<after> calling 305can simply overwrite the C<SIGCHLD> signal handler I<after> calling
282C<ev_default_init>. 306C<ev_default_init>.
283 307
284The flags argument can be used to specify special behaviour or specific 308The flags argument can be used to specify special behaviour or specific
… …
293The 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
294thing, believe me). 318thing, believe me).
295 319
296=item C<EVFLAG_NOENV> 320=item C<EVFLAG_NOENV>
297 321
298If 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
299or setgid) then libev will I<not> look at the environment variable 323or setgid) then libev will I<not> look at the environment variable
300C<LIBEV_FLAGS>. Otherwise (the default), this environment variable will 324C<LIBEV_FLAGS>. Otherwise (the default), this environment variable will
301override 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
302useful 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
303around bugs. 327around bugs.
… …
310 334
311This works by calling C<getpid ()> on every iteration of the loop, 335This works by calling C<getpid ()> on every iteration of the loop,
312and 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
313iterations and little real work, but is usually not noticeable (on my 337iterations and little real work, but is usually not noticeable (on my
314GNU/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
315without 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
316C<pthread_atfork> which is even faster). 340C<pthread_atfork> which is even faster).
317 341
318The 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
319forget about forgetting to tell libev about forking) when you use this 343forget about forgetting to tell libev about forking) when you use this
320flag. 344flag.
321 345
322This 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>
323environment variable. 347environment variable.
324 348
325=item C<EVBACKEND_SELECT> (value 1, portable select backend) 349=item C<EVBACKEND_SELECT> (value 1, portable select backend)
326 350
327This is your standard select(2) backend. Not I<completely> standard, as 351This is your standard select(2) backend. Not I<completely> standard, as
… …
329but 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
330using 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
331usually the fastest backend for a low number of (low-numbered :) fds. 355usually the fastest backend for a low number of (low-numbered :) fds.
332 356
333To 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
334parallelity (most of the file descriptors should be busy). If you are 358parallelism (most of the file descriptors should be busy). If you are
335writing 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
336connections as possible during one iteration. You might also want to have 360connections as possible during one iteration. You might also want to have
337a 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
338readyness notifications you get per iteration. 362readiness notifications you get per iteration.
339 363
340=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)
341 365
342And this is your standard poll(2) backend. It's more complicated 366And this is your standard poll(2) backend. It's more complicated
343than select, but handles sparse fds better and has no artificial 367than select, but handles sparse fds better and has no artificial
… …
351For 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,
352but it scales phenomenally better. While poll and select usually scale 376but it scales phenomenally better. While poll and select usually scale
353like 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),
354epoll 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
355of shortcomings, such as silently dropping events in some hard-to-detect 379of shortcomings, such as silently dropping events in some hard-to-detect
356cases 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
357support for dup. 381support for dup.
358 382
359While 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
360will 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
361(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
362best 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
363very well if you register events for both fds. 387very well if you register events for both fds.
364 388
365Please note that epoll sometimes generates spurious notifications, so you 389Please note that epoll sometimes generates spurious notifications, so you
… …
368 392
369Best performance from this backend is achieved by not unregistering all 393Best performance from this backend is achieved by not unregistering all
370watchers 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.
371keep at least one watcher active per fd at all times. 395keep at least one watcher active per fd at all times.
372 396
373While nominally embeddeble in other event loops, this feature is broken in 397While nominally embeddable in other event loops, this feature is broken in
374all kernel versions tested so far. 398all kernel versions tested so far.
375 399
376=item C<EVBACKEND_KQUEUE> (value 8, most BSD clones) 400=item C<EVBACKEND_KQUEUE> (value 8, most BSD clones)
377 401
378Kqueue deserves special mention, as at the time of this writing, it 402Kqueue deserves special mention, as at the time of this writing, it
379was 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
380with anything but sockets and pipes, except on Darwin, where of course 404with anything but sockets and pipes, except on Darwin, where of course
381it's completely useless). For this reason it's not being "autodetected" 405it's completely useless). For this reason it's not being "auto-detected"
382unless you explicitly specify it explicitly in the flags (i.e. using 406unless you explicitly specify it explicitly in the flags (i.e. using
383C<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)
384system like NetBSD. 408system like NetBSD.
385 409
386You 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
… …
388the target platform). See C<ev_embed> watchers for more info. 412the target platform). See C<ev_embed> watchers for more info.
389 413
390It 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
391kernel is more efficient (which says nothing about its actual speed, of 415kernel is more efficient (which says nothing about its actual speed, of
392course). While stopping, setting and starting an I/O watcher does never 416course). While stopping, setting and starting an I/O watcher does never
393cause 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
394two 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
395drops fds silently in similarly hard-to-detect cases. 419drops fds silently in similarly hard-to-detect cases.
396 420
397This backend usually performs well under most conditions. 421This backend usually performs well under most conditions.
398 422
… …
413=item C<EVBACKEND_PORT> (value 32, Solaris 10) 437=item C<EVBACKEND_PORT> (value 32, Solaris 10)
414 438
415This 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,
416it'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)).
417 441
418Please note that solaris event ports can deliver a lot of spurious 442Please note that Solaris event ports can deliver a lot of spurious
419notifications, 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
420blocking when no data (or space) is available. 444blocking when no data (or space) is available.
421 445
422While this backend scales well, it requires one system call per active 446While this backend scales well, it requires one system call per active
423file descriptor per loop iteration. For small and medium numbers of file 447file descriptor per loop iteration. For small and medium numbers of file
424descriptors a "slow" C<EVBACKEND_SELECT> or C<EVBACKEND_POLL> backend 448descriptors a "slow" C<EVBACKEND_SELECT> or C<EVBACKEND_POLL> backend
425might perform better. 449might perform better.
426 450
427On the positive side, ignoring the spurious readyness notifications, this 451On the positive side, ignoring the spurious readiness notifications, this
428backend actually performed to specification in all tests and is fully 452backend actually performed to specification in all tests and is fully
429embeddable, which is a rare feat among the OS-specific backends. 453embeddable, which is a rare feat among the OS-specific backends.
430 454
431=item C<EVBACKEND_ALL> 455=item C<EVBACKEND_ALL>
432 456
… …
436 460
437It is definitely not recommended to use this flag. 461It is definitely not recommended to use this flag.
438 462
439=back 463=back
440 464
441If 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
442backends 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
443specified, all backends in C<ev_recommended_backends ()> will be tried. 467specified, all backends in C<ev_recommended_backends ()> will be tried.
444 468
445The most typical usage is like this: 469The most typical usage is like this:
446 470
… …
478=item ev_default_destroy () 502=item ev_default_destroy ()
479 503
480Destroys the default loop again (frees all memory and kernel state 504Destroys the default loop again (frees all memory and kernel state
481etc.). 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
482sense, 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
483responsibility to either stop all watchers cleanly yoursef I<before> 507responsibility to either stop all watchers cleanly yourself I<before>
484calling this function, or cope with the fact afterwards (which is usually 508calling this function, or cope with the fact afterwards (which is usually
485the 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
486for example). 510for example).
487 511
488Note 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
… …
569A 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
570those 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
571case 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.
572 596
573A 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
574neccessary) and will handle those and any outstanding ones. It will block 598necessary) and will handle those and any outstanding ones. It will block
575your 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
576one 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
577external event in conjunction with something not expressible using other 601external event in conjunction with something not expressible using other
578libev 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
579usually a better approach for this kind of thing. 603usually a better approach for this kind of thing.
… …
680to spend more time collecting timeouts, at the expense of increased 704to spend more time collecting timeouts, at the expense of increased
681latency (the watcher callback will be called later). C<ev_io> watchers 705latency (the watcher callback will be called later). C<ev_io> watchers
682will 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
683any overhead in libev. 707any overhead in libev.
684 708
685Many (busy) programs can usually benefit by setting the io collect 709Many (busy) programs can usually benefit by setting the I/O collect
686interval 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
687interactive servers (of course not for games), likewise for timeouts. It 711interactive servers (of course not for games), likewise for timeouts. It
688usually 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>,
689as 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.
690 725
691=back 726=back
692 727
693 728
694=head1 ANATOMY OF A WATCHER 729=head1 ANATOMY OF A WATCHER
… …
714watcher 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,
715although this can sometimes be quite valid). 750although this can sometimes be quite valid).
716 751
717Each 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
718(watcher *, callback)>, which expects a callback to be provided. This 753(watcher *, callback)>, which expects a callback to be provided. This
719callback 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
720watchers, each time the event loop detects that the file descriptor given 755watchers, each time the event loop detects that the file descriptor given
721is readable and/or writable). 756is readable and/or writable).
722 757
723Each watcher type has its own C<< ev_<type>_set (watcher *, ...) >> macro 758Each watcher type has its own C<< ev_<type>_set (watcher *, ...) >> macro
724with arguments specific to this watcher type. There is also a macro 759with arguments specific to this watcher type. There is also a macro
… …
800 835
801The given async watcher has been asynchronously notified (see C<ev_async>). 836The given async watcher has been asynchronously notified (see C<ev_async>).
802 837
803=item C<EV_ERROR> 838=item C<EV_ERROR>
804 839
805An unspecified error has occured, the watcher has been stopped. This might 840An unspecified error has occurred, the watcher has been stopped. This might
806happen because the watcher could not be properly started because libev 841happen because the watcher could not be properly started because libev
807ran 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
808problem. 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
809with the watcher being stopped. 844with the watcher being stopped.
810 845
811Libev will usually signal a few "dummy" events together with an error, 846Libev will usually signal a few "dummy" events together with an error,
812for 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
813your 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
814with 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
815programs, though, so beware. 850programs, though, so beware.
816 851
817=back 852=back
818 853
819=head2 GENERIC WATCHER FUNCTIONS 854=head2 GENERIC WATCHER FUNCTIONS
… …
849Although some watcher types do not have type-specific arguments 884Although some watcher types do not have type-specific arguments
850(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.
851 886
852=item C<ev_TYPE_init> (ev_TYPE *watcher, callback, [args]) 887=item C<ev_TYPE_init> (ev_TYPE *watcher, callback, [args])
853 888
854This 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
855calls 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
856a watcher. The same limitations apply, of course. 891a watcher. The same limitations apply, of course.
857 892
858=item C<ev_TYPE_start> (loop *, ev_TYPE *watcher) 893=item C<ev_TYPE_start> (loop *, ev_TYPE *watcher)
859 894
860Starts (activates) the given watcher. Only active watchers will receive 895Starts (activates) the given watcher. Only active watchers will receive
… …
1029If 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
1030(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
1031C<EVBACKEND_POLL>). 1066C<EVBACKEND_POLL>).
1032 1067
1033Another 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
1034receive "spurious" readyness notifications, that is your callback might 1069receive "spurious" readiness notifications, that is your callback might
1035be 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
1036because 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
1037lot 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
1038this situation even with a relatively standard program structure. Thus 1073this situation even with a relatively standard program structure. Thus
1039it 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
1040C<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.
1041 1076
1042If 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
1043play 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
1044whether 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
1045such 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
1046its own, so its quite safe to use). 1081its own, so its quite safe to use).
1047 1082
1048=head3 The special problem of disappearing file descriptors 1083=head3 The special problem of disappearing file descriptors
… …
1108=item ev_io_init (ev_io *, callback, int fd, int events) 1143=item ev_io_init (ev_io *, callback, int fd, int events)
1109 1144
1110=item ev_io_set (ev_io *, int fd, int events) 1145=item ev_io_set (ev_io *, int fd, int events)
1111 1146
1112Configures 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
1113rceeive 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
1114C<EV_READ | EV_WRITE> to receive the given events. 1149C<EV_READ | EV_WRITE> to receive the given events.
1115 1150
1116=item int fd [read-only] 1151=item int fd [read-only]
1117 1152
1118The file descriptor being watched. 1153The file descriptor being watched.
… …
1148 1183
1149Timer watchers are simple relative timers that generate an event after a 1184Timer watchers are simple relative timers that generate an event after a
1150given time, and optionally repeating in regular intervals after that. 1185given time, and optionally repeating in regular intervals after that.
1151 1186
1152The 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
1153times 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
1154time, it will still time out after (roughly) and hour. "Roughly" because 1189year, it will still time out after (roughly) and hour. "Roughly" because
1155detecting time jumps is hard, and some inaccuracies are unavoidable (the 1190detecting time jumps is hard, and some inaccuracies are unavoidable (the
1156monotonic clock option helps a lot here). 1191monotonic clock option helps a lot here).
1157 1192
1158The relative timeouts are calculated relative to the C<ev_now ()> 1193The relative timeouts are calculated relative to the C<ev_now ()>
1159time. 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
… …
1161you 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
1162on the current time, use something like this to adjust for this: 1197on the current time, use something like this to adjust for this:
1163 1198
1164 ev_timer_set (&timer, after + ev_now () - ev_time (), 0.); 1199 ev_timer_set (&timer, after + ev_now () - ev_time (), 0.);
1165 1200
1166The 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,
1167but if multiple timers become ready during the same loop iteration then 1202but if multiple timers become ready during the same loop iteration then
1168order of execution is undefined. 1203order of execution is undefined.
1169 1204
1170=head3 Watcher-Specific Functions and Data Members 1205=head3 Watcher-Specific Functions and Data Members
1171 1206
… …
1173 1208
1174=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)
1175 1210
1176=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)
1177 1212
1178Configure the timer to trigger after C<after> seconds. If C<repeat> is 1213Configure the timer to trigger after C<after> seconds. If C<repeat>
1179C<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
1180timer will automatically be configured to trigger again C<repeat> seconds 1215reached. If it is positive, then the timer will automatically be
1181later, again, and again, until stopped manually. 1216configured to trigger again C<repeat> seconds later, again, and again,
1217until stopped manually.
1182 1218
1183The 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
1184configure 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
1185exactly 10 second intervals. If, however, your program cannot keep up with 1221trigger at exactly 10 second intervals. If, however, your program cannot
1186the 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
1187timer will not fire more than once per event loop iteration. 1223do stuff) the timer will not fire more than once per event loop iteration.
1188 1224
1189=item ev_timer_again (loop, ev_timer *) 1225=item ev_timer_again (loop, ev_timer *)
1190 1226
1191This 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
1192repeating. The exact semantics are: 1228repeating. The exact semantics are:
1193 1229
1194If the timer is pending, its pending status is cleared. 1230If the timer is pending, its pending status is cleared.
1195 1231
1196If 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).
1197 1233
1198If the timer is repeating, either start it if necessary (with the 1234If the timer is repeating, either start it if necessary (with the
1199C<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.
1200 1236
1201This sounds a bit complicated, but here is a useful and typical 1237This sounds a bit complicated, but here is a useful and typical
1202example: 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
1203timeout, 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
1204seconds 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
1205configure 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
1206C<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
1207you 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
… …
1268 1304
1269Periodic 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
1270(and unfortunately a bit complex). 1306(and unfortunately a bit complex).
1271 1307
1272Unlike 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)
1273but on wallclock time (absolute time). You can tell a periodic watcher 1309but on wall clock time (absolute time). You can tell a periodic watcher
1274to 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
1275periodic 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 ()
1276+ 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
1277take 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
1278roughly 10 seconds later). 1315roughly 10 seconds later as it uses a relative timeout).
1279 1316
1280They 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,
1281triggering an event on each midnight, local time or other, complicated, 1318such as triggering an event on each "midnight, local time", or other
1282rules. 1319complicated, rules.
1283 1320
1284As 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
1285time (C<at>) has been passed, but if multiple periodic timers become ready 1322time (C<at>) has passed, but if multiple periodic timers become ready
1286during the same loop iteration then order of execution is undefined. 1323during the same loop iteration then order of execution is undefined.
1287 1324
1288=head3 Watcher-Specific Functions and Data Members 1325=head3 Watcher-Specific Functions and Data Members
1289 1326
1290=over 4 1327=over 4
… …
1298 1335
1299=over 4 1336=over 4
1300 1337
1301=item * absolute timer (at = time, interval = reschedule_cb = 0) 1338=item * absolute timer (at = time, interval = reschedule_cb = 0)
1302 1339
1303In this configuration the watcher triggers an event at the wallclock time 1340In this configuration the watcher triggers an event after the wall clock
1304C<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
1305that 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
1306system time reaches or surpasses this time. 1343run when the system time reaches or surpasses this time.
1307 1344
1308=item * repeating interval timer (at = offset, interval > 0, reschedule_cb = 0) 1345=item * repeating interval timer (at = offset, interval > 0, reschedule_cb = 0)
1309 1346
1310In 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
1311C<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)
1312and then repeat, regardless of any time jumps. 1349and then repeat, regardless of any time jumps.
1313 1350
1314This 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
1315time: 1352time, for example, here is a C<ev_periodic> that triggers each hour, on
1353the hour:
1316 1354
1317 ev_periodic_set (&periodic, 0., 3600., 0); 1355 ev_periodic_set (&periodic, 0., 3600., 0);
1318 1356
1319This 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,
1320but 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
1321full 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
1322by 3600. 1360by 3600.
1323 1361
1324Another way to think about it (for the mathematically inclined) is that 1362Another way to think about it (for the mathematically inclined) is that
1325C<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
1326time where C<time = at (mod interval)>, regardless of any time jumps. 1364time where C<time = at (mod interval)>, regardless of any time jumps.
1327 1365
1328For 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
1329C<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
1330this 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).
1331 1374
1332=item * manual reschedule mode (at and interval ignored, reschedule_cb = callback) 1375=item * manual reschedule mode (at and interval ignored, reschedule_cb = callback)
1333 1376
1334In 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
1335ignored. Instead, each time the periodic watcher gets scheduled, the 1378ignored. Instead, each time the periodic watcher gets scheduled, the
1336reschedule callback will be called with the watcher as first, and the 1379reschedule callback will be called with the watcher as first, and the
1337current time as second argument. 1380current time as second argument.
1338 1381
1339NOTE: I<This callback MUST NOT stop or destroy any periodic watcher, 1382NOTE: I<This callback MUST NOT stop or destroy any periodic watcher,
1340ever, or make any event loop modifications>. If you need to stop it, 1383ever, or make ANY event loop modifications whatsoever>.
1341return C<now + 1e30> (or so, fudge fudge) and stop it afterwards (e.g. by
1342starting an C<ev_prepare> watcher, which is legal).
1343 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
1344Its prototype is C<ev_tstamp (*reschedule_cb)(struct ev_periodic *w, 1389The callback prototype is C<ev_tstamp (*reschedule_cb)(struct ev_periodic
1345ev_tstamp now)>, e.g.: 1390*w, ev_tstamp now)>, e.g.:
1346 1391
1347 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)
1348 { 1393 {
1349 return now + 60.; 1394 return now + 60.;
1350 } 1395 }
… …
1352It 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
1353(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
1354will usually be called just before the callback will be triggered, but 1399will usually be called just before the callback will be triggered, but
1355might be called at other times, too. 1400might be called at other times, too.
1356 1401
1357NOTE: 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
1358passed C<now> value >>. Not even C<now> itself will do, it I<must> be larger. 1403equal to the passed C<now> value >>.
1359 1404
1360This 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
1361triggers 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
1362next 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
1363you 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
1364reason I omitted it as an example). 1409reason I omitted it as an example).
1365 1410
1366=back 1411=back
… …
1370Simply stops and restarts the periodic watcher again. This is only useful 1415Simply stops and restarts the periodic watcher again. This is only useful
1371when you changed some parameters or the reschedule callback would return 1416when you changed some parameters or the reschedule callback would return
1372a 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
1373program when the crontabs have changed). 1418program when the crontabs have changed).
1374 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
1375=item ev_tstamp offset [read-write] 1425=item ev_tstamp offset [read-write]
1376 1426
1377When repeating, this contains the offset value, otherwise this is the 1427When repeating, this contains the offset value, otherwise this is the
1378absolute 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>).
1379 1429
… …
1390 1440
1391The current reschedule callback, or C<0>, if this functionality is 1441The current reschedule callback, or C<0>, if this functionality is
1392switched 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
1393the periodic timer fires or C<ev_periodic_again> is being called. 1443the periodic timer fires or C<ev_periodic_again> is being called.
1394 1444
1395=item ev_tstamp at [read-only]
1396
1397When active, contains the absolute time that the watcher is supposed to
1398trigger next.
1399
1400=back 1445=back
1401 1446
1402=head3 Examples 1447=head3 Examples
1403 1448
1404Example: Call a callback every hour, or, more precisely, whenever the 1449Example: Call a callback every hour, or, more precisely, whenever the
1405system clock is divisible by 3600. The callback invocation times have 1450system clock is divisible by 3600. The callback invocation times have
1406potentially a lot of jittering, but good long-term stability. 1451potentially a lot of jitter, but good long-term stability.
1407 1452
1408 static void 1453 static void
1409 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)
1410 { 1455 {
1411 ... 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)
… …
1448as 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
1449watcher 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
1450SIG_DFL (regardless of what it was set to before). 1495SIG_DFL (regardless of what it was set to before).
1451 1496
1452If possible and supported, libev will install its handlers with 1497If possible and supported, libev will install its handlers with
1453C<SA_RESTART> behaviour enabled, so syscalls should not be unduly 1498C<SA_RESTART> behaviour enabled, so system calls should not be unduly
1454interrupted. If you have a problem with syscalls getting interrupted by 1499interrupted. If you have a problem with system calls getting interrupted by
1455signals 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
1456them in an C<ev_prepare> watcher. 1501them in an C<ev_prepare> watcher.
1457 1502
1458=head3 Watcher-Specific Functions and Data Members 1503=head3 Watcher-Specific Functions and Data Members
1459 1504
… …
1494is 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
1495forked (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
1496loop isn't entered (or is continued from a watcher). 1541loop isn't entered (or is continued from a watcher).
1497 1542
1498Only the default event loop is capable of handling signals, and therefore 1543Only the default event loop is capable of handling signals, and therefore
1499you can only rgeister child watchers in the default event loop. 1544you can only register child watchers in the default event loop.
1500 1545
1501=head3 Process Interaction 1546=head3 Process Interaction
1502 1547
1503Libev grabs C<SIGCHLD> as soon as the default event loop is 1548Libev grabs C<SIGCHLD> as soon as the default event loop is
1504initialised. This is necessary to guarantee proper behaviour even if 1549initialised. This is necessary to guarantee proper behaviour even if
1505the first child watcher is started after the child exits. The occurance 1550the first child watcher is started after the child exits. The occurrence
1506of C<SIGCHLD> is recorded asynchronously, but child reaping is done 1551of C<SIGCHLD> is recorded asynchronously, but child reaping is done
1507synchronously as part of the event loop processing. Libev always reaps all 1552synchronously as part of the event loop processing. Libev always reaps all
1508children, even ones not watched. 1553children, even ones not watched.
1509 1554
1510=head3 Overriding the Built-In Processing 1555=head3 Overriding the Built-In Processing
… …
1579 } 1624 }
1580 1625
1581 1626
1582=head2 C<ev_stat> - did the file attributes just change? 1627=head2 C<ev_stat> - did the file attributes just change?
1583 1628
1584This watches a filesystem path for attribute changes. That is, it calls 1629This watches a file system path for attribute changes. That is, it calls
1585C<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
1586compared to the last time, invoking the callback if it did. 1631compared to the last time, invoking the callback if it did.
1587 1632
1588The 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
1589not 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
… …
1607as even with OS-supported change notifications, this can be 1652as even with OS-supported change notifications, this can be
1608resource-intensive. 1653resource-intensive.
1609 1654
1610At the time of this writing, only the Linux inotify interface is 1655At the time of this writing, only the Linux inotify interface is
1611implemented (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
1612reader). 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
1613semantics of C<ev_stat> watchers, which means that libev sometimes needs 1659not change the semantics of C<ev_stat> watchers, which means that libev
1614to fall back to regular polling again even with inotify, but changes are 1660sometimes needs to fall back to regular polling again even with inotify,
1615usually detected immediately, and if the file exists there will be no 1661but changes are usually detected immediately, and if the file exists there
1616polling. 1662will be no polling.
1617 1663
1618=head3 ABI Issues (Largefile Support) 1664=head3 ABI Issues (Largefile Support)
1619 1665
1620Libev by default (unless the user overrides this) uses the default 1666Libev by default (unless the user overrides this) uses the default
1621compilation environment, which means that on systems with optionally 1667compilation environment, which means that on systems with optionally
1622disabled 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
1623structure. When using the library from programs that change the ABI to 1669structure. When using the library from programs that change the ABI to
1624use 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
1625compile libev with the same flags to get binary compatibility. This is 1671compile libev with the same flags to get binary compatibility. This is
1626obviously 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
1627most noticably with ev_stat and largefile support. 1673most noticeably with ev_stat and large file support.
1628 1674
1629=head3 Inotify 1675=head3 Inotify
1630 1676
1631When C<inotify (7)> support has been compiled into libev (generally only 1677When C<inotify (7)> support has been compiled into libev (generally only
1632available 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
1633change detection where possible. The inotify descriptor will be created lazily 1679change detection where possible. The inotify descriptor will be created lazily
1634when the first C<ev_stat> watcher is being started. 1680when the first C<ev_stat> watcher is being started.
1635 1681
1636Inotify presense does not change the semantics of C<ev_stat> watchers 1682Inotify presence does not change the semantics of C<ev_stat> watchers
1637except that changes might be detected earlier, and in some cases, to avoid 1683except that changes might be detected earlier, and in some cases, to avoid
1638making regular C<stat> calls. Even in the presense of inotify support 1684making regular C<stat> calls. Even in the presence of inotify support
1639there are many cases where libev has to resort to regular C<stat> polling. 1685there are many cases where libev has to resort to regular C<stat> polling.
1640 1686
1641(There is no support for kqueue, as apparently it cannot be used to 1687(There is no support for kqueue, as apparently it cannot be used to
1642implement this functionality, due to the requirement of having a file 1688implement this functionality, due to the requirement of having a file
1643descriptor open on the object at all times). 1689descriptor open on the object at all times).
1644 1690
1645=head3 The special problem of stat time resolution 1691=head3 The special problem of stat time resolution
1646 1692
1647The C<stat ()> syscall only supports full-second resolution portably, and 1693The C<stat ()> system call only supports full-second resolution portably, and
1648even on systems where the resolution is higher, many filesystems still 1694even on systems where the resolution is higher, many file systems still
1649only support whole seconds. 1695only support whole seconds.
1650 1696
1651That 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
1652miss 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
1653your callback, which does something. When there is another update within 1699calls your callback, which does something. When there is another update
1654the 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.
1655 1702
1656The 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
1657the 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
1658(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);
1659is added to work around small timing inconsistencies of some operating 1706ev_timer_again (loop, w)>).
1660systems. 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).
1661 1716
1662=head3 Watcher-Specific Functions and Data Members 1717=head3 Watcher-Specific Functions and Data Members
1663 1718
1664=over 4 1719=over 4
1665 1720
… …
1671C<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
1672be 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
1673a 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
1674path for as long as the watcher is active. 1729path for as long as the watcher is active.
1675 1730
1676The 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
1677relative 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
1678last change was detected). 1733was detected).
1679 1734
1680=item ev_stat_stat (loop, ev_stat *) 1735=item ev_stat_stat (loop, ev_stat *)
1681 1736
1682Updates the stat buffer immediately with new values. If you change the 1737Updates the stat buffer immediately with new values. If you change the
1683watched path in your callback, you could call this fucntion to avoid 1738watched path in your callback, you could call this function to avoid
1684detecting this change (while introducing a race condition). Can also be 1739detecting this change (while introducing a race condition if you are not
1685useful simply to find out the new values. 1740the only one changing the path). Can also be useful simply to find out the
1741new values.
1686 1742
1687=item ev_statdata attr [read-only] 1743=item ev_statdata attr [read-only]
1688 1744
1689The most-recently detected attributes of the file. Although the type is of 1745The most-recently detected attributes of the file. Although the type is
1690C<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
1691suitable 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
1692was some error while C<stat>ing the file. 1749some error while C<stat>ing the file.
1693 1750
1694=item ev_statdata prev [read-only] 1751=item ev_statdata prev [read-only]
1695 1752
1696The previous attributes of the file. The callback gets invoked whenever 1753The previous attributes of the file. The callback gets invoked whenever
1697C<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>.
1698 1757
1699=item ev_tstamp interval [read-only] 1758=item ev_tstamp interval [read-only]
1700 1759
1701The specified interval. 1760The specified interval.
1702 1761
1703=item const char *path [read-only] 1762=item const char *path [read-only]
1704 1763
1705The filesystem path that is being watched. 1764The file system path that is being watched.
1706 1765
1707=back 1766=back
1708 1767
1709=head3 Examples 1768=head3 Examples
1710 1769
… …
1756 } 1815 }
1757 1816
1758 ... 1817 ...
1759 ev_stat_init (&passwd, stat_cb, "/etc/passwd", 0.); 1818 ev_stat_init (&passwd, stat_cb, "/etc/passwd", 0.);
1760 ev_stat_start (loop, &passwd); 1819 ev_stat_start (loop, &passwd);
1761 ev_timer_init (&timer, timer_cb, 0., 1.01); 1820 ev_timer_init (&timer, timer_cb, 0., 1.02);
1762 1821
1763 1822
1764=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...
1765 1824
1766Idle 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
… …
1836 1895
1837This 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
1838to 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
1839them 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
1840provide just this functionality). Then, in the check watcher you check for 1899provide just this functionality). Then, in the check watcher you check for
1841any events that occured (by checking the pending status of all watchers 1900any events that occurred (by checking the pending status of all watchers
1842and 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
1843callbacks will never actually be called (but must be valid nevertheless, 1902callbacks will never actually be called (but must be valid nevertheless,
1844because you never know, you know?). 1903because you never know, you know?).
1845 1904
1846As another example, the Perl Coro module uses these hooks to integrate 1905As another example, the Perl Coro module uses these hooks to integrate
… …
1854 1913
1855It 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>)
1856priority, to ensure that they are being run before any other watchers 1915priority, to ensure that they are being run before any other watchers
1857after 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,
1858too) should not activate ("feed") events into libev. While libev fully 1917too) should not activate ("feed") events into libev. While libev fully
1859supports this, they will be called before other C<ev_check> watchers 1918supports this, they might get executed before other C<ev_check> watchers
1860did 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
1861(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
1862state until their C<ev_check> watcher ran (always remind yourself to 1921state until their C<ev_check> watcher ran (always remind yourself to
1863coexist peacefully with others). 1922coexist peacefully with others).
1864 1923
… …
1879=head3 Examples 1938=head3 Examples
1880 1939
1881There 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
1882into 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
1883(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
1884use 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
1885embeds 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
1886into the Glib event loop). 1945Glib event loop).
1887 1946
1888Method 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,
1889and 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
1890is 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
1891priority 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
… …
1948 2007
1949Method 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>
1950in the prepare watcher and would dispose of the check watcher. 2009in the prepare watcher and would dispose of the check watcher.
1951 2010
1952Method 3: If the module to be embedded supports explicit event 2011Method 3: If the module to be embedded supports explicit event
1953notification (adns does), you can also make use of the actual watcher 2012notification (libadns does), you can also make use of the actual watcher
1954callbacks, and only destroy/create the watchers in the prepare watcher. 2013callbacks, and only destroy/create the watchers in the prepare watcher.
1955 2014
1956 static void 2015 static void
1957 timer_cb (EV_P_ ev_timer *w, int revents) 2016 timer_cb (EV_P_ ev_timer *w, int revents)
1958 { 2017 {
… …
1973 } 2032 }
1974 2033
1975 // do not ever call adns_afterpoll 2034 // do not ever call adns_afterpoll
1976 2035
1977Method 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
1978want 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
1979their poll function. The drawback with this solution is that the main 2038their poll function. The drawback with this solution is that the main
1980loop 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
1981this. 2040this.
1982 2041
1983 static gint 2042 static gint
… …
2067 2126
2068Configures the watcher to embed the given loop, which must be 2127Configures the watcher to embed the given loop, which must be
2069embeddable. 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
2070invoked automatically, otherwise it is the responsibility of the callback 2129invoked automatically, otherwise it is the responsibility of the callback
2071to 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,
2072if 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).
2073 2132
2074=item ev_embed_sweep (loop, ev_embed *) 2133=item ev_embed_sweep (loop, ev_embed *)
2075 2134
2076Make a single, non-blocking sweep over the embedded loop. This works 2135Make a single, non-blocking sweep over the embedded loop. This works
2077similarly 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
2078apropriate way for embedded loops. 2137appropriate way for embedded loops.
2079 2138
2080=item struct ev_loop *other [read-only] 2139=item struct ev_loop *other [read-only]
2081 2140
2082The embedded event loop. 2141The embedded event loop.
2083 2142
… …
2085 2144
2086=head3 Examples 2145=head3 Examples
2087 2146
2088Example: 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
2089event 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
2090loop 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
2091C<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
2092used). 2151used).
2093 2152
2094 struct ev_loop *loop_hi = ev_default_init (0); 2153 struct ev_loop *loop_hi = ev_default_init (0);
2095 struct ev_loop *loop_lo = 0; 2154 struct ev_loop *loop_lo = 0;
2096 struct ev_embed embed; 2155 struct ev_embed embed;
… …
2190 2249
2191=item queueing from a signal handler context 2250=item queueing from a signal handler context
2192 2251
2193To 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
2194handler 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
2195some fictitiuous SIGUSR1 handler: 2254some fictitious SIGUSR1 handler:
2196 2255
2197 static ev_async mysig; 2256 static ev_async mysig;
2198 2257
2199 static void 2258 static void
2200 sigusr1_handler (void) 2259 sigusr1_handler (void)
… …
2274=item ev_async_send (loop, ev_async *) 2333=item ev_async_send (loop, ev_async *)
2275 2334
2276Sends/signals/activates the given C<ev_async> watcher, that is, feeds 2335Sends/signals/activates the given C<ev_async> watcher, that is, feeds
2277an 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
2278C<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
2279similar 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
2280section below on what exactly this means). 2339section below on what exactly this means).
2281 2340
2282This 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,
2283so 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
2284calls to C<ev_async_send>. 2343calls to C<ev_async_send>.
2285 2344
2286=item bool = ev_async_pending (ev_async *) 2345=item bool = ev_async_pending (ev_async *)
2287 2346
2288Returns 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
… …
2290event loop. 2349event loop.
2291 2350
2292C<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
2293the 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,
2294it 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
2295quickly check wether invoking the loop might be a good idea. 2354quickly check whether invoking the loop might be a good idea.
2296 2355
2297Not 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
2298wether it has been requested to make this watcher pending. 2357whether it has been requested to make this watcher pending.
2299 2358
2300=back 2359=back
2301 2360
2302 2361
2303=head1 OTHER FUNCTIONS 2362=head1 OTHER FUNCTIONS
… …
2314or timeout without having to allocate/configure/start/stop/free one or 2373or timeout without having to allocate/configure/start/stop/free one or
2315more watchers yourself. 2374more watchers yourself.
2316 2375
2317If 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
2318is 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
2319C<events> set will be craeted and started. 2378C<events> set will be created and started.
2320 2379
2321If 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
2322started. Otherwise an C<ev_timer> watcher with after = C<timeout> (and 2381started. Otherwise an C<ev_timer> watcher with after = C<timeout> (and
2323repeat = 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
2324dubious value. 2383dubious value.
… …
2349Feed 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
2350the given events it. 2409the given events it.
2351 2410
2352=item ev_feed_signal_event (ev_loop *loop, int signum) 2411=item ev_feed_signal_event (ev_loop *loop, int signum)
2353 2412
2354Feed 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
2355loop!). 2414loop!).
2356 2415
2357=back 2416=back
2358 2417
2359 2418
… …
2375 2434
2376=item * Priorities are not currently supported. Initialising priorities 2435=item * Priorities are not currently supported. Initialising priorities
2377will fail and all watchers will have the same priority, even though there 2436will fail and all watchers will have the same priority, even though there
2378is an ev_pri field. 2437is an ev_pri field.
2379 2438
2439=item * In libevent, the last base created gets the signals, in libev, the
2440first base created (== the default loop) gets the signals.
2441
2380=item * Other members are not supported. 2442=item * Other members are not supported.
2381 2443
2382=item * The libev emulation is I<not> ABI compatible to libevent, you need 2444=item * The libev emulation is I<not> ABI compatible to libevent, you need
2383to use the libev header file and library. 2445to use the libev header file and library.
2384 2446
2385=back 2447=back
2386 2448
2387=head1 C++ SUPPORT 2449=head1 C++ SUPPORT
2388 2450
2389Libev comes with some simplistic wrapper classes for C++ that mainly allow 2451Libev comes with some simplistic wrapper classes for C++ that mainly allow
2390you 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
2391the callback model to a model using method callbacks on objects. 2453the callback model to a model using method callbacks on objects.
2392 2454
2393To use it, 2455To use it,
2394 2456
2395 #include <ev++.h> 2457 #include <ev++.h>
… …
2496=item w->set (struct ev_loop *) 2558=item w->set (struct ev_loop *)
2497 2559
2498Associates 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
2499do this when the watcher is inactive (and not pending either). 2561do this when the watcher is inactive (and not pending either).
2500 2562
2501=item w->set ([args]) 2563=item w->set ([arguments])
2502 2564
2503Basically 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
2504called at least once. Unlike the C counterpart, an active watcher gets 2566called at least once. Unlike the C counterpart, an active watcher gets
2505automatically stopped and restarted when reconfiguring it with this 2567automatically stopped and restarted when reconfiguring it with this
2506method. 2568method.
2507 2569
2508=item w->start () 2570=item w->start ()
… …
2550 2612
2551 2613
2552=head1 OTHER LANGUAGE BINDINGS 2614=head1 OTHER LANGUAGE BINDINGS
2553 2615
2554Libev does not offer other language bindings itself, but bindings for a 2616Libev does not offer other language bindings itself, but bindings for a
2555numbe 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
2556any interesting language binding in addition to the ones listed here, drop 2618any interesting language binding in addition to the ones listed here, drop
2557me a note. 2619me a note.
2558 2620
2559=over 4 2621=over 4
2560 2622
… …
2570L<http://software.schmorp.de/pkg/EV>. 2632L<http://software.schmorp.de/pkg/EV>.
2571 2633
2572=item Ruby 2634=item Ruby
2573 2635
2574Tony 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
2575of the libev API and adds filehandle abstractions, asynchronous DNS and 2637of the libev API and adds file handle abstractions, asynchronous DNS and
2576more 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
2577L<http://rev.rubyforge.org/>. 2639L<http://rev.rubyforge.org/>.
2578 2640
2579=item D 2641=item D
2580 2642
… …
2584=back 2646=back
2585 2647
2586 2648
2587=head1 MACRO MAGIC 2649=head1 MACRO MAGIC
2588 2650
2589Libev can be compiled with a variety of options, the most fundamantal 2651Libev can be compiled with a variety of options, the most fundamental
2590of which is C<EV_MULTIPLICITY>. This option determines whether (most) 2652of which is C<EV_MULTIPLICITY>. This option determines whether (most)
2591functions and callbacks have an initial C<struct ev_loop *> argument. 2653functions and callbacks have an initial C<struct ev_loop *> argument.
2592 2654
2593To 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
2594following macros are defined: 2656following macros are defined:
… …
2668libev somewhere in your source tree). 2730libev somewhere in your source tree).
2669 2731
2670=head2 FILESETS 2732=head2 FILESETS
2671 2733
2672Depending 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
2673in your app. 2735in your application.
2674 2736
2675=head3 CORE EVENT LOOP 2737=head3 CORE EVENT LOOP
2676 2738
2677To 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
2678configuration (no autoconf): 2740configuration (no autoconf):
… …
2729 event.h 2791 event.h
2730 event.c 2792 event.c
2731 2793
2732=head3 AUTOCONF SUPPORT 2794=head3 AUTOCONF SUPPORT
2733 2795
2734Instead of using C<EV_STANDALONE=1> and providing your config in 2796Instead of using C<EV_STANDALONE=1> and providing your configuration in
2735whatever 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
2736F<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
2737include F<config.h> and configure itself accordingly. 2799include F<config.h> and configure itself accordingly.
2738 2800
2739For this of course you need the m4 file: 2801For this of course you need the m4 file:
… …
2741 libev.m4 2803 libev.m4
2742 2804
2743=head2 PREPROCESSOR SYMBOLS/MACROS 2805=head2 PREPROCESSOR SYMBOLS/MACROS
2744 2806
2745Libev 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
2746define 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
2747autoconf is noted for every option. 2809autoconf is noted for every option.
2748 2810
2749=over 4 2811=over 4
2750 2812
2751=item EV_STANDALONE 2813=item EV_STANDALONE
… …
2757F<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.
2758 2820
2759=item EV_USE_MONOTONIC 2821=item EV_USE_MONOTONIC
2760 2822
2761If 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
2762monotonic clock option at both compiletime and runtime. Otherwise no use 2824monotonic clock option at both compile time and runtime. Otherwise no use
2763of 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
2764usually have to link against librt or something similar. Enabling it when 2826usually have to link against librt or something similar. Enabling it when
2765the functionality isn't available is safe, though, although you have 2827the functionality isn't available is safe, though, although you have
2766to 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>
2767function is hiding in (often F<-lrt>). 2829function is hiding in (often F<-lrt>).
2768 2830
2769=item EV_USE_REALTIME 2831=item EV_USE_REALTIME
2770 2832
2771If 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
2772realtime clock option at compiletime (and assume its availability at 2834real-time clock option at compile time (and assume its availability at
2773runtime if successful). Otherwise no use of the realtime clock option will 2835runtime if successful). Otherwise no use of the real-time clock option will
2774be attempted. This effectively replaces C<gettimeofday> by C<clock_get 2836be attempted. This effectively replaces C<gettimeofday> by C<clock_get
2775(CLOCK_REALTIME, ...)> and will not normally affect correctness. See the 2837(CLOCK_REALTIME, ...)> and will not normally affect correctness. See the
2776note about libraries in the description of C<EV_USE_MONOTONIC>, though. 2838note about libraries in the description of C<EV_USE_MONOTONIC>, though.
2777 2839
2778=item EV_USE_NANOSLEEP 2840=item EV_USE_NANOSLEEP
… …
27892.7 or newer, otherwise disabled. 28512.7 or newer, otherwise disabled.
2790 2852
2791=item EV_USE_SELECT 2853=item EV_USE_SELECT
2792 2854
2793If 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
2794C<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
2795other method takes over, select will be it. Otherwise the select backend 2857other method takes over, select will be it. Otherwise the select backend
2796will not be compiled in. 2858will not be compiled in.
2797 2859
2798=item EV_SELECT_USE_FD_SET 2860=item EV_SELECT_USE_FD_SET
2799 2861
2800If 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>
2801structure. 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
2802C<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
2803exotic systems. This usually limits the range of file descriptors to some 2865exotic systems. This usually limits the range of file descriptors to some
2804low limit such as 1024 or might have other limitations (winsocket only 2866low limit such as 1024 or might have other limitations (winsocket only
2805allows 64 sockets). The C<FD_SETSIZE> macro, set before compilation, might 2867allows 64 sockets). The C<FD_SETSIZE> macro, set before compilation, might
2806influence the size of the C<fd_set> used. 2868influence the size of the C<fd_set> used.
2807 2869
… …
2856otherwise another method will be used as fallback. This is the preferred 2918otherwise another method will be used as fallback. This is the preferred
2857backend for Solaris 10 systems. 2919backend for Solaris 10 systems.
2858 2920
2859=item EV_USE_DEVPOLL 2921=item EV_USE_DEVPOLL
2860 2922
2861reserved for future expansion, works like the USE symbols above. 2923Reserved for future expansion, works like the USE symbols above.
2862 2924
2863=item EV_USE_INOTIFY 2925=item EV_USE_INOTIFY
2864 2926
2865If 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
2866interface to speed up C<ev_stat> watchers. Its actual availability will 2928interface to speed up C<ev_stat> watchers. Its actual availability will
… …
2873access 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
2874type 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
2875that 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"
2876as 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.
2877 2939
2878In 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>
2879(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.
2880 2942
2881=item EV_H 2943=item EV_H
2882 2944
2883The 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
… …
2922When doing priority-based operations, libev usually has to linearly search 2984When doing priority-based operations, libev usually has to linearly search
2923all 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
2924and 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
2925fine. 2987fine.
2926 2988
2927If 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
2928C<0> will save some memory and cpu. 2990C<0> will save some memory and CPU.
2929 2991
2930=item EV_PERIODIC_ENABLE 2992=item EV_PERIODIC_ENABLE
2931 2993
2932If 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
2933defined 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
… …
2960defined to be C<0>, then they are not. 3022defined to be C<0>, then they are not.
2961 3023
2962=item EV_MINIMAL 3024=item EV_MINIMAL
2963 3025
2964If 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
2965speed, 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
2966some 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.
2967 3030
2968=item EV_PID_HASHSIZE 3031=item EV_PID_HASHSIZE
2969 3032
2970C<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
2971pid. 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
… …
2977C<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
2978inotify 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>),
2979usually 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>
2980watchers 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
2981two). 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.>
2982 3080
2983=item EV_COMMON 3081=item EV_COMMON
2984 3082
2985By default, all watchers have a C<void *data> member. By redefining 3083By default, all watchers have a C<void *data> member. By redefining
2986this 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
… …
3006avoid 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
3007method calls instead of plain function calls in C++. 3105method calls instead of plain function calls in C++.
3008 3106
3009=head2 EXPORTED API SYMBOLS 3107=head2 EXPORTED API SYMBOLS
3010 3108
3011If 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
3012exported symbols, you can use the provided F<Symbol.*> files which list 3110exported symbols, you can use the provided F<Symbol.*> files which list
3013all public symbols, one per line: 3111all public symbols, one per line:
3014 3112
3015 Symbols.ev for libev proper 3113 Symbols.ev for libev proper
3016 Symbols.event for the libevent emulation 3114 Symbols.event for the libevent emulation
3017 3115
3018This 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
3019multiple versions of libev linked together (which is obviously bad in 3117multiple versions of libev linked together (which is obviously bad in
3020itself, but sometimes it is inconvinient to avoid this). 3118itself, but sometimes it is inconvenient to avoid this).
3021 3119
3022A 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
3023include before including F<ev.h>: 3121include before including F<ev.h>:
3024 3122
3025 <Symbols.ev sed -e "s/.*/#define & myprefix_&/" >wrap.h 3123 <Symbols.ev sed -e "s/.*/#define & myprefix_&/" >wrap.h
… …
3064 3162
3065=head1 THREADS AND COROUTINES 3163=head1 THREADS AND COROUTINES
3066 3164
3067=head2 THREADS 3165=head2 THREADS
3068 3166
3069Libev itself is completely threadsafe, but it uses no locking. This 3167Libev itself is completely thread-safe, but it uses no locking. This
3070means 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
3071only 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
3072parameter. 3170parameter.
3073 3171
3074Or put differently: calls with different loop parameters can be done in 3172Or put differently: calls with different loop parameters can be done in
… …
3081help you but by giving some generic advice: 3179help you but by giving some generic advice:
3082 3180
3083=over 4 3181=over 4
3084 3182
3085=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
3086in 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.
3087 3185
3088This helps integrating other libraries or software modules that use libev 3186This helps integrating other libraries or software modules that use libev
3089themselves and don't care/know about threading. 3187themselves and don't care/know about threading.
3090 3188
3091=item * one loop per thread is usually a good model. 3189=item * one loop per thread is usually a good model.
3092 3190
3093Doing this is almost never wrong, sometimes a better-performance model 3191Doing this is almost never wrong, sometimes a better-performance model
3094exists, but it is always a good start. 3192exists, but it is always a good start.
3095 3193
3096=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
3097loop 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.
3098 3196
3099Chosing 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
3100better than you currently do :-) 3198better than you currently do :-)
3101 3199
3102=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
3103event 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
3104threads safely (or from signal contexts...). 3202threads safely (or from signal contexts...).
3105 3203
3106=back 3204=back
3107 3205
3108=head2 COROUTINES 3206=head2 COROUTINES
3109 3207
3110Libev is much more accomodating to coroutines ("cooperative threads"): 3208Libev is much more accommodating to coroutines ("cooperative threads"):
3111libev fully supports nesting calls to it's functions from different 3209libev fully supports nesting calls to it's functions from different
3112coroutines (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
3113different coroutines and switch freely between both coroutines running the 3211different coroutines and switch freely between both coroutines running the
3114loop, 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
3115you must not do this from C<ev_periodic> reschedule callbacks. 3213you must not do this from C<ev_periodic> reschedule callbacks.
… …
3156correct 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
3157have many watchers waiting for the same fd or signal). 3255have many watchers waiting for the same fd or signal).
3158 3256
3159=item Finding the next timer in each loop iteration: O(1) 3257=item Finding the next timer in each loop iteration: O(1)
3160 3258
3161By 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
3162beginning of the storage array. 3260fixed position in the storage array.
3163 3261
3164=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)
3165 3263
3166A 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
3167libev to recalculate its status (and possibly tell the kernel, depending 3265libev to recalculate its status (and possibly tell the kernel, depending
3168on backend and wether C<ev_io_set> was used). 3266on backend and whether C<ev_io_set> was used).
3169 3267
3170=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)
3171 3269
3172=item Priority handling: O(number_of_priorities) 3270=item Priority handling: O(number_of_priorities)
3173 3271
… …
3180 3278
3181=item Processing ev_async_send: O(number_of_async_watchers) 3279=item Processing ev_async_send: O(number_of_async_watchers)
3182 3280
3183=item Processing signals: O(max_signal_number) 3281=item Processing signals: O(max_signal_number)
3184 3282
3185Sending 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>
3186calls in the current loop iteration. Checking for async and signal events 3284calls in the current loop iteration. Checking for async and signal events
3187involves iterating over all running async watchers or all signal numbers. 3285involves iterating over all running async watchers or all signal numbers.
3188 3286
3189=back 3287=back
3190 3288
… …
3196model. Libev still offers limited functionality on this platform in 3294model. Libev still offers limited functionality on this platform in
3197the form of the C<EVBACKEND_SELECT> backend, and only supports socket 3295the form of the C<EVBACKEND_SELECT> backend, and only supports socket
3198descriptors. This only applies when using Win32 natively, not when using 3296descriptors. This only applies when using Win32 natively, not when using
3199e.g. cygwin. 3297e.g. cygwin.
3200 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
3201There is no supported compilation method available on windows except 3304There is no supported compilation method available on windows except
3202embedding it into other applications. 3305embedding it into other applications.
3203 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
3204Due 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
3205abysmal performance of winsockets, using a large number of sockets is not 3315the abysmal performance of winsockets, using a large number of sockets
3206recommended (and not reasonable). If your program needs to use more than 3316is not recommended (and not reasonable). If your program needs to use
3207a 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
3208implementation for windows, as libev offers the POSIX model, which cannot 3318different implementation for windows, as libev offers the POSIX readiness
3209be implemented efficiently on windows (microsoft monopoly games). 3319notification model, which cannot be implemented efficiently on windows
3320(Microsoft monopoly games).
3210 3321
3211=over 4 3322=over 4
3212 3323
3213=item The winsocket select function 3324=item The winsocket select function
3214 3325
3215The winsocket C<select> function doesn't follow POSIX in that it requires 3326The winsocket C<select> function doesn't follow POSIX in that it
3216socket I<handles> and not socket I<file descriptors>. This makes select 3327requires socket I<handles> and not socket I<file descriptors> (it is
3217very inefficient, and also requires a mapping from file descriptors 3328also extremely buggy). This makes select very inefficient, and also
3218to socket handles. See the discussion of the C<EV_SELECT_USE_FD_SET>, 3329requires a mapping from file descriptors to socket handles. See the
3219C<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
3220symbols for more info. 3331C<EV_FD_TO_WIN32_HANDLE> preprocessor symbols for more info.
3221 3332
3222The configuration for a "naked" win32 using the microsoft runtime 3333The configuration for a "naked" win32 using the Microsoft runtime
3223libraries and raw winsocket select is: 3334libraries and raw winsocket select is:
3224 3335
3225 #define EV_USE_SELECT 1 3336 #define EV_USE_SELECT 1
3226 #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 */
3227 3338
3228Note 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
3229complexity in the O(n²) range when using win32. 3340complexity in the O(n²) range when using win32.
3230 3341
3231=item Limited number of file descriptors 3342=item Limited number of file descriptors
3232 3343
3233Windows has numerous arbitrary (and low) limits on things. Early versions 3344Windows has numerous arbitrary (and low) limits on things.
3234of 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
3235(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
3236C<64> things at the same time internally; microsoft recommends spawning a 3348can only wait for C<64> things at the same time internally; Microsoft
3237chain 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).
3238 3351
3239Newer 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>
3240to 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
3241call (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
3242select emulation on windows). 3355select emulation on windows).
3243 3356
3244Another limit is the number of file descriptors in the microsoft runtime 3357Another limit is the number of file descriptors in the Microsoft runtime
3245libraries, 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
3246or something like this inside microsoft). You can increase this by calling 3359or something like this inside Microsoft). You can increase this by calling
3247C<_setmaxstdio>, which can increase this limit to C<2048> (another 3360C<_setmaxstdio>, which can increase this limit to C<2048> (another
3248arbitrary limit), but is broken in many versions of the microsoft runtime 3361arbitrary limit), but is broken in many versions of the Microsoft runtime
3249libraries. 3362libraries.
3250 3363
3251This 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
3252windows 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
3253wrap 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
3254calling select (O(n²)) will likely make this unworkable. 3367calling select (O(n²)) will likely make this unworkable.
3255 3368
3256=back 3369=back
3257 3370
3258 3371
3372=head1 PORTABILITY REQUIREMENTS
3373
3374In addition to a working ISO-C implementation, libev relies on a few
3375additional extensions:
3376
3377=over 4
3378
3379=item C<sig_atomic_t volatile> must be thread-atomic as well
3380
3381The type C<sig_atomic_t volatile> (or whatever is defined as
3382C<EV_ATOMIC_T>) must be atomic w.r.t. accesses from different
3383threads. This is not part of the specification for C<sig_atomic_t>, but is
3384believed to be sufficiently portable.
3385
3386=item C<sigprocmask> must work in a threaded environment
3387
3388Libev uses C<sigprocmask> to temporarily block signals. This is not
3389allowed in a threaded program (C<pthread_sigmask> has to be used). Typical
3390pthread implementations will either allow C<sigprocmask> in the "main
3391thread" or will block signals process-wide, both behaviours would
3392be compatible with libev. Interaction between C<sigprocmask> and
3393C<pthread_sigmask> could complicate things, however.
3394
3395The most portable way to handle signals is to block signals in all threads
3396except the initial one, and run the default loop in the initial thread as
3397well.
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
3414=back
3415
3416If you know of other additional requirements drop me a note.
3417
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
3259=head1 AUTHOR 3471=head1 AUTHOR
3260 3472
3261Marc Lehmann <libev@schmorp.de>. 3473Marc Lehmann <libev@schmorp.de>.
3262 3474

Diff Legend

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