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

Comparing libev/ev.pod (file contents):
Revision 1.160 by root, Thu May 22 03:06:58 2008 UTC vs.
Revision 1.161 by root, Sat May 24 03:08:03 2008 UTC

… …
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 121
122=head1 ERROR HANDLING 122=head1 ERROR HANDLING
123 123
124Libev knows three classes of errors: operating system errors, usage errors 124Libev knows three classes of errors: operating system errors, usage errors
125and internal errors (bugs). 125and internal errors (bugs).
126 126
127When libev catches an operating system error it cannot handle (for example 127When libev catches an operating system error it cannot handle (for example
128a syscall indicating a condition libev cannot fix), it calls the callback 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 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 130abort. The default is to print a diagnostic message and to call C<abort
131()>. 131()>.
132 132
133When libev detects a usage error such as a negative timer interval, then 133When libev detects a usage error such as a negative timer interval, then
… …
155 155
156=item ev_sleep (ev_tstamp interval) 156=item ev_sleep (ev_tstamp interval)
157 157
158Sleep for the given interval: The current thread will be blocked until 158Sleep for the given interval: The current thread will be blocked until
159either it is interrupted or the given time interval has passed. Basically 159either it is interrupted or the given time interval has passed. Basically
160this is a subsecond-resolution C<sleep ()>. 160this is a sub-second-resolution C<sleep ()>.
161 161
162=item int ev_version_major () 162=item int ev_version_major ()
163 163
164=item int ev_version_minor () 164=item int ev_version_minor ()
165 165
… …
200=item unsigned int ev_recommended_backends () 200=item unsigned int ev_recommended_backends ()
201 201
202Return 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
203recommended for this platform. This set is often smaller than the one 203recommended for this platform. This set is often smaller than the one
204returned 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
205most BSDs and will not be autodetected unless you explicitly request it 205most BSDs and will not be auto-detected unless you explicitly request it
206(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
207libev will probe for if you specify no backends explicitly. 207libev will probe for if you specify no backends explicitly.
208 208
209=item unsigned int ev_embeddable_backends () 209=item unsigned int ev_embeddable_backends ()
210 210
… …
252 ... 252 ...
253 ev_set_allocator (persistent_realloc); 253 ev_set_allocator (persistent_realloc);
254 254
255=item ev_set_syserr_cb (void (*cb)(const char *msg)); 255=item ev_set_syserr_cb (void (*cb)(const char *msg));
256 256
257Set the callback function to call on a retryable syscall error (such 257Set the callback function to call on a retryable system call error (such
258as failed select, poll, epoll_wait). The message is a printable string 258as failed select, poll, epoll_wait). The message is a printable string
259indicating the system call or subsystem causing the problem. If this 259indicating the system call or subsystem causing the problem. If this
260callback 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
261matter what, when it returns. That is, libev will generally retry the 261matter what, when it returns. That is, libev will generally retry the
262requested 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
263(such as abort). 263(such as abort).
264 264
265Example: This is basically the same thing that libev does internally, too. 265Example: This is basically the same thing that libev does internally, too.
… …
298from 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,
299as loops cannot bes hared easily between threads anyway). 299as loops cannot bes hared easily between threads anyway).
300 300
301The 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
302C<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
303for 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
304create 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
305can simply overwrite the C<SIGCHLD> signal handler I<after> calling 305can simply overwrite the C<SIGCHLD> signal handler I<after> calling
306C<ev_default_init>. 306C<ev_default_init>.
307 307
308The flags argument can be used to specify special behaviour or specific 308The flags argument can be used to specify special behaviour or specific
… …
317The 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
318thing, believe me). 318thing, believe me).
319 319
320=item C<EVFLAG_NOENV> 320=item C<EVFLAG_NOENV>
321 321
322If 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
323or setgid) then libev will I<not> look at the environment variable 323or setgid) then libev will I<not> look at the environment variable
324C<LIBEV_FLAGS>. Otherwise (the default), this environment variable will 324C<LIBEV_FLAGS>. Otherwise (the default), this environment variable will
325override 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
326useful 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
327around bugs. 327around bugs.
… …
334 334
335This works by calling C<getpid ()> on every iteration of the loop, 335This works by calling C<getpid ()> on every iteration of the loop,
336and 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
337iterations and little real work, but is usually not noticeable (on my 337iterations and little real work, but is usually not noticeable (on my
338GNU/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
339without 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
340C<pthread_atfork> which is even faster). 340C<pthread_atfork> which is even faster).
341 341
342The 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
343forget about forgetting to tell libev about forking) when you use this 343forget about forgetting to tell libev about forking) when you use this
344flag. 344flag.
345 345
346This 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>
347environment variable. 347environment variable.
348 348
349=item C<EVBACKEND_SELECT> (value 1, portable select backend) 349=item C<EVBACKEND_SELECT> (value 1, portable select backend)
350 350
351This is your standard select(2) backend. Not I<completely> standard, as 351This is your standard select(2) backend. Not I<completely> standard, as
… …
353but 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
354using 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
355usually the fastest backend for a low number of (low-numbered :) fds. 355usually the fastest backend for a low number of (low-numbered :) fds.
356 356
357To 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
358parallelity (most of the file descriptors should be busy). If you are 358parallelism (most of the file descriptors should be busy). If you are
359writing 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
360connections as possible during one iteration. You might also want to have 360connections as possible during one iteration. You might also want to have
361a 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
362readiness notifications you get per iteration. 362readiness notifications you get per iteration.
363 363
… …
375For 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,
376but it scales phenomenally better. While poll and select usually scale 376but it scales phenomenally better. While poll and select usually scale
377like 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),
378epoll 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
379of shortcomings, such as silently dropping events in some hard-to-detect 379of shortcomings, such as silently dropping events in some hard-to-detect
380cases 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
381support for dup. 381support for dup.
382 382
383While 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
384will 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
385(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
386best 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
387very well if you register events for both fds. 387very well if you register events for both fds.
388 388
389Please note that epoll sometimes generates spurious notifications, so you 389Please note that epoll sometimes generates spurious notifications, so you
… …
392 392
393Best performance from this backend is achieved by not unregistering all 393Best performance from this backend is achieved by not unregistering all
394watchers 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.
395keep at least one watcher active per fd at all times. 395keep at least one watcher active per fd at all times.
396 396
397While nominally embeddeble in other event loops, this feature is broken in 397While nominally embeddable in other event loops, this feature is broken in
398all kernel versions tested so far. 398all kernel versions tested so far.
399 399
400=item C<EVBACKEND_KQUEUE> (value 8, most BSD clones) 400=item C<EVBACKEND_KQUEUE> (value 8, most BSD clones)
401 401
402Kqueue deserves special mention, as at the time of this writing, it 402Kqueue deserves special mention, as at the time of this writing, it
403was 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
404with anything but sockets and pipes, except on Darwin, where of course 404with anything but sockets and pipes, except on Darwin, where of course
405it's completely useless). For this reason it's not being "autodetected" 405it's completely useless). For this reason it's not being "auto-detected"
406unless you explicitly specify it explicitly in the flags (i.e. using 406unless you explicitly specify it explicitly in the flags (i.e. using
407C<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)
408system like NetBSD. 408system like NetBSD.
409 409
410You 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
… …
412the target platform). See C<ev_embed> watchers for more info. 412the target platform). See C<ev_embed> watchers for more info.
413 413
414It 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
415kernel is more efficient (which says nothing about its actual speed, of 415kernel is more efficient (which says nothing about its actual speed, of
416course). While stopping, setting and starting an I/O watcher does never 416course). While stopping, setting and starting an I/O watcher does never
417cause 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
418two 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
419drops fds silently in similarly hard-to-detect cases. 419drops fds silently in similarly hard-to-detect cases.
420 420
421This backend usually performs well under most conditions. 421This backend usually performs well under most conditions.
422 422
… …
437=item C<EVBACKEND_PORT> (value 32, Solaris 10) 437=item C<EVBACKEND_PORT> (value 32, Solaris 10)
438 438
439This 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,
440it'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)).
441 441
442Please note that solaris event ports can deliver a lot of spurious 442Please note that Solaris event ports can deliver a lot of spurious
443notifications, 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
444blocking when no data (or space) is available. 444blocking when no data (or space) is available.
445 445
446While this backend scales well, it requires one system call per active 446While this backend scales well, it requires one system call per active
447file descriptor per loop iteration. For small and medium numbers of file 447file descriptor per loop iteration. For small and medium numbers of file
… …
460 460
461It is definitely not recommended to use this flag. 461It is definitely not recommended to use this flag.
462 462
463=back 463=back
464 464
465If 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
466backends 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
467specified, all backends in C<ev_recommended_backends ()> will be tried. 467specified, all backends in C<ev_recommended_backends ()> will be tried.
468 468
469The most typical usage is like this: 469The most typical usage is like this:
470 470
… …
502=item ev_default_destroy () 502=item ev_default_destroy ()
503 503
504Destroys the default loop again (frees all memory and kernel state 504Destroys the default loop again (frees all memory and kernel state
505etc.). 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
506sense, 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
507responsibility to either stop all watchers cleanly yoursef I<before> 507responsibility to either stop all watchers cleanly yourself I<before>
508calling this function, or cope with the fact afterwards (which is usually 508calling this function, or cope with the fact afterwards (which is usually
509the 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
510for example). 510for example).
511 511
512Note 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
… …
593A 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
594those 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
595case 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.
596 596
597A 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
598neccessary) and will handle those and any outstanding ones. It will block 598necessary) and will handle those and any outstanding ones. It will block
599your 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
600one 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
601external event in conjunction with something not expressible using other 601external event in conjunction with something not expressible using other
602libev 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
603usually a better approach for this kind of thing. 603usually a better approach for this kind of thing.
… …
704to spend more time collecting timeouts, at the expense of increased 704to spend more time collecting timeouts, at the expense of increased
705latency (the watcher callback will be called later). C<ev_io> watchers 705latency (the watcher callback will be called later). C<ev_io> watchers
706will 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
707any overhead in libev. 707any overhead in libev.
708 708
709Many (busy) programs can usually benefit by setting the io collect 709Many (busy) programs can usually benefit by setting the I/O collect
710interval 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
711interactive servers (of course not for games), likewise for timeouts. It 711interactive servers (of course not for games), likewise for timeouts. It
712usually 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>,
713as this approsaches the timing granularity of most systems. 713as this approaches the timing granularity of most systems.
714 714
715=item ev_loop_verify (loop) 715=item ev_loop_verify (loop)
716 716
717This function only does something when C<EV_VERIFY> support has been 717This function only does something when C<EV_VERIFY> support has been
718compiled in. It tries to go through all internal structures and checks 718compiled in. It tries to go through all internal structures and checks
… …
749watcher 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,
750although this can sometimes be quite valid). 750although this can sometimes be quite valid).
751 751
752Each 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
753(watcher *, callback)>, which expects a callback to be provided. This 753(watcher *, callback)>, which expects a callback to be provided. This
754callback 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
755watchers, each time the event loop detects that the file descriptor given 755watchers, each time the event loop detects that the file descriptor given
756is readable and/or writable). 756is readable and/or writable).
757 757
758Each watcher type has its own C<< ev_<type>_set (watcher *, ...) >> macro 758Each watcher type has its own C<< ev_<type>_set (watcher *, ...) >> macro
759with arguments specific to this watcher type. There is also a macro 759with arguments specific to this watcher type. There is also a macro
… …
835 835
836The given async watcher has been asynchronously notified (see C<ev_async>). 836The given async watcher has been asynchronously notified (see C<ev_async>).
837 837
838=item C<EV_ERROR> 838=item C<EV_ERROR>
839 839
840An unspecified error has occured, the watcher has been stopped. This might 840An unspecified error has occurred, the watcher has been stopped. This might
841happen because the watcher could not be properly started because libev 841happen because the watcher could not be properly started because libev
842ran 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
843problem. 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
844with the watcher being stopped. 844with the watcher being stopped.
845 845
846Libev will usually signal a few "dummy" events together with an error, 846Libev will usually signal a few "dummy" events together with an error,
847for 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
848your 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
849with 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
850programs, though, so beware. 850programs, though, so beware.
851 851
852=back 852=back
853 853
854=head2 GENERIC WATCHER FUNCTIONS 854=head2 GENERIC WATCHER FUNCTIONS
… …
884Although some watcher types do not have type-specific arguments 884Although some watcher types do not have type-specific arguments
885(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.
886 886
887=item C<ev_TYPE_init> (ev_TYPE *watcher, callback, [args]) 887=item C<ev_TYPE_init> (ev_TYPE *watcher, callback, [args])
888 888
889This 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
890calls 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
891a watcher. The same limitations apply, of course. 891a watcher. The same limitations apply, of course.
892 892
893=item C<ev_TYPE_start> (loop *, ev_TYPE *watcher) 893=item C<ev_TYPE_start> (loop *, ev_TYPE *watcher)
894 894
895Starts (activates) the given watcher. Only active watchers will receive 895Starts (activates) the given watcher. Only active watchers will receive
… …
1067 1067
1068Another 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
1069receive "spurious" readiness notifications, that is your callback might 1069receive "spurious" readiness notifications, that is your callback might
1070be 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
1071because 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
1072lot 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
1073this situation even with a relatively standard program structure. Thus 1073this situation even with a relatively standard program structure. Thus
1074it 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
1075C<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.
1076 1076
1077If 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
1078play 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
1079whether 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
1080such 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
1081its own, so its quite safe to use). 1081its own, so its quite safe to use).
1082 1082
1083=head3 The special problem of disappearing file descriptors 1083=head3 The special problem of disappearing file descriptors
… …
1143=item ev_io_init (ev_io *, callback, int fd, int events) 1143=item ev_io_init (ev_io *, callback, int fd, int events)
1144 1144
1145=item ev_io_set (ev_io *, int fd, int events) 1145=item ev_io_set (ev_io *, int fd, int events)
1146 1146
1147Configures 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
1148rceeive 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
1149C<EV_READ | EV_WRITE> to receive the given events. 1149C<EV_READ | EV_WRITE> to receive the given events.
1150 1150
1151=item int fd [read-only] 1151=item int fd [read-only]
1152 1152
1153The file descriptor being watched. 1153The file descriptor being watched.
… …
1183 1183
1184Timer watchers are simple relative timers that generate an event after a 1184Timer watchers are simple relative timers that generate an event after a
1185given time, and optionally repeating in regular intervals after that. 1185given time, and optionally repeating in regular intervals after that.
1186 1186
1187The 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
1188times out after an hour and you reset your system clock to january last 1188times out after an hour and you reset your system clock to January last
1189year, it will still time out after (roughly) and hour. "Roughly" because 1189year, it will still time out after (roughly) and hour. "Roughly" because
1190detecting time jumps is hard, and some inaccuracies are unavoidable (the 1190detecting time jumps is hard, and some inaccuracies are unavoidable (the
1191monotonic clock option helps a lot here). 1191monotonic clock option helps a lot here).
1192 1192
1193The relative timeouts are calculated relative to the C<ev_now ()> 1193The relative timeouts are calculated relative to the C<ev_now ()>
… …
1196you 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
1197on the current time, use something like this to adjust for this: 1197on the current time, use something like this to adjust for this:
1198 1198
1199 ev_timer_set (&timer, after + ev_now () - ev_time (), 0.); 1199 ev_timer_set (&timer, after + ev_now () - ev_time (), 0.);
1200 1200
1201The callback is guarenteed to be invoked only after its timeout has passed, 1201The callback is guaranteed to be invoked only after its timeout has passed,
1202but if multiple timers become ready during the same loop iteration then 1202but if multiple timers become ready during the same loop iteration then
1203order of execution is undefined. 1203order of execution is undefined.
1204 1204
1205=head3 Watcher-Specific Functions and Data Members 1205=head3 Watcher-Specific Functions and Data Members
1206 1206
… …
1227This 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
1228repeating. The exact semantics are: 1228repeating. The exact semantics are:
1229 1229
1230If the timer is pending, its pending status is cleared. 1230If the timer is pending, its pending status is cleared.
1231 1231
1232If 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).
1233 1233
1234If the timer is repeating, either start it if necessary (with the 1234If the timer is repeating, either start it if necessary (with the
1235C<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.
1236 1236
1237This sounds a bit complicated, but here is a useful and typical 1237This sounds a bit complicated, but here is a useful and typical
1238example: 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
1239timeout, 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
1240seconds 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
1241configure 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
1242C<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
1243you 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
… …
1304 1304
1305Periodic 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
1306(and unfortunately a bit complex). 1306(and unfortunately a bit complex).
1307 1307
1308Unlike 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)
1309but on wallclock time (absolute time). You can tell a periodic watcher 1309but on wall clock time (absolute time). You can tell a periodic watcher
1310to trigger after 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
1311periodic 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 ()
1312+ 10.>, that is, an absolute time not a delay) and then reset your system 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 1313clock to January of the previous year, then it will take more than year
1314to trigger the event (unlike an C<ev_timer>, which would still trigger 1314to trigger the event (unlike an C<ev_timer>, which would still trigger
1315roughly 10 seconds later as it uses a relative timeout). 1315roughly 10 seconds later as it uses a relative timeout).
1316 1316
1317C<ev_periodic>s can also be used to implement vastly more complex timers, 1317C<ev_periodic>s can also be used to implement vastly more complex timers,
1318such as triggering an event on each "midnight, local time", or other 1318such as triggering an event on each "midnight, local time", or other
1319complicated, rules. 1319complicated, rules.
1320 1320
1321As 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
1322time (C<at>) has passed, but if multiple periodic timers become ready 1322time (C<at>) has passed, but if multiple periodic timers become ready
1323during the same loop iteration then order of execution is undefined. 1323during the same loop iteration then order of execution is undefined.
1324 1324
1325=head3 Watcher-Specific Functions and Data Members 1325=head3 Watcher-Specific Functions and Data Members
1326 1326
… …
1335 1335
1336=over 4 1336=over 4
1337 1337
1338=item * absolute timer (at = time, interval = reschedule_cb = 0) 1338=item * absolute timer (at = time, interval = reschedule_cb = 0)
1339 1339
1340In this configuration the watcher triggers an event after the wallclock 1340In this configuration the watcher triggers an event after the wall clock
1341time C<at> has passed and doesn't repeat. It will not adjust when a time 1341time C<at> has passed and doesn't repeat. It will not adjust when a time
1342jump occurs, that is, if it is to be run at January 1st 2011 then it will 1342jump occurs, that is, if it is to be run at January 1st 2011 then it will
1343run when the system time reaches or surpasses this time. 1343run when the system time reaches or surpasses this time.
1344 1344
1345=item * repeating interval timer (at = offset, interval > 0, reschedule_cb = 0) 1345=item * repeating interval timer (at = offset, interval > 0, reschedule_cb = 0)
… …
1353the hour: 1353the hour:
1354 1354
1355 ev_periodic_set (&periodic, 0., 3600., 0); 1355 ev_periodic_set (&periodic, 0., 3600., 0);
1356 1356
1357This 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,
1358but 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
1359full 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
1360by 3600. 1360by 3600.
1361 1361
1362Another way to think about it (for the mathematically inclined) is that 1362Another way to think about it (for the mathematically inclined) is that
1363C<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
… …
1365 1365
1366For 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
1367C<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
1368this value, and in fact is often specified as zero. 1368this value, and in fact is often specified as zero.
1369 1369
1370Note also that there is an upper limit to how often a timer can fire (cpu 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 1371speed for example), so if C<interval> is very small then timing stability
1372will of course detoriate. Libev itself tries to be exact to be about one 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). 1373millisecond (if the OS supports it and the machine is fast enough).
1374 1374
1375=item * manual reschedule mode (at and interval ignored, reschedule_cb = callback) 1375=item * manual reschedule mode (at and interval ignored, reschedule_cb = callback)
1376 1376
1377In 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
… …
1446 1446
1447=head3 Examples 1447=head3 Examples
1448 1448
1449Example: Call a callback every hour, or, more precisely, whenever the 1449Example: Call a callback every hour, or, more precisely, whenever the
1450system clock is divisible by 3600. The callback invocation times have 1450system clock is divisible by 3600. The callback invocation times have
1451potentially a lot of jittering, but good long-term stability. 1451potentially a lot of jitter, but good long-term stability.
1452 1452
1453 static void 1453 static void
1454 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)
1455 { 1455 {
1456 ... 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)
… …
1493as 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
1494watcher 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
1495SIG_DFL (regardless of what it was set to before). 1495SIG_DFL (regardless of what it was set to before).
1496 1496
1497If possible and supported, libev will install its handlers with 1497If possible and supported, libev will install its handlers with
1498C<SA_RESTART> behaviour enabled, so syscalls should not be unduly 1498C<SA_RESTART> behaviour enabled, so system calls should not be unduly
1499interrupted. If you have a problem with syscalls getting interrupted by 1499interrupted. If you have a problem with system calls getting interrupted by
1500signals 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
1501them in an C<ev_prepare> watcher. 1501them in an C<ev_prepare> watcher.
1502 1502
1503=head3 Watcher-Specific Functions and Data Members 1503=head3 Watcher-Specific Functions and Data Members
1504 1504
… …
1539is 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
1540forked (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
1541loop isn't entered (or is continued from a watcher). 1541loop isn't entered (or is continued from a watcher).
1542 1542
1543Only the default event loop is capable of handling signals, and therefore 1543Only the default event loop is capable of handling signals, and therefore
1544you can only rgeister child watchers in the default event loop. 1544you can only register child watchers in the default event loop.
1545 1545
1546=head3 Process Interaction 1546=head3 Process Interaction
1547 1547
1548Libev grabs C<SIGCHLD> as soon as the default event loop is 1548Libev grabs C<SIGCHLD> as soon as the default event loop is
1549initialised. This is necessary to guarantee proper behaviour even if 1549initialised. This is necessary to guarantee proper behaviour even if
1550the first child watcher is started after the child exits. The occurance 1550the first child watcher is started after the child exits. The occurrence
1551of C<SIGCHLD> is recorded asynchronously, but child reaping is done 1551of C<SIGCHLD> is recorded asynchronously, but child reaping is done
1552synchronously as part of the event loop processing. Libev always reaps all 1552synchronously as part of the event loop processing. Libev always reaps all
1553children, even ones not watched. 1553children, even ones not watched.
1554 1554
1555=head3 Overriding the Built-In Processing 1555=head3 Overriding the Built-In Processing
… …
1624 } 1624 }
1625 1625
1626 1626
1627=head2 C<ev_stat> - did the file attributes just change? 1627=head2 C<ev_stat> - did the file attributes just change?
1628 1628
1629This watches a filesystem path for attribute changes. That is, it calls 1629This watches a file system path for attribute changes. That is, it calls
1630C<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
1631compared to the last time, invoking the callback if it did. 1631compared to the last time, invoking the callback if it did.
1632 1632
1633The 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
1634not 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
… …
1668disabled 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
1669structure. When using the library from programs that change the ABI to 1669structure. When using the library from programs that change the ABI to
1670use 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
1671compile libev with the same flags to get binary compatibility. This is 1671compile libev with the same flags to get binary compatibility. This is
1672obviously 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
1673most noticably with ev_stat and largefile support. 1673most noticeably with ev_stat and large file support.
1674 1674
1675=head3 Inotify 1675=head3 Inotify
1676 1676
1677When C<inotify (7)> support has been compiled into libev (generally only 1677When C<inotify (7)> support has been compiled into libev (generally only
1678available 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
… …
1688implement this functionality, due to the requirement of having a file 1688implement this functionality, due to the requirement of having a file
1689descriptor open on the object at all times). 1689descriptor open on the object at all times).
1690 1690
1691=head3 The special problem of stat time resolution 1691=head3 The special problem of stat time resolution
1692 1692
1693The C<stat ()> syscall only supports full-second resolution portably, and 1693The C<stat ()> system call only supports full-second resolution portably, and
1694even on systems where the resolution is higher, many filesystems still 1694even on systems where the resolution is higher, many file systems still
1695only support whole seconds. 1695only support whole seconds.
1696 1696
1697That means that, if the time is the only thing that changes, you can 1697That means that, if the time is the only thing that changes, you can
1698easily miss updates: on the first update, C<ev_stat> detects a change and 1698easily miss updates: on the first update, C<ev_stat> detects a change and
1699calls your callback, which does something. When there is another update 1699calls your callback, which does something. When there is another update
… …
1759 1759
1760The specified interval. 1760The specified interval.
1761 1761
1762=item const char *path [read-only] 1762=item const char *path [read-only]
1763 1763
1764The filesystem path that is being watched. 1764The file system path that is being watched.
1765 1765
1766=back 1766=back
1767 1767
1768=head3 Examples 1768=head3 Examples
1769 1769
… …
1895 1895
1896This 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
1897to 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
1898them 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
1899provide just this functionality). Then, in the check watcher you check for 1899provide just this functionality). Then, in the check watcher you check for
1900any events that occured (by checking the pending status of all watchers 1900any events that occurred (by checking the pending status of all watchers
1901and 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
1902callbacks will never actually be called (but must be valid nevertheless, 1902callbacks will never actually be called (but must be valid nevertheless,
1903because you never know, you know?). 1903because you never know, you know?).
1904 1904
1905As another example, the Perl Coro module uses these hooks to integrate 1905As another example, the Perl Coro module uses these hooks to integrate
… …
2007 2007
2008Method 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>
2009in the prepare watcher and would dispose of the check watcher. 2009in the prepare watcher and would dispose of the check watcher.
2010 2010
2011Method 3: If the module to be embedded supports explicit event 2011Method 3: If the module to be embedded supports explicit event
2012notification (adns does), you can also make use of the actual watcher 2012notification (libadns does), you can also make use of the actual watcher
2013callbacks, and only destroy/create the watchers in the prepare watcher. 2013callbacks, and only destroy/create the watchers in the prepare watcher.
2014 2014
2015 static void 2015 static void
2016 timer_cb (EV_P_ ev_timer *w, int revents) 2016 timer_cb (EV_P_ ev_timer *w, int revents)
2017 { 2017 {
… …
2032 } 2032 }
2033 2033
2034 // do not ever call adns_afterpoll 2034 // do not ever call adns_afterpoll
2035 2035
2036Method 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
2037want 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
2038their poll function. The drawback with this solution is that the main 2038their poll function. The drawback with this solution is that the main
2039loop 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
2040this. 2040this.
2041 2041
2042 static gint 2042 static gint
… …
2126 2126
2127Configures the watcher to embed the given loop, which must be 2127Configures the watcher to embed the given loop, which must be
2128embeddable. 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
2129invoked automatically, otherwise it is the responsibility of the callback 2129invoked automatically, otherwise it is the responsibility of the callback
2130to 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,
2131if 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).
2132 2132
2133=item ev_embed_sweep (loop, ev_embed *) 2133=item ev_embed_sweep (loop, ev_embed *)
2134 2134
2135Make a single, non-blocking sweep over the embedded loop. This works 2135Make a single, non-blocking sweep over the embedded loop. This works
2136similarly 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
2137apropriate way for embedded loops. 2137appropriate way for embedded loops.
2138 2138
2139=item struct ev_loop *other [read-only] 2139=item struct ev_loop *other [read-only]
2140 2140
2141The embedded event loop. 2141The embedded event loop.
2142 2142
… …
2144 2144
2145=head3 Examples 2145=head3 Examples
2146 2146
2147Example: 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
2148event 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
2149loop 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
2150C<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
2151used). 2151used).
2152 2152
2153 struct ev_loop *loop_hi = ev_default_init (0); 2153 struct ev_loop *loop_hi = ev_default_init (0);
2154 struct ev_loop *loop_lo = 0; 2154 struct ev_loop *loop_lo = 0;
2155 struct ev_embed embed; 2155 struct ev_embed embed;
… …
2249 2249
2250=item queueing from a signal handler context 2250=item queueing from a signal handler context
2251 2251
2252To 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
2253handler 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
2254some fictitiuous SIGUSR1 handler: 2254some fictitious SIGUSR1 handler:
2255 2255
2256 static ev_async mysig; 2256 static ev_async mysig;
2257 2257
2258 static void 2258 static void
2259 sigusr1_handler (void) 2259 sigusr1_handler (void)
… …
2333=item ev_async_send (loop, ev_async *) 2333=item ev_async_send (loop, ev_async *)
2334 2334
2335Sends/signals/activates the given C<ev_async> watcher, that is, feeds 2335Sends/signals/activates the given C<ev_async> watcher, that is, feeds
2336an 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
2337C<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
2338similar 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
2339section below on what exactly this means). 2339section below on what exactly this means).
2340 2340
2341This 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,
2342so 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
2343calls to C<ev_async_send>. 2343calls to C<ev_async_send>.
2344 2344
2345=item bool = ev_async_pending (ev_async *) 2345=item bool = ev_async_pending (ev_async *)
2346 2346
2347Returns 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
… …
2349event loop. 2349event loop.
2350 2350
2351C<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
2352the 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,
2353it 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
2354quickly check wether invoking the loop might be a good idea. 2354quickly check whether invoking the loop might be a good idea.
2355 2355
2356Not 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
2357wether it has been requested to make this watcher pending. 2357whether it has been requested to make this watcher pending.
2358 2358
2359=back 2359=back
2360 2360
2361 2361
2362=head1 OTHER FUNCTIONS 2362=head1 OTHER FUNCTIONS
… …
2373or timeout without having to allocate/configure/start/stop/free one or 2373or timeout without having to allocate/configure/start/stop/free one or
2374more watchers yourself. 2374more watchers yourself.
2375 2375
2376If 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
2377is 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
2378C<events> set will be craeted and started. 2378C<events> set will be created and started.
2379 2379
2380If 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
2381started. Otherwise an C<ev_timer> watcher with after = C<timeout> (and 2381started. Otherwise an C<ev_timer> watcher with after = C<timeout> (and
2382repeat = 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
2383dubious value. 2383dubious value.
… …
2408Feed 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
2409the given events it. 2409the given events it.
2410 2410
2411=item ev_feed_signal_event (ev_loop *loop, int signum) 2411=item ev_feed_signal_event (ev_loop *loop, int signum)
2412 2412
2413Feed 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
2414loop!). 2414loop!).
2415 2415
2416=back 2416=back
2417 2417
2418 2418
… …
2447=back 2447=back
2448 2448
2449=head1 C++ SUPPORT 2449=head1 C++ SUPPORT
2450 2450
2451Libev comes with some simplistic wrapper classes for C++ that mainly allow 2451Libev comes with some simplistic wrapper classes for C++ that mainly allow
2452you 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
2453the callback model to a model using method callbacks on objects. 2453the callback model to a model using method callbacks on objects.
2454 2454
2455To use it, 2455To use it,
2456 2456
2457 #include <ev++.h> 2457 #include <ev++.h>
… …
2558=item w->set (struct ev_loop *) 2558=item w->set (struct ev_loop *)
2559 2559
2560Associates 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
2561do this when the watcher is inactive (and not pending either). 2561do this when the watcher is inactive (and not pending either).
2562 2562
2563=item w->set ([args]) 2563=item w->set ([arguments])
2564 2564
2565Basically 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
2566called at least once. Unlike the C counterpart, an active watcher gets 2566called at least once. Unlike the C counterpart, an active watcher gets
2567automatically stopped and restarted when reconfiguring it with this 2567automatically stopped and restarted when reconfiguring it with this
2568method. 2568method.
2569 2569
2570=item w->start () 2570=item w->start ()
… …
2612 2612
2613 2613
2614=head1 OTHER LANGUAGE BINDINGS 2614=head1 OTHER LANGUAGE BINDINGS
2615 2615
2616Libev does not offer other language bindings itself, but bindings for a 2616Libev does not offer other language bindings itself, but bindings for a
2617numbe 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
2618any interesting language binding in addition to the ones listed here, drop 2618any interesting language binding in addition to the ones listed here, drop
2619me a note. 2619me a note.
2620 2620
2621=over 4 2621=over 4
2622 2622
… …
2632L<http://software.schmorp.de/pkg/EV>. 2632L<http://software.schmorp.de/pkg/EV>.
2633 2633
2634=item Ruby 2634=item Ruby
2635 2635
2636Tony 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
2637of the libev API and adds filehandle abstractions, asynchronous DNS and 2637of the libev API and adds file handle abstractions, asynchronous DNS and
2638more 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
2639L<http://rev.rubyforge.org/>. 2639L<http://rev.rubyforge.org/>.
2640 2640
2641=item D 2641=item D
2642 2642
… …
2646=back 2646=back
2647 2647
2648 2648
2649=head1 MACRO MAGIC 2649=head1 MACRO MAGIC
2650 2650
2651Libev can be compiled with a variety of options, the most fundamantal 2651Libev can be compiled with a variety of options, the most fundamental
2652of which is C<EV_MULTIPLICITY>. This option determines whether (most) 2652of which is C<EV_MULTIPLICITY>. This option determines whether (most)
2653functions and callbacks have an initial C<struct ev_loop *> argument. 2653functions and callbacks have an initial C<struct ev_loop *> argument.
2654 2654
2655To 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
2656following macros are defined: 2656following macros are defined:
… …
2730libev somewhere in your source tree). 2730libev somewhere in your source tree).
2731 2731
2732=head2 FILESETS 2732=head2 FILESETS
2733 2733
2734Depending 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
2735in your app. 2735in your application.
2736 2736
2737=head3 CORE EVENT LOOP 2737=head3 CORE EVENT LOOP
2738 2738
2739To 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
2740configuration (no autoconf): 2740configuration (no autoconf):
… …
2791 event.h 2791 event.h
2792 event.c 2792 event.c
2793 2793
2794=head3 AUTOCONF SUPPORT 2794=head3 AUTOCONF SUPPORT
2795 2795
2796Instead of using C<EV_STANDALONE=1> and providing your config in 2796Instead of using C<EV_STANDALONE=1> and providing your configuration in
2797whatever 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
2798F<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
2799include F<config.h> and configure itself accordingly. 2799include F<config.h> and configure itself accordingly.
2800 2800
2801For this of course you need the m4 file: 2801For this of course you need the m4 file:
… …
2803 libev.m4 2803 libev.m4
2804 2804
2805=head2 PREPROCESSOR SYMBOLS/MACROS 2805=head2 PREPROCESSOR SYMBOLS/MACROS
2806 2806
2807Libev 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
2808define 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
2809autoconf is noted for every option. 2809autoconf is noted for every option.
2810 2810
2811=over 4 2811=over 4
2812 2812
2813=item EV_STANDALONE 2813=item EV_STANDALONE
… …
2819F<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.
2820 2820
2821=item EV_USE_MONOTONIC 2821=item EV_USE_MONOTONIC
2822 2822
2823If 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
2824monotonic clock option at both compiletime and runtime. Otherwise no use 2824monotonic clock option at both compile time and runtime. Otherwise no use
2825of 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
2826usually have to link against librt or something similar. Enabling it when 2826usually have to link against librt or something similar. Enabling it when
2827the functionality isn't available is safe, though, although you have 2827the functionality isn't available is safe, though, although you have
2828to 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>
2829function is hiding in (often F<-lrt>). 2829function is hiding in (often F<-lrt>).
2830 2830
2831=item EV_USE_REALTIME 2831=item EV_USE_REALTIME
2832 2832
2833If 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
2834realtime clock option at compiletime (and assume its availability at 2834real-time clock option at compile time (and assume its availability at
2835runtime if successful). Otherwise no use of the realtime clock option will 2835runtime if successful). Otherwise no use of the real-time clock option will
2836be attempted. This effectively replaces C<gettimeofday> by C<clock_get 2836be attempted. This effectively replaces C<gettimeofday> by C<clock_get
2837(CLOCK_REALTIME, ...)> and will not normally affect correctness. See the 2837(CLOCK_REALTIME, ...)> and will not normally affect correctness. See the
2838note about libraries in the description of C<EV_USE_MONOTONIC>, though. 2838note about libraries in the description of C<EV_USE_MONOTONIC>, though.
2839 2839
2840=item EV_USE_NANOSLEEP 2840=item EV_USE_NANOSLEEP
… …
28512.7 or newer, otherwise disabled. 28512.7 or newer, otherwise disabled.
2852 2852
2853=item EV_USE_SELECT 2853=item EV_USE_SELECT
2854 2854
2855If 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
2856C<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
2857other method takes over, select will be it. Otherwise the select backend 2857other method takes over, select will be it. Otherwise the select backend
2858will not be compiled in. 2858will not be compiled in.
2859 2859
2860=item EV_SELECT_USE_FD_SET 2860=item EV_SELECT_USE_FD_SET
2861 2861
2862If 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>
2863structure. 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
2864C<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
2865exotic systems. This usually limits the range of file descriptors to some 2865exotic systems. This usually limits the range of file descriptors to some
2866low limit such as 1024 or might have other limitations (winsocket only 2866low limit such as 1024 or might have other limitations (winsocket only
2867allows 64 sockets). The C<FD_SETSIZE> macro, set before compilation, might 2867allows 64 sockets). The C<FD_SETSIZE> macro, set before compilation, might
2868influence the size of the C<fd_set> used. 2868influence the size of the C<fd_set> used.
2869 2869
… …
2918otherwise another method will be used as fallback. This is the preferred 2918otherwise another method will be used as fallback. This is the preferred
2919backend for Solaris 10 systems. 2919backend for Solaris 10 systems.
2920 2920
2921=item EV_USE_DEVPOLL 2921=item EV_USE_DEVPOLL
2922 2922
2923reserved for future expansion, works like the USE symbols above. 2923Reserved for future expansion, works like the USE symbols above.
2924 2924
2925=item EV_USE_INOTIFY 2925=item EV_USE_INOTIFY
2926 2926
2927If 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
2928interface to speed up C<ev_stat> watchers. Its actual availability will 2928interface to speed up C<ev_stat> watchers. Its actual availability will
… …
2935access 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
2936type 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
2937that 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"
2938as 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.
2939 2939
2940In 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>
2941(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.
2942 2942
2943=item EV_H 2943=item EV_H
2944 2944
2945The 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
… …
2984When doing priority-based operations, libev usually has to linearly search 2984When doing priority-based operations, libev usually has to linearly search
2985all 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
2986and 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
2987fine. 2987fine.
2988 2988
2989If 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
2990C<0> will save some memory and cpu. 2990C<0> will save some memory and CPU.
2991 2991
2992=item EV_PERIODIC_ENABLE 2992=item EV_PERIODIC_ENABLE
2993 2993
2994If 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
2995defined 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
… …
3023 3023
3024=item EV_MINIMAL 3024=item EV_MINIMAL
3025 3025
3026If 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
3027speed, define this symbol to C<1>. Currently this is used to override some 3027speed, define this symbol to C<1>. Currently this is used to override some
3028inlining decisions, saves roughly 30% codesize of amd64. It also selects a 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. 3029much smaller 2-heap for timer management over the default 4-heap.
3030 3030
3031=item EV_PID_HASHSIZE 3031=item EV_PID_HASHSIZE
3032 3032
3033C<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
… …
3046=item EV_USE_4HEAP 3046=item EV_USE_4HEAP
3047 3047
3048Heaps are not very cache-efficient. To improve the cache-efficiency of the 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 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 3050to C<1>. The 4-heap uses more complicated (longer) code but has
3051noticably faster performance with many (thousands) of watchers. 3051noticeably faster performance with many (thousands) of watchers.
3052 3052
3053The default is C<1> unless C<EV_MINIMAL> is set in which case it is C<0> 3053The default is C<1> unless C<EV_MINIMAL> is set in which case it is C<0>
3054(disabled). 3054(disabled).
3055 3055
3056=item EV_HEAP_CACHE_AT 3056=item EV_HEAP_CACHE_AT
… …
3058Heaps are not very cache-efficient. To improve the cache-efficiency of the 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 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>), 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, 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 3062but avoids random read accesses on heap changes. This improves performance
3063noticably with with many (hundreds) of watchers. 3063noticeably with with many (hundreds) of watchers.
3064 3064
3065The default is C<1> unless C<EV_MINIMAL> is set in which case it is C<0> 3065The default is C<1> unless C<EV_MINIMAL> is set in which case it is C<0>
3066(disabled). 3066(disabled).
3067 3067
3068=item EV_VERIFY 3068=item EV_VERIFY
… …
3104avoid 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
3105method calls instead of plain function calls in C++. 3105method calls instead of plain function calls in C++.
3106 3106
3107=head2 EXPORTED API SYMBOLS 3107=head2 EXPORTED API SYMBOLS
3108 3108
3109If 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
3110exported symbols, you can use the provided F<Symbol.*> files which list 3110exported symbols, you can use the provided F<Symbol.*> files which list
3111all public symbols, one per line: 3111all public symbols, one per line:
3112 3112
3113 Symbols.ev for libev proper 3113 Symbols.ev for libev proper
3114 Symbols.event for the libevent emulation 3114 Symbols.event for the libevent emulation
3115 3115
3116This 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
3117multiple versions of libev linked together (which is obviously bad in 3117multiple versions of libev linked together (which is obviously bad in
3118itself, but sometimes it is inconvinient to avoid this). 3118itself, but sometimes it is inconvenient to avoid this).
3119 3119
3120A 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
3121include before including F<ev.h>: 3121include before including F<ev.h>:
3122 3122
3123 <Symbols.ev sed -e "s/.*/#define & myprefix_&/" >wrap.h 3123 <Symbols.ev sed -e "s/.*/#define & myprefix_&/" >wrap.h
… …
3162 3162
3163=head1 THREADS AND COROUTINES 3163=head1 THREADS AND COROUTINES
3164 3164
3165=head2 THREADS 3165=head2 THREADS
3166 3166
3167Libev itself is completely threadsafe, but it uses no locking. This 3167Libev itself is completely thread-safe, but it uses no locking. This
3168means 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
3169only 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
3170parameter. 3170parameter.
3171 3171
3172Or put differently: calls with different loop parameters can be done in 3172Or put differently: calls with different loop parameters can be done in
… …
3179help you but by giving some generic advice: 3179help you but by giving some generic advice:
3180 3180
3181=over 4 3181=over 4
3182 3182
3183=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
3184in 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.
3185 3185
3186This helps integrating other libraries or software modules that use libev 3186This helps integrating other libraries or software modules that use libev
3187themselves and don't care/know about threading. 3187themselves and don't care/know about threading.
3188 3188
3189=item * one loop per thread is usually a good model. 3189=item * one loop per thread is usually a good model.
3190 3190
3191Doing this is almost never wrong, sometimes a better-performance model 3191Doing this is almost never wrong, sometimes a better-performance model
3192exists, but it is always a good start. 3192exists, but it is always a good start.
3193 3193
3194=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
3195loop 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.
3196 3196
3197Chosing 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
3198better than you currently do :-) 3198better than you currently do :-)
3199 3199
3200=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
3201event 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
3202threads safely (or from signal contexts...). 3202threads safely (or from signal contexts...).
3203 3203
3204=back 3204=back
3205 3205
3206=head2 COROUTINES 3206=head2 COROUTINES
3207 3207
3208Libev is much more accomodating to coroutines ("cooperative threads"): 3208Libev is much more accommodating to coroutines ("cooperative threads"):
3209libev fully supports nesting calls to it's functions from different 3209libev fully supports nesting calls to it's functions from different
3210coroutines (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
3211different coroutines and switch freely between both coroutines running the 3211different coroutines and switch freely between both coroutines running the
3212loop, 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
3213you must not do this from C<ev_periodic> reschedule callbacks. 3213you must not do this from C<ev_periodic> reschedule callbacks.
… …
3261 3261
3262=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)
3263 3263
3264A 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
3265libev to recalculate its status (and possibly tell the kernel, depending 3265libev to recalculate its status (and possibly tell the kernel, depending
3266on backend and wether C<ev_io_set> was used). 3266on backend and whether C<ev_io_set> was used).
3267 3267
3268=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)
3269 3269
3270=item Priority handling: O(number_of_priorities) 3270=item Priority handling: O(number_of_priorities)
3271 3271
… …
3278 3278
3279=item Processing ev_async_send: O(number_of_async_watchers) 3279=item Processing ev_async_send: O(number_of_async_watchers)
3280 3280
3281=item Processing signals: O(max_signal_number) 3281=item Processing signals: O(max_signal_number)
3282 3282
3283Sending 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>
3284calls in the current loop iteration. Checking for async and signal events 3284calls in the current loop iteration. Checking for async and signal events
3285involves iterating over all running async watchers or all signal numbers. 3285involves iterating over all running async watchers or all signal numbers.
3286 3286
3287=back 3287=back
3288 3288
… …
3308the abysmal performance of winsockets, using a large number of sockets 3308the abysmal performance of winsockets, using a large number of sockets
3309is not recommended (and not reasonable). If your program needs to use 3309is not recommended (and not reasonable). If your program needs to use
3310more than a hundred or so sockets, then likely it needs to use a totally 3310more than a hundred or so sockets, then likely it needs to use a totally
3311different implementation for windows, as libev offers the POSIX readiness 3311different implementation for windows, as libev offers the POSIX readiness
3312notification model, which cannot be implemented efficiently on windows 3312notification model, which cannot be implemented efficiently on windows
3313(microsoft monopoly games). 3313(Microsoft monopoly games).
3314 3314
3315=over 4 3315=over 4
3316 3316
3317=item The winsocket select function 3317=item The winsocket select function
3318 3318
… …
3321also extremely buggy). This makes select very inefficient, and also 3321also extremely buggy). This makes select very inefficient, and also
3322requires a mapping from file descriptors to socket handles. See the 3322requires a mapping from file descriptors to socket handles. See the
3323discussion of the C<EV_SELECT_USE_FD_SET>, C<EV_SELECT_IS_WINSOCKET> and 3323discussion of the C<EV_SELECT_USE_FD_SET>, C<EV_SELECT_IS_WINSOCKET> and
3324C<EV_FD_TO_WIN32_HANDLE> preprocessor symbols for more info. 3324C<EV_FD_TO_WIN32_HANDLE> preprocessor symbols for more info.
3325 3325
3326The configuration for a "naked" win32 using the microsoft runtime 3326The configuration for a "naked" win32 using the Microsoft runtime
3327libraries and raw winsocket select is: 3327libraries and raw winsocket select is:
3328 3328
3329 #define EV_USE_SELECT 1 3329 #define EV_USE_SELECT 1
3330 #define EV_SELECT_IS_WINSOCKET 1 /* forces EV_SELECT_USE_FD_SET, too */ 3330 #define EV_SELECT_IS_WINSOCKET 1 /* forces EV_SELECT_USE_FD_SET, too */
3331 3331
… …
3336 3336
3337Windows has numerous arbitrary (and low) limits on things. 3337Windows has numerous arbitrary (and low) limits on things.
3338 3338
3339Early versions of winsocket's select only supported waiting for a maximum 3339Early versions of winsocket's select only supported waiting for a maximum
3340of C<64> handles (probably owning to the fact that all windows kernels 3340of C<64> handles (probably owning to the fact that all windows kernels
3341can only wait for C<64> things at the same time internally; microsoft 3341can only wait for C<64> things at the same time internally; Microsoft
3342recommends spawning a chain of threads and wait for 63 handles and the 3342recommends spawning a chain of threads and wait for 63 handles and the
3343previous thread in each. Great). 3343previous thread in each. Great).
3344 3344
3345Newer versions support more handles, but you need to define C<FD_SETSIZE> 3345Newer versions support more handles, but you need to define C<FD_SETSIZE>
3346to some high number (e.g. C<2048>) before compiling the winsocket select 3346to some high number (e.g. C<2048>) before compiling the winsocket select
3347call (which might be in libev or elsewhere, for example, perl does its own 3347call (which might be in libev or elsewhere, for example, perl does its own
3348select emulation on windows). 3348select emulation on windows).
3349 3349
3350Another limit is the number of file descriptors in the microsoft runtime 3350Another limit is the number of file descriptors in the Microsoft runtime
3351libraries, which by default is C<64> (there must be a hidden I<64> fetish 3351libraries, which by default is C<64> (there must be a hidden I<64> fetish
3352or something like this inside microsoft). You can increase this by calling 3352or something like this inside Microsoft). You can increase this by calling
3353C<_setmaxstdio>, which can increase this limit to C<2048> (another 3353C<_setmaxstdio>, which can increase this limit to C<2048> (another
3354arbitrary limit), but is broken in many versions of the microsoft runtime 3354arbitrary limit), but is broken in many versions of the Microsoft runtime
3355libraries. 3355libraries.
3356 3356
3357This might get you to about C<512> or C<2048> sockets (depending on 3357This might get you to about C<512> or C<2048> sockets (depending on
3358windows version and/or the phase of the moon). To get more, you need to 3358windows version and/or the phase of the moon). To get more, you need to
3359wrap all I/O functions and provide your own fd management, but the cost of 3359wrap all I/O functions and provide your own fd management, but the cost of
… …
3416scared by this. 3416scared by this.
3417 3417
3418However, these are unavoidable for many reasons. For one, each compiler 3418However, these are unavoidable for many reasons. For one, each compiler
3419has different warnings, and each user has different tastes regarding 3419has different warnings, and each user has different tastes regarding
3420warning options. "Warn-free" code therefore cannot be a goal except when 3420warning options. "Warn-free" code therefore cannot be a goal except when
3421targetting a specific compiler and compiler-version. 3421targeting a specific compiler and compiler-version.
3422 3422
3423Another reason is that some compiler warnings require elaborate 3423Another reason is that some compiler warnings require elaborate
3424workarounds, or other changes to the code that make it less clear and less 3424workarounds, or other changes to the code that make it less clear and less
3425maintainable. 3425maintainable.
3426 3426
3427And of course, some compiler warnings are just plain stupid, or simply 3427And of course, some compiler warnings are just plain stupid, or simply
3428wrong (because they don't actually warn about the cindition their message 3428wrong (because they don't actually warn about the condition their message
3429seems to warn about). 3429seems to warn about).
3430 3430
3431While libev is written to generate as few warnings as possible, 3431While libev is written to generate as few warnings as possible,
3432"warn-free" code is not a goal, and it is recommended not to build libev 3432"warn-free" code is not a goal, and it is recommended not to build libev
3433with any compiler warnings enabled unless you are prepared to cope with 3433with any compiler warnings enabled unless you are prepared to cope with
… …
3445 3445
3446 ==2274== definitely lost: 0 bytes in 0 blocks. 3446 ==2274== definitely lost: 0 bytes in 0 blocks.
3447 ==2274== possibly lost: 0 bytes in 0 blocks. 3447 ==2274== possibly lost: 0 bytes in 0 blocks.
3448 ==2274== still reachable: 256 bytes in 1 blocks. 3448 ==2274== still reachable: 256 bytes in 1 blocks.
3449 3449
3450then there is no memory leak. Similarly, under some circumstances, 3450Then there is no memory leak. Similarly, under some circumstances,
3451valgrind might report kernel bugs as if it were a bug in libev, or it 3451valgrind might report kernel bugs as if it were a bug in libev, or it
3452might be confused (it is a very good tool, but only a tool). 3452might be confused (it is a very good tool, but only a tool).
3453 3453
3454If you are unsure about something, feel free to contact the mailing list 3454If you are unsure about something, feel free to contact the mailing list
3455with the full valgrind report and an explanation on why you think this is 3455with the full valgrind report and an explanation on why you think this is

Diff Legend

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