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

Comparing libev/ev.pod (file contents):
Revision 1.231 by root, Wed Apr 15 19:35:53 2009 UTC vs.
Revision 1.292 by sf-exg, Mon Mar 22 09:57:01 2010 UTC

62 62
63 // unloop was called, so exit 63 // unloop was called, so exit
64 return 0; 64 return 0;
65 } 65 }
66 66
67=head1 DESCRIPTION 67=head1 ABOUT THIS DOCUMENT
68
69This document documents the libev software package.
68 70
69The newest version of this document is also available as an html-formatted 71The newest version of this document is also available as an html-formatted
70web page you might find easier to navigate when reading it for the first 72web page you might find easier to navigate when reading it for the first
71time: L<http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod>. 73time: L<http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod>.
74
75While this document tries to be as complete as possible in documenting
76libev, its usage and the rationale behind its design, it is not a tutorial
77on event-based programming, nor will it introduce event-based programming
78with libev.
79
80Familarity with event based programming techniques in general is assumed
81throughout this document.
82
83=head1 ABOUT LIBEV
72 84
73Libev is an event loop: you register interest in certain events (such as a 85Libev is an event loop: you register interest in certain events (such as a
74file descriptor being readable or a timeout occurring), and it will manage 86file descriptor being readable or a timeout occurring), and it will manage
75these event sources and provide your program with events. 87these event sources and provide your program with events.
76 88
86=head2 FEATURES 98=head2 FEATURES
87 99
88Libev supports C<select>, C<poll>, the Linux-specific C<epoll>, the 100Libev supports C<select>, C<poll>, the Linux-specific C<epoll>, the
89BSD-specific C<kqueue> and the Solaris-specific event port mechanisms 101BSD-specific C<kqueue> and the Solaris-specific event port mechanisms
90for file descriptor events (C<ev_io>), the Linux C<inotify> interface 102for file descriptor events (C<ev_io>), the Linux C<inotify> interface
91(for C<ev_stat>), relative timers (C<ev_timer>), absolute timers 103(for C<ev_stat>), Linux eventfd/signalfd (for faster and cleaner
92with customised rescheduling (C<ev_periodic>), synchronous signals 104inter-thread wakeup (C<ev_async>)/signal handling (C<ev_signal>)) relative
93(C<ev_signal>), process status change events (C<ev_child>), and event 105timers (C<ev_timer>), absolute timers with customised rescheduling
94watchers dealing with the event loop mechanism itself (C<ev_idle>, 106(C<ev_periodic>), synchronous signals (C<ev_signal>), process status
95C<ev_embed>, C<ev_prepare> and C<ev_check> watchers) as well as 107change events (C<ev_child>), and event watchers dealing with the event
96file watchers (C<ev_stat>) and even limited support for fork events 108loop mechanism itself (C<ev_idle>, C<ev_embed>, C<ev_prepare> and
97(C<ev_fork>). 109C<ev_check> watchers) as well as file watchers (C<ev_stat>) and even
110limited support for fork events (C<ev_fork>).
98 111
99It also is quite fast (see this 112It also is quite fast (see this
100L<benchmark|http://libev.schmorp.de/bench.html> comparing it to libevent 113L<benchmark|http://libev.schmorp.de/bench.html> comparing it to libevent
101for example). 114for example).
102 115
105Libev is very configurable. In this manual the default (and most common) 118Libev is very configurable. In this manual the default (and most common)
106configuration will be described, which supports multiple event loops. For 119configuration will be described, which supports multiple event loops. For
107more info about various configuration options please have a look at 120more info about various configuration options please have a look at
108B<EMBED> section in this manual. If libev was configured without support 121B<EMBED> section in this manual. If libev was configured without support
109for multiple event loops, then all functions taking an initial argument of 122for multiple event loops, then all functions taking an initial argument of
110name C<loop> (which is always of type C<ev_loop *>) will not have 123name C<loop> (which is always of type C<struct ev_loop *>) will not have
111this argument. 124this argument.
112 125
113=head2 TIME REPRESENTATION 126=head2 TIME REPRESENTATION
114 127
115Libev represents time as a single floating point number, representing the 128Libev represents time as a single floating point number, representing
116(fractional) number of seconds since the (POSIX) epoch (somewhere near 129the (fractional) number of seconds since the (POSIX) epoch (somewhere
117the beginning of 1970, details are complicated, don't ask). This type is 130near the beginning of 1970, details are complicated, don't ask). This
118called C<ev_tstamp>, which is what you should use too. It usually aliases 131type is called C<ev_tstamp>, which is what you should use too. It usually
119to the C<double> type in C, and when you need to do any calculations on 132aliases to the C<double> type in C. When you need to do any calculations
120it, you should treat it as some floating point value. Unlike the name 133on it, you should treat it as some floating point value. Unlike the name
121component C<stamp> might indicate, it is also used for time differences 134component C<stamp> might indicate, it is also used for time differences
122throughout libev. 135throughout libev.
123 136
124=head1 ERROR HANDLING 137=head1 ERROR HANDLING
125 138
332useful to try out specific backends to test their performance, or to work 345useful to try out specific backends to test their performance, or to work
333around bugs. 346around bugs.
334 347
335=item C<EVFLAG_FORKCHECK> 348=item C<EVFLAG_FORKCHECK>
336 349
337Instead of calling C<ev_default_fork> or C<ev_loop_fork> manually after 350Instead of calling C<ev_loop_fork> manually after a fork, you can also
338a fork, you can also make libev check for a fork in each iteration by 351make libev check for a fork in each iteration by enabling this flag.
339enabling this flag.
340 352
341This works by calling C<getpid ()> on every iteration of the loop, 353This works by calling C<getpid ()> on every iteration of the loop,
342and thus this might slow down your event loop if you do a lot of loop 354and thus this might slow down your event loop if you do a lot of loop
343iterations and little real work, but is usually not noticeable (on my 355iterations and little real work, but is usually not noticeable (on my
344GNU/Linux system for example, C<getpid> is actually a simple 5-insn sequence 356GNU/Linux system for example, C<getpid> is actually a simple 5-insn sequence
350flag. 362flag.
351 363
352This flag setting cannot be overridden or specified in the C<LIBEV_FLAGS> 364This flag setting cannot be overridden or specified in the C<LIBEV_FLAGS>
353environment variable. 365environment variable.
354 366
367=item C<EVFLAG_NOINOTIFY>
368
369When this flag is specified, then libev will not attempt to use the
370I<inotify> API for it's C<ev_stat> watchers. Apart from debugging and
371testing, this flag can be useful to conserve inotify file descriptors, as
372otherwise each loop using C<ev_stat> watchers consumes one inotify handle.
373
374=item C<EVFLAG_SIGNALFD>
375
376When this flag is specified, then libev will attempt to use the
377I<signalfd> API for it's C<ev_signal> (and C<ev_child>) watchers. This API
378delivers signals synchronously, which makes it both faster and might make
379it possible to get the queued signal data. It can also simplify signal
380handling with threads, as long as you properly block signals in your
381threads that are not interested in handling them.
382
383Signalfd will not be used by default as this changes your signal mask, and
384there are a lot of shoddy libraries and programs (glib's threadpool for
385example) that can't properly initialise their signal masks.
386
355=item C<EVBACKEND_SELECT> (value 1, portable select backend) 387=item C<EVBACKEND_SELECT> (value 1, portable select backend)
356 388
357This is your standard select(2) backend. Not I<completely> standard, as 389This is your standard select(2) backend. Not I<completely> standard, as
358libev tries to roll its own fd_set with no limits on the number of fds, 390libev tries to roll its own fd_set with no limits on the number of fds,
359but if that fails, expect a fairly low limit on the number of fds when 391but if that fails, expect a fairly low limit on the number of fds when
382 414
383This backend maps C<EV_READ> to C<POLLIN | POLLERR | POLLHUP>, and 415This backend maps C<EV_READ> to C<POLLIN | POLLERR | POLLHUP>, and
384C<EV_WRITE> to C<POLLOUT | POLLERR | POLLHUP>. 416C<EV_WRITE> to C<POLLOUT | POLLERR | POLLHUP>.
385 417
386=item C<EVBACKEND_EPOLL> (value 4, Linux) 418=item C<EVBACKEND_EPOLL> (value 4, Linux)
419
420Use the linux-specific epoll(7) interface (for both pre- and post-2.6.9
421kernels).
387 422
388For few fds, this backend is a bit little slower than poll and select, 423For few fds, this backend is a bit little slower than poll and select,
389but it scales phenomenally better. While poll and select usually scale 424but it scales phenomenally better. While poll and select usually scale
390like O(total_fds) where n is the total number of fds (or the highest fd), 425like O(total_fds) where n is the total number of fds (or the highest fd),
391epoll scales either O(1) or O(active_fds). 426epoll scales either O(1) or O(active_fds).
506 541
507It is definitely not recommended to use this flag. 542It is definitely not recommended to use this flag.
508 543
509=back 544=back
510 545
511If one or more of these are or'ed into the flags value, then only these 546If one or more of the backend flags are or'ed into the flags value,
512backends will be tried (in the reverse order as listed here). If none are 547then only these backends will be tried (in the reverse order as listed
513specified, all backends in C<ev_recommended_backends ()> will be tried. 548here). If none are specified, all backends in C<ev_recommended_backends
549()> will be tried.
514 550
515Example: This is the most typical usage. 551Example: This is the most typical usage.
516 552
517 if (!ev_default_loop (0)) 553 if (!ev_default_loop (0))
518 fatal ("could not initialise libev, bad $LIBEV_FLAGS in environment?"); 554 fatal ("could not initialise libev, bad $LIBEV_FLAGS in environment?");
530 ev_default_loop (ev_recommended_backends () | EVBACKEND_KQUEUE); 566 ev_default_loop (ev_recommended_backends () | EVBACKEND_KQUEUE);
531 567
532=item struct ev_loop *ev_loop_new (unsigned int flags) 568=item struct ev_loop *ev_loop_new (unsigned int flags)
533 569
534Similar to C<ev_default_loop>, but always creates a new event loop that is 570Similar to C<ev_default_loop>, but always creates a new event loop that is
535always distinct from the default loop. Unlike the default loop, it cannot 571always distinct from the default loop.
536handle signal and child watchers, and attempts to do so will be greeted by
537undefined behaviour (or a failed assertion if assertions are enabled).
538 572
539Note that this function I<is> thread-safe, and the recommended way to use 573Note that this function I<is> thread-safe, and one common way to use
540libev with threads is indeed to create one loop per thread, and using the 574libev with threads is indeed to create one loop per thread, and using the
541default loop in the "main" or "initial" thread. 575default loop in the "main" or "initial" thread.
542 576
543Example: Try to create a event loop that uses epoll and nothing else. 577Example: Try to create a event loop that uses epoll and nothing else.
544 578
546 if (!epoller) 580 if (!epoller)
547 fatal ("no epoll found here, maybe it hides under your chair"); 581 fatal ("no epoll found here, maybe it hides under your chair");
548 582
549=item ev_default_destroy () 583=item ev_default_destroy ()
550 584
551Destroys the default loop again (frees all memory and kernel state 585Destroys the default loop (frees all memory and kernel state etc.). None
552etc.). None of the active event watchers will be stopped in the normal 586of the active event watchers will be stopped in the normal sense, so
553sense, so e.g. C<ev_is_active> might still return true. It is your 587e.g. C<ev_is_active> might still return true. It is your responsibility to
554responsibility to either stop all watchers cleanly yourself I<before> 588either stop all watchers cleanly yourself I<before> calling this function,
555calling this function, or cope with the fact afterwards (which is usually 589or cope with the fact afterwards (which is usually the easiest thing, you
556the easiest thing, you can just ignore the watchers and/or C<free ()> them 590can just ignore the watchers and/or C<free ()> them for example).
557for example).
558 591
559Note that certain global state, such as signal state (and installed signal 592Note that certain global state, such as signal state (and installed signal
560handlers), will not be freed by this function, and related watchers (such 593handlers), will not be freed by this function, and related watchers (such
561as signal and child watchers) would need to be stopped manually. 594as signal and child watchers) would need to be stopped manually.
562 595
563In general it is not advisable to call this function except in the 596In general it is not advisable to call this function except in the
564rare occasion where you really need to free e.g. the signal handling 597rare occasion where you really need to free e.g. the signal handling
565pipe fds. If you need dynamically allocated loops it is better to use 598pipe fds. If you need dynamically allocated loops it is better to use
566C<ev_loop_new> and C<ev_loop_destroy>). 599C<ev_loop_new> and C<ev_loop_destroy>.
567 600
568=item ev_loop_destroy (loop) 601=item ev_loop_destroy (loop)
569 602
570Like C<ev_default_destroy>, but destroys an event loop created by an 603Like C<ev_default_destroy>, but destroys an event loop created by an
571earlier call to C<ev_loop_new>. 604earlier call to C<ev_loop_new>.
577name, you can call it anytime, but it makes most sense after forking, in 610name, you can call it anytime, but it makes most sense after forking, in
578the child process (or both child and parent, but that again makes little 611the child process (or both child and parent, but that again makes little
579sense). You I<must> call it in the child before using any of the libev 612sense). You I<must> call it in the child before using any of the libev
580functions, and it will only take effect at the next C<ev_loop> iteration. 613functions, and it will only take effect at the next C<ev_loop> iteration.
581 614
615Again, you I<have> to call it on I<any> loop that you want to re-use after
616a fork, I<even if you do not plan to use the loop in the parent>. This is
617because some kernel interfaces *cough* I<kqueue> *cough* do funny things
618during fork.
619
582On the other hand, you only need to call this function in the child 620On the other hand, you only need to call this function in the child
583process if and only if you want to use the event library in the child. If 621process if and only if you want to use the event loop in the child. If you
584you just fork+exec, you don't have to call it at all. 622just fork+exec or create a new loop in the child, you don't have to call
623it at all.
585 624
586The function itself is quite fast and it's usually not a problem to call 625The function itself is quite fast and it's usually not a problem to call
587it just in case after a fork. To make this easy, the function will fit in 626it just in case after a fork. To make this easy, the function will fit in
588quite nicely into a call to C<pthread_atfork>: 627quite nicely into a call to C<pthread_atfork>:
589 628
591 630
592=item ev_loop_fork (loop) 631=item ev_loop_fork (loop)
593 632
594Like C<ev_default_fork>, but acts on an event loop created by 633Like C<ev_default_fork>, but acts on an event loop created by
595C<ev_loop_new>. Yes, you have to call this on every allocated event loop 634C<ev_loop_new>. Yes, you have to call this on every allocated event loop
596after fork that you want to re-use in the child, and how you do this is 635after fork that you want to re-use in the child, and how you keep track of
597entirely your own problem. 636them is entirely your own problem.
598 637
599=item int ev_is_default_loop (loop) 638=item int ev_is_default_loop (loop)
600 639
601Returns true when the given loop is, in fact, the default loop, and false 640Returns true when the given loop is, in fact, the default loop, and false
602otherwise. 641otherwise.
603 642
604=item unsigned int ev_loop_count (loop) 643=item unsigned int ev_iteration (loop)
605 644
606Returns the count of loop iterations for the loop, which is identical to 645Returns the current iteration count for the loop, which is identical to
607the number of times libev did poll for new events. It starts at C<0> and 646the number of times libev did poll for new events. It starts at C<0> and
608happily wraps around with enough iterations. 647happily wraps around with enough iterations.
609 648
610This value can sometimes be useful as a generation counter of sorts (it 649This value can sometimes be useful as a generation counter of sorts (it
611"ticks" the number of loop iterations), as it roughly corresponds with 650"ticks" the number of loop iterations), as it roughly corresponds with
612C<ev_prepare> and C<ev_check> calls. 651C<ev_prepare> and C<ev_check> calls - and is incremented between the
652prepare and check phases.
653
654=item unsigned int ev_depth (loop)
655
656Returns the number of times C<ev_loop> was entered minus the number of
657times C<ev_loop> was exited, in other words, the recursion depth.
658
659Outside C<ev_loop>, this number is zero. In a callback, this number is
660C<1>, unless C<ev_loop> was invoked recursively (or from another thread),
661in which case it is higher.
662
663Leaving C<ev_loop> abnormally (setjmp/longjmp, cancelling the thread
664etc.), doesn't count as "exit" - consider this as a hint to avoid such
665ungentleman behaviour unless it's really convenient.
613 666
614=item unsigned int ev_backend (loop) 667=item unsigned int ev_backend (loop)
615 668
616Returns one of the C<EVBACKEND_*> flags indicating the event backend in 669Returns one of the C<EVBACKEND_*> flags indicating the event backend in
617use. 670use.
632 685
633This function is rarely useful, but when some event callback runs for a 686This function is rarely useful, but when some event callback runs for a
634very long time without entering the event loop, updating libev's idea of 687very long time without entering the event loop, updating libev's idea of
635the current time is a good idea. 688the current time is a good idea.
636 689
637See also "The special problem of time updates" in the C<ev_timer> section. 690See also L<The special problem of time updates> in the C<ev_timer> section.
638 691
639=item ev_suspend (loop) 692=item ev_suspend (loop)
640 693
641=item ev_resume (loop) 694=item ev_resume (loop)
642 695
663event loop time (see C<ev_now_update>). 716event loop time (see C<ev_now_update>).
664 717
665=item ev_loop (loop, int flags) 718=item ev_loop (loop, int flags)
666 719
667Finally, this is it, the event handler. This function usually is called 720Finally, this is it, the event handler. This function usually is called
668after you initialised all your watchers and you want to start handling 721after you have initialised all your watchers and you want to start
669events. 722handling events.
670 723
671If the flags argument is specified as C<0>, it will not return until 724If the flags argument is specified as C<0>, it will not return until
672either no event watchers are active anymore or C<ev_unloop> was called. 725either no event watchers are active anymore or C<ev_unloop> was called.
673 726
674Please note that an explicit C<ev_unloop> is usually better than 727Please note that an explicit C<ev_unloop> is usually better than
748 801
749Ref/unref can be used to add or remove a reference count on the event 802Ref/unref can be used to add or remove a reference count on the event
750loop: Every watcher keeps one reference, and as long as the reference 803loop: Every watcher keeps one reference, and as long as the reference
751count is nonzero, C<ev_loop> will not return on its own. 804count is nonzero, C<ev_loop> will not return on its own.
752 805
753If you have a watcher you never unregister that should not keep C<ev_loop> 806This is useful when you have a watcher that you never intend to
754from returning, call ev_unref() after starting, and ev_ref() before 807unregister, but that nevertheless should not keep C<ev_loop> from
808returning. In such a case, call C<ev_unref> after starting, and C<ev_ref>
755stopping it. 809before stopping it.
756 810
757As an example, libev itself uses this for its internal signal pipe: It 811As an example, libev itself uses this for its internal signal pipe: It
758is not visible to the libev user and should not keep C<ev_loop> from 812is not visible to the libev user and should not keep C<ev_loop> from
759exiting if no event watchers registered by it are active. It is also an 813exiting if no event watchers registered by it are active. It is also an
760excellent way to do this for generic recurring timers or from within 814excellent way to do this for generic recurring timers or from within
799 853
800By setting a higher I<io collect interval> you allow libev to spend more 854By setting a higher I<io collect interval> you allow libev to spend more
801time collecting I/O events, so you can handle more events per iteration, 855time collecting I/O events, so you can handle more events per iteration,
802at the cost of increasing latency. Timeouts (both C<ev_periodic> and 856at the cost of increasing latency. Timeouts (both C<ev_periodic> and
803C<ev_timer>) will be not affected. Setting this to a non-null value will 857C<ev_timer>) will be not affected. Setting this to a non-null value will
804introduce an additional C<ev_sleep ()> call into most loop iterations. 858introduce an additional C<ev_sleep ()> call into most loop iterations. The
859sleep time ensures that libev will not poll for I/O events more often then
860once per this interval, on average.
805 861
806Likewise, by setting a higher I<timeout collect interval> you allow libev 862Likewise, by setting a higher I<timeout collect interval> you allow libev
807to spend more time collecting timeouts, at the expense of increased 863to spend more time collecting timeouts, at the expense of increased
808latency/jitter/inexactness (the watcher callback will be called 864latency/jitter/inexactness (the watcher callback will be called
809later). C<ev_io> watchers will not be affected. Setting this to a non-null 865later). C<ev_io> watchers will not be affected. Setting this to a non-null
811 867
812Many (busy) programs can usually benefit by setting the I/O collect 868Many (busy) programs can usually benefit by setting the I/O collect
813interval to a value near C<0.1> or so, which is often enough for 869interval to a value near C<0.1> or so, which is often enough for
814interactive servers (of course not for games), likewise for timeouts. It 870interactive servers (of course not for games), likewise for timeouts. It
815usually doesn't make much sense to set it to a lower value than C<0.01>, 871usually doesn't make much sense to set it to a lower value than C<0.01>,
816as this approaches the timing granularity of most systems. 872as this approaches the timing granularity of most systems. Note that if
873you do transactions with the outside world and you can't increase the
874parallelity, then this setting will limit your transaction rate (if you
875need to poll once per transaction and the I/O collect interval is 0.01,
876then you can't do more than 100 transations per second).
817 877
818Setting the I<timeout collect interval> can improve the opportunity for 878Setting the I<timeout collect interval> can improve the opportunity for
819saving power, as the program will "bundle" timer callback invocations that 879saving power, as the program will "bundle" timer callback invocations that
820are "near" in time together, by delaying some, thus reducing the number of 880are "near" in time together, by delaying some, thus reducing the number of
821times the process sleeps and wakes up again. Another useful technique to 881times the process sleeps and wakes up again. Another useful technique to
822reduce iterations/wake-ups is to use C<ev_periodic> watchers and make sure 882reduce iterations/wake-ups is to use C<ev_periodic> watchers and make sure
823they fire on, say, one-second boundaries only. 883they fire on, say, one-second boundaries only.
824 884
885Example: we only need 0.1s timeout granularity, and we wish not to poll
886more often than 100 times per second:
887
888 ev_set_timeout_collect_interval (EV_DEFAULT_UC_ 0.1);
889 ev_set_io_collect_interval (EV_DEFAULT_UC_ 0.01);
890
891=item ev_invoke_pending (loop)
892
893This call will simply invoke all pending watchers while resetting their
894pending state. Normally, C<ev_loop> does this automatically when required,
895but when overriding the invoke callback this call comes handy.
896
897=item int ev_pending_count (loop)
898
899Returns the number of pending watchers - zero indicates that no watchers
900are pending.
901
902=item ev_set_invoke_pending_cb (loop, void (*invoke_pending_cb)(EV_P))
903
904This overrides the invoke pending functionality of the loop: Instead of
905invoking all pending watchers when there are any, C<ev_loop> will call
906this callback instead. This is useful, for example, when you want to
907invoke the actual watchers inside another context (another thread etc.).
908
909If you want to reset the callback, use C<ev_invoke_pending> as new
910callback.
911
912=item ev_set_loop_release_cb (loop, void (*release)(EV_P), void (*acquire)(EV_P))
913
914Sometimes you want to share the same loop between multiple threads. This
915can be done relatively simply by putting mutex_lock/unlock calls around
916each call to a libev function.
917
918However, C<ev_loop> can run an indefinite time, so it is not feasible to
919wait for it to return. One way around this is to wake up the loop via
920C<ev_unloop> and C<av_async_send>, another way is to set these I<release>
921and I<acquire> callbacks on the loop.
922
923When set, then C<release> will be called just before the thread is
924suspended waiting for new events, and C<acquire> is called just
925afterwards.
926
927Ideally, C<release> will just call your mutex_unlock function, and
928C<acquire> will just call the mutex_lock function again.
929
930While event loop modifications are allowed between invocations of
931C<release> and C<acquire> (that's their only purpose after all), no
932modifications done will affect the event loop, i.e. adding watchers will
933have no effect on the set of file descriptors being watched, or the time
934waited. Use an C<ev_async> watcher to wake up C<ev_loop> when you want it
935to take note of any changes you made.
936
937In theory, threads executing C<ev_loop> will be async-cancel safe between
938invocations of C<release> and C<acquire>.
939
940See also the locking example in the C<THREADS> section later in this
941document.
942
943=item ev_set_userdata (loop, void *data)
944
945=item ev_userdata (loop)
946
947Set and retrieve a single C<void *> associated with a loop. When
948C<ev_set_userdata> has never been called, then C<ev_userdata> returns
949C<0.>
950
951These two functions can be used to associate arbitrary data with a loop,
952and are intended solely for the C<invoke_pending_cb>, C<release> and
953C<acquire> callbacks described above, but of course can be (ab-)used for
954any other purpose as well.
955
825=item ev_loop_verify (loop) 956=item ev_loop_verify (loop)
826 957
827This function only does something when C<EV_VERIFY> support has been 958This function only does something when C<EV_VERIFY> support has been
828compiled in, which is the default for non-minimal builds. It tries to go 959compiled in, which is the default for non-minimal builds. It tries to go
829through all internal structures and checks them for validity. If anything 960through all internal structures and checks them for validity. If anything
905=item C<EV_WRITE> 1036=item C<EV_WRITE>
906 1037
907The file descriptor in the C<ev_io> watcher has become readable and/or 1038The file descriptor in the C<ev_io> watcher has become readable and/or
908writable. 1039writable.
909 1040
910=item C<EV_TIMEOUT> 1041=item C<EV_TIMER>
911 1042
912The C<ev_timer> watcher has timed out. 1043The C<ev_timer> watcher has timed out.
913 1044
914=item C<EV_PERIODIC> 1045=item C<EV_PERIODIC>
915 1046
1005 1136
1006 ev_io w; 1137 ev_io w;
1007 ev_init (&w, my_cb); 1138 ev_init (&w, my_cb);
1008 ev_io_set (&w, STDIN_FILENO, EV_READ); 1139 ev_io_set (&w, STDIN_FILENO, EV_READ);
1009 1140
1010=item C<ev_TYPE_set> (ev_TYPE *, [args]) 1141=item C<ev_TYPE_set> (ev_TYPE *watcher, [args])
1011 1142
1012This macro initialises the type-specific parts of a watcher. You need to 1143This macro initialises the type-specific parts of a watcher. You need to
1013call C<ev_init> at least once before you call this macro, but you can 1144call C<ev_init> at least once before you call this macro, but you can
1014call C<ev_TYPE_set> any number of times. You must not, however, call this 1145call C<ev_TYPE_set> any number of times. You must not, however, call this
1015macro on a watcher that is active (it can be pending, however, which is a 1146macro on a watcher that is active (it can be pending, however, which is a
1028 1159
1029Example: Initialise and set an C<ev_io> watcher in one step. 1160Example: Initialise and set an C<ev_io> watcher in one step.
1030 1161
1031 ev_io_init (&w, my_cb, STDIN_FILENO, EV_READ); 1162 ev_io_init (&w, my_cb, STDIN_FILENO, EV_READ);
1032 1163
1033=item C<ev_TYPE_start> (loop *, ev_TYPE *watcher) 1164=item C<ev_TYPE_start> (loop, ev_TYPE *watcher)
1034 1165
1035Starts (activates) the given watcher. Only active watchers will receive 1166Starts (activates) the given watcher. Only active watchers will receive
1036events. If the watcher is already active nothing will happen. 1167events. If the watcher is already active nothing will happen.
1037 1168
1038Example: Start the C<ev_io> watcher that is being abused as example in this 1169Example: Start the C<ev_io> watcher that is being abused as example in this
1039whole section. 1170whole section.
1040 1171
1041 ev_io_start (EV_DEFAULT_UC, &w); 1172 ev_io_start (EV_DEFAULT_UC, &w);
1042 1173
1043=item C<ev_TYPE_stop> (loop *, ev_TYPE *watcher) 1174=item C<ev_TYPE_stop> (loop, ev_TYPE *watcher)
1044 1175
1045Stops the given watcher if active, and clears the pending status (whether 1176Stops the given watcher if active, and clears the pending status (whether
1046the watcher was active or not). 1177the watcher was active or not).
1047 1178
1048It is possible that stopped watchers are pending - for example, 1179It is possible that stopped watchers are pending - for example,
1073=item ev_cb_set (ev_TYPE *watcher, callback) 1204=item ev_cb_set (ev_TYPE *watcher, callback)
1074 1205
1075Change the callback. You can change the callback at virtually any time 1206Change the callback. You can change the callback at virtually any time
1076(modulo threads). 1207(modulo threads).
1077 1208
1078=item ev_set_priority (ev_TYPE *watcher, priority) 1209=item ev_set_priority (ev_TYPE *watcher, int priority)
1079 1210
1080=item int ev_priority (ev_TYPE *watcher) 1211=item int ev_priority (ev_TYPE *watcher)
1081 1212
1082Set and query the priority of the watcher. The priority is a small 1213Set and query the priority of the watcher. The priority is a small
1083integer between C<EV_MAXPRI> (default: C<2>) and C<EV_MINPRI> 1214integer between C<EV_MAXPRI> (default: C<2>) and C<EV_MINPRI>
1084(default: C<-2>). Pending watchers with higher priority will be invoked 1215(default: C<-2>). Pending watchers with higher priority will be invoked
1085before watchers with lower priority, but priority will not keep watchers 1216before watchers with lower priority, but priority will not keep watchers
1086from being executed (except for C<ev_idle> watchers). 1217from being executed (except for C<ev_idle> watchers).
1087 1218
1088This means that priorities are I<only> used for ordering callback
1089invocation after new events have been received. This is useful, for
1090example, to reduce latency after idling, or more often, to bind two
1091watchers on the same event and make sure one is called first.
1092
1093If you need to suppress invocation when higher priority events are pending 1219If you need to suppress invocation when higher priority events are pending
1094you need to look at C<ev_idle> watchers, which provide this functionality. 1220you need to look at C<ev_idle> watchers, which provide this functionality.
1095 1221
1096You I<must not> change the priority of a watcher as long as it is active or 1222You I<must not> change the priority of a watcher as long as it is active or
1097pending. 1223pending.
1098
1099The default priority used by watchers when no priority has been set is
1100always C<0>, which is supposed to not be too high and not be too low :).
1101 1224
1102Setting a priority outside the range of C<EV_MINPRI> to C<EV_MAXPRI> is 1225Setting a priority outside the range of C<EV_MINPRI> to C<EV_MAXPRI> is
1103fine, as long as you do not mind that the priority value you query might 1226fine, as long as you do not mind that the priority value you query might
1104or might not have been clamped to the valid range. 1227or might not have been clamped to the valid range.
1228
1229The default priority used by watchers when no priority has been set is
1230always C<0>, which is supposed to not be too high and not be too low :).
1231
1232See L<WATCHER PRIORITY MODELS>, below, for a more thorough treatment of
1233priorities.
1105 1234
1106=item ev_invoke (loop, ev_TYPE *watcher, int revents) 1235=item ev_invoke (loop, ev_TYPE *watcher, int revents)
1107 1236
1108Invoke the C<watcher> with the given C<loop> and C<revents>. Neither 1237Invoke the C<watcher> with the given C<loop> and C<revents>. Neither
1109C<loop> nor C<revents> need to be valid as long as the watcher callback 1238C<loop> nor C<revents> need to be valid as long as the watcher callback
1116returns its C<revents> bitset (as if its callback was invoked). If the 1245returns its C<revents> bitset (as if its callback was invoked). If the
1117watcher isn't pending it does nothing and returns C<0>. 1246watcher isn't pending it does nothing and returns C<0>.
1118 1247
1119Sometimes it can be useful to "poll" a watcher instead of waiting for its 1248Sometimes it can be useful to "poll" a watcher instead of waiting for its
1120callback to be invoked, which can be accomplished with this function. 1249callback to be invoked, which can be accomplished with this function.
1250
1251=item ev_feed_event (loop, ev_TYPE *watcher, int revents)
1252
1253Feeds the given event set into the event loop, as if the specified event
1254had happened for the specified watcher (which must be a pointer to an
1255initialised but not necessarily started event watcher). Obviously you must
1256not free the watcher as long as it has pending events.
1257
1258Stopping the watcher, letting libev invoke it, or calling
1259C<ev_clear_pending> will clear the pending event, even if the watcher was
1260not started in the first place.
1261
1262See also C<ev_feed_fd_event> and C<ev_feed_signal_event> for related
1263functions that do not need a watcher.
1121 1264
1122=back 1265=back
1123 1266
1124 1267
1125=head2 ASSOCIATING CUSTOM DATA WITH A WATCHER 1268=head2 ASSOCIATING CUSTOM DATA WITH A WATCHER
1174 #include <stddef.h> 1317 #include <stddef.h>
1175 1318
1176 static void 1319 static void
1177 t1_cb (EV_P_ ev_timer *w, int revents) 1320 t1_cb (EV_P_ ev_timer *w, int revents)
1178 { 1321 {
1179 struct my_biggy big = (struct my_biggy * 1322 struct my_biggy big = (struct my_biggy *)
1180 (((char *)w) - offsetof (struct my_biggy, t1)); 1323 (((char *)w) - offsetof (struct my_biggy, t1));
1181 } 1324 }
1182 1325
1183 static void 1326 static void
1184 t2_cb (EV_P_ ev_timer *w, int revents) 1327 t2_cb (EV_P_ ev_timer *w, int revents)
1185 { 1328 {
1186 struct my_biggy big = (struct my_biggy * 1329 struct my_biggy big = (struct my_biggy *)
1187 (((char *)w) - offsetof (struct my_biggy, t2)); 1330 (((char *)w) - offsetof (struct my_biggy, t2));
1188 } 1331 }
1332
1333=head2 WATCHER PRIORITY MODELS
1334
1335Many event loops support I<watcher priorities>, which are usually small
1336integers that influence the ordering of event callback invocation
1337between watchers in some way, all else being equal.
1338
1339In libev, Watcher priorities can be set using C<ev_set_priority>. See its
1340description for the more technical details such as the actual priority
1341range.
1342
1343There are two common ways how these these priorities are being interpreted
1344by event loops:
1345
1346In the more common lock-out model, higher priorities "lock out" invocation
1347of lower priority watchers, which means as long as higher priority
1348watchers receive events, lower priority watchers are not being invoked.
1349
1350The less common only-for-ordering model uses priorities solely to order
1351callback invocation within a single event loop iteration: Higher priority
1352watchers are invoked before lower priority ones, but they all get invoked
1353before polling for new events.
1354
1355Libev uses the second (only-for-ordering) model for all its watchers
1356except for idle watchers (which use the lock-out model).
1357
1358The rationale behind this is that implementing the lock-out model for
1359watchers is not well supported by most kernel interfaces, and most event
1360libraries will just poll for the same events again and again as long as
1361their callbacks have not been executed, which is very inefficient in the
1362common case of one high-priority watcher locking out a mass of lower
1363priority ones.
1364
1365Static (ordering) priorities are most useful when you have two or more
1366watchers handling the same resource: a typical usage example is having an
1367C<ev_io> watcher to receive data, and an associated C<ev_timer> to handle
1368timeouts. Under load, data might be received while the program handles
1369other jobs, but since timers normally get invoked first, the timeout
1370handler will be executed before checking for data. In that case, giving
1371the timer a lower priority than the I/O watcher ensures that I/O will be
1372handled first even under adverse conditions (which is usually, but not
1373always, what you want).
1374
1375Since idle watchers use the "lock-out" model, meaning that idle watchers
1376will only be executed when no same or higher priority watchers have
1377received events, they can be used to implement the "lock-out" model when
1378required.
1379
1380For example, to emulate how many other event libraries handle priorities,
1381you can associate an C<ev_idle> watcher to each such watcher, and in
1382the normal watcher callback, you just start the idle watcher. The real
1383processing is done in the idle watcher callback. This causes libev to
1384continously poll and process kernel event data for the watcher, but when
1385the lock-out case is known to be rare (which in turn is rare :), this is
1386workable.
1387
1388Usually, however, the lock-out model implemented that way will perform
1389miserably under the type of load it was designed to handle. In that case,
1390it might be preferable to stop the real watcher before starting the
1391idle watcher, so the kernel will not have to process the event in case
1392the actual processing will be delayed for considerable time.
1393
1394Here is an example of an I/O watcher that should run at a strictly lower
1395priority than the default, and which should only process data when no
1396other events are pending:
1397
1398 ev_idle idle; // actual processing watcher
1399 ev_io io; // actual event watcher
1400
1401 static void
1402 io_cb (EV_P_ ev_io *w, int revents)
1403 {
1404 // stop the I/O watcher, we received the event, but
1405 // are not yet ready to handle it.
1406 ev_io_stop (EV_A_ w);
1407
1408 // start the idle watcher to ahndle the actual event.
1409 // it will not be executed as long as other watchers
1410 // with the default priority are receiving events.
1411 ev_idle_start (EV_A_ &idle);
1412 }
1413
1414 static void
1415 idle_cb (EV_P_ ev_idle *w, int revents)
1416 {
1417 // actual processing
1418 read (STDIN_FILENO, ...);
1419
1420 // have to start the I/O watcher again, as
1421 // we have handled the event
1422 ev_io_start (EV_P_ &io);
1423 }
1424
1425 // initialisation
1426 ev_idle_init (&idle, idle_cb);
1427 ev_io_init (&io, io_cb, STDIN_FILENO, EV_READ);
1428 ev_io_start (EV_DEFAULT_ &io);
1429
1430In the "real" world, it might also be beneficial to start a timer, so that
1431low-priority connections can not be locked out forever under load. This
1432enables your program to keep a lower latency for important connections
1433during short periods of high load, while not completely locking out less
1434important ones.
1189 1435
1190 1436
1191=head1 WATCHER TYPES 1437=head1 WATCHER TYPES
1192 1438
1193This section describes each watcher in detail, but will not repeat 1439This section describes each watcher in detail, but will not repeat
1219descriptors to non-blocking mode is also usually a good idea (but not 1465descriptors to non-blocking mode is also usually a good idea (but not
1220required if you know what you are doing). 1466required if you know what you are doing).
1221 1467
1222If you cannot use non-blocking mode, then force the use of a 1468If you cannot use non-blocking mode, then force the use of a
1223known-to-be-good backend (at the time of this writing, this includes only 1469known-to-be-good backend (at the time of this writing, this includes only
1224C<EVBACKEND_SELECT> and C<EVBACKEND_POLL>). 1470C<EVBACKEND_SELECT> and C<EVBACKEND_POLL>). The same applies to file
1471descriptors for which non-blocking operation makes no sense (such as
1472files) - libev doesn't guarentee any specific behaviour in that case.
1225 1473
1226Another thing you have to watch out for is that it is quite easy to 1474Another thing you have to watch out for is that it is quite easy to
1227receive "spurious" readiness notifications, that is your callback might 1475receive "spurious" readiness notifications, that is your callback might
1228be called with C<EV_READ> but a subsequent C<read>(2) will actually block 1476be called with C<EV_READ> but a subsequent C<read>(2) will actually block
1229because there is no data. Not only are some backends known to create a 1477because there is no data. Not only are some backends known to create a
1294 1542
1295So when you encounter spurious, unexplained daemon exits, make sure you 1543So when you encounter spurious, unexplained daemon exits, make sure you
1296ignore SIGPIPE (and maybe make sure you log the exit status of your daemon 1544ignore SIGPIPE (and maybe make sure you log the exit status of your daemon
1297somewhere, as that would have given you a big clue). 1545somewhere, as that would have given you a big clue).
1298 1546
1547=head3 The special problem of accept()ing when you can't
1548
1549Many implementations of the POSIX C<accept> function (for example,
1550found in post-2004 Linux) have the peculiar behaviour of not removing a
1551connection from the pending queue in all error cases.
1552
1553For example, larger servers often run out of file descriptors (because
1554of resource limits), causing C<accept> to fail with C<ENFILE> but not
1555rejecting the connection, leading to libev signalling readiness on
1556the next iteration again (the connection still exists after all), and
1557typically causing the program to loop at 100% CPU usage.
1558
1559Unfortunately, the set of errors that cause this issue differs between
1560operating systems, there is usually little the app can do to remedy the
1561situation, and no known thread-safe method of removing the connection to
1562cope with overload is known (to me).
1563
1564One of the easiest ways to handle this situation is to just ignore it
1565- when the program encounters an overload, it will just loop until the
1566situation is over. While this is a form of busy waiting, no OS offers an
1567event-based way to handle this situation, so it's the best one can do.
1568
1569A better way to handle the situation is to log any errors other than
1570C<EAGAIN> and C<EWOULDBLOCK>, making sure not to flood the log with such
1571messages, and continue as usual, which at least gives the user an idea of
1572what could be wrong ("raise the ulimit!"). For extra points one could stop
1573the C<ev_io> watcher on the listening fd "for a while", which reduces CPU
1574usage.
1575
1576If your program is single-threaded, then you could also keep a dummy file
1577descriptor for overload situations (e.g. by opening F</dev/null>), and
1578when you run into C<ENFILE> or C<EMFILE>, close it, run C<accept>,
1579close that fd, and create a new dummy fd. This will gracefully refuse
1580clients under typical overload conditions.
1581
1582The last way to handle it is to simply log the error and C<exit>, as
1583is often done with C<malloc> failures, but this results in an easy
1584opportunity for a DoS attack.
1299 1585
1300=head3 Watcher-Specific Functions 1586=head3 Watcher-Specific Functions
1301 1587
1302=over 4 1588=over 4
1303 1589
1350year, it will still time out after (roughly) one hour. "Roughly" because 1636year, it will still time out after (roughly) one hour. "Roughly" because
1351detecting time jumps is hard, and some inaccuracies are unavoidable (the 1637detecting time jumps is hard, and some inaccuracies are unavoidable (the
1352monotonic clock option helps a lot here). 1638monotonic clock option helps a lot here).
1353 1639
1354The callback is guaranteed to be invoked only I<after> its timeout has 1640The callback is guaranteed to be invoked only I<after> its timeout has
1355passed. If multiple timers become ready during the same loop iteration 1641passed (not I<at>, so on systems with very low-resolution clocks this
1356then the ones with earlier time-out values are invoked before ones with 1642might introduce a small delay). If multiple timers become ready during the
1357later time-out values (but this is no longer true when a callback calls 1643same loop iteration then the ones with earlier time-out values are invoked
1358C<ev_loop> recursively). 1644before ones of the same priority with later time-out values (but this is
1645no longer true when a callback calls C<ev_loop> recursively).
1359 1646
1360=head3 Be smart about timeouts 1647=head3 Be smart about timeouts
1361 1648
1362Many real-world problems involve some kind of timeout, usually for error 1649Many real-world problems involve some kind of timeout, usually for error
1363recovery. A typical example is an HTTP request - if the other side hangs, 1650recovery. A typical example is an HTTP request - if the other side hangs,
1407C<after> argument to C<ev_timer_set>, and only ever use the C<repeat> 1694C<after> argument to C<ev_timer_set>, and only ever use the C<repeat>
1408member and C<ev_timer_again>. 1695member and C<ev_timer_again>.
1409 1696
1410At start: 1697At start:
1411 1698
1412 ev_timer_init (timer, callback); 1699 ev_init (timer, callback);
1413 timer->repeat = 60.; 1700 timer->repeat = 60.;
1414 ev_timer_again (loop, timer); 1701 ev_timer_again (loop, timer);
1415 1702
1416Each time there is some activity: 1703Each time there is some activity:
1417 1704
1479 1766
1480To start the timer, simply initialise the watcher and set C<last_activity> 1767To start the timer, simply initialise the watcher and set C<last_activity>
1481to the current time (meaning we just have some activity :), then call the 1768to the current time (meaning we just have some activity :), then call the
1482callback, which will "do the right thing" and start the timer: 1769callback, which will "do the right thing" and start the timer:
1483 1770
1484 ev_timer_init (timer, callback); 1771 ev_init (timer, callback);
1485 last_activity = ev_now (loop); 1772 last_activity = ev_now (loop);
1486 callback (loop, timer, EV_TIMEOUT); 1773 callback (loop, timer, EV_TIMER);
1487 1774
1488And when there is some activity, simply store the current time in 1775And when there is some activity, simply store the current time in
1489C<last_activity>, no libev calls at all: 1776C<last_activity>, no libev calls at all:
1490 1777
1491 last_actiivty = ev_now (loop); 1778 last_actiivty = ev_now (loop);
1550 1837
1551If the event loop is suspended for a long time, you can also force an 1838If the event loop is suspended for a long time, you can also force an
1552update of the time returned by C<ev_now ()> by calling C<ev_now_update 1839update of the time returned by C<ev_now ()> by calling C<ev_now_update
1553()>. 1840()>.
1554 1841
1842=head3 The special problems of suspended animation
1843
1844When you leave the server world it is quite customary to hit machines that
1845can suspend/hibernate - what happens to the clocks during such a suspend?
1846
1847Some quick tests made with a Linux 2.6.28 indicate that a suspend freezes
1848all processes, while the clocks (C<times>, C<CLOCK_MONOTONIC>) continue
1849to run until the system is suspended, but they will not advance while the
1850system is suspended. That means, on resume, it will be as if the program
1851was frozen for a few seconds, but the suspend time will not be counted
1852towards C<ev_timer> when a monotonic clock source is used. The real time
1853clock advanced as expected, but if it is used as sole clocksource, then a
1854long suspend would be detected as a time jump by libev, and timers would
1855be adjusted accordingly.
1856
1857I would not be surprised to see different behaviour in different between
1858operating systems, OS versions or even different hardware.
1859
1860The other form of suspend (job control, or sending a SIGSTOP) will see a
1861time jump in the monotonic clocks and the realtime clock. If the program
1862is suspended for a very long time, and monotonic clock sources are in use,
1863then you can expect C<ev_timer>s to expire as the full suspension time
1864will be counted towards the timers. When no monotonic clock source is in
1865use, then libev will again assume a timejump and adjust accordingly.
1866
1867It might be beneficial for this latter case to call C<ev_suspend>
1868and C<ev_resume> in code that handles C<SIGTSTP>, to at least get
1869deterministic behaviour in this case (you can do nothing against
1870C<SIGSTOP>).
1871
1555=head3 Watcher-Specific Functions and Data Members 1872=head3 Watcher-Specific Functions and Data Members
1556 1873
1557=over 4 1874=over 4
1558 1875
1559=item ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat) 1876=item ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat)
1582If the timer is started but non-repeating, stop it (as if it timed out). 1899If the timer is started but non-repeating, stop it (as if it timed out).
1583 1900
1584If the timer is repeating, either start it if necessary (with the 1901If the timer is repeating, either start it if necessary (with the
1585C<repeat> value), or reset the running timer to the C<repeat> value. 1902C<repeat> value), or reset the running timer to the C<repeat> value.
1586 1903
1587This sounds a bit complicated, see "Be smart about timeouts", above, for a 1904This sounds a bit complicated, see L<Be smart about timeouts>, above, for a
1588usage example. 1905usage example.
1906
1907=item ev_tstamp ev_timer_remaining (loop, ev_timer *)
1908
1909Returns the remaining time until a timer fires. If the timer is active,
1910then this time is relative to the current event loop time, otherwise it's
1911the timeout value currently configured.
1912
1913That is, after an C<ev_timer_set (w, 5, 7)>, C<ev_timer_remaining> returns
1914C<5>. When the timer is started and one second passes, C<ev_timer_remaining>
1915will return C<4>. When the timer expires and is restarted, it will return
1916roughly C<7> (likely slightly less as callback invocation takes some time,
1917too), and so on.
1589 1918
1590=item ev_tstamp repeat [read-write] 1919=item ev_tstamp repeat [read-write]
1591 1920
1592The current C<repeat> value. Will be used each time the watcher times out 1921The current C<repeat> value. Will be used each time the watcher times out
1593or C<ev_timer_again> is called, and determines the next timeout (if any), 1922or C<ev_timer_again> is called, and determines the next timeout (if any),
1829Signal watchers will trigger an event when the process receives a specific 2158Signal watchers will trigger an event when the process receives a specific
1830signal one or more times. Even though signals are very asynchronous, libev 2159signal one or more times. Even though signals are very asynchronous, libev
1831will try it's best to deliver signals synchronously, i.e. as part of the 2160will try it's best to deliver signals synchronously, i.e. as part of the
1832normal event processing, like any other event. 2161normal event processing, like any other event.
1833 2162
1834If you want signals asynchronously, just use C<sigaction> as you would 2163If you want signals to be delivered truly asynchronously, just use
1835do without libev and forget about sharing the signal. You can even use 2164C<sigaction> as you would do without libev and forget about sharing
1836C<ev_async> from a signal handler to synchronously wake up an event loop. 2165the signal. You can even use C<ev_async> from a signal handler to
2166synchronously wake up an event loop.
1837 2167
1838You can configure as many watchers as you like per signal. Only when the 2168You can configure as many watchers as you like for the same signal, but
2169only within the same loop, i.e. you can watch for C<SIGINT> in your
2170default loop and for C<SIGIO> in another loop, but you cannot watch for
2171C<SIGINT> in both the default loop and another loop at the same time. At
2172the moment, C<SIGCHLD> is permanently tied to the default loop.
2173
1839first watcher gets started will libev actually register a signal handler 2174When the first watcher gets started will libev actually register something
1840with the kernel (thus it coexists with your own signal handlers as long as 2175with the kernel (thus it coexists with your own signal handlers as long as
1841you don't register any with libev for the same signal). Similarly, when 2176you don't register any with libev for the same signal).
1842the last signal watcher for a signal is stopped, libev will reset the
1843signal handler to SIG_DFL (regardless of what it was set to before).
1844 2177
1845If possible and supported, libev will install its handlers with 2178If possible and supported, libev will install its handlers with
1846C<SA_RESTART> behaviour enabled, so system calls should not be unduly 2179C<SA_RESTART> (or equivalent) behaviour enabled, so system calls should
1847interrupted. If you have a problem with system calls getting interrupted by 2180not be unduly interrupted. If you have a problem with system calls getting
1848signals you can block all signals in an C<ev_check> watcher and unblock 2181interrupted by signals you can block all signals in an C<ev_check> watcher
1849them in an C<ev_prepare> watcher. 2182and unblock them in an C<ev_prepare> watcher.
2183
2184=head3 The special problem of inheritance over fork/execve/pthread_create
2185
2186Both the signal mask (C<sigprocmask>) and the signal disposition
2187(C<sigaction>) are unspecified after starting a signal watcher (and after
2188stopping it again), that is, libev might or might not block the signal,
2189and might or might not set or restore the installed signal handler.
2190
2191While this does not matter for the signal disposition (libev never
2192sets signals to C<SIG_IGN>, so handlers will be reset to C<SIG_DFL> on
2193C<execve>), this matters for the signal mask: many programs do not expect
2194certain signals to be blocked.
2195
2196This means that before calling C<exec> (from the child) you should reset
2197the signal mask to whatever "default" you expect (all clear is a good
2198choice usually).
2199
2200The simplest way to ensure that the signal mask is reset in the child is
2201to install a fork handler with C<pthread_atfork> that resets it. That will
2202catch fork calls done by libraries (such as the libc) as well.
2203
2204In current versions of libev, the signal will not be blocked indefinitely
2205unless you use the C<signalfd> API (C<EV_SIGNALFD>). While this reduces
2206the window of opportunity for problems, it will not go away, as libev
2207I<has> to modify the signal mask, at least temporarily.
2208
2209So I can't stress this enough: I<If you do not reset your signal mask when
2210you expect it to be empty, you have a race condition in your code>. This
2211is not a libev-specific thing, this is true for most event libraries.
1850 2212
1851=head3 Watcher-Specific Functions and Data Members 2213=head3 Watcher-Specific Functions and Data Members
1852 2214
1853=over 4 2215=over 4
1854 2216
1886some child status changes (most typically when a child of yours dies or 2248some child status changes (most typically when a child of yours dies or
1887exits). It is permissible to install a child watcher I<after> the child 2249exits). It is permissible to install a child watcher I<after> the child
1888has been forked (which implies it might have already exited), as long 2250has been forked (which implies it might have already exited), as long
1889as the event loop isn't entered (or is continued from a watcher), i.e., 2251as the event loop isn't entered (or is continued from a watcher), i.e.,
1890forking and then immediately registering a watcher for the child is fine, 2252forking and then immediately registering a watcher for the child is fine,
1891but forking and registering a watcher a few event loop iterations later is 2253but forking and registering a watcher a few event loop iterations later or
1892not. 2254in the next callback invocation is not.
1893 2255
1894Only the default event loop is capable of handling signals, and therefore 2256Only the default event loop is capable of handling signals, and therefore
1895you can only register child watchers in the default event loop. 2257you can only register child watchers in the default event loop.
1896 2258
2259Due to some design glitches inside libev, child watchers will always be
2260handled at maximum priority (their priority is set to C<EV_MAXPRI> by
2261libev)
2262
1897=head3 Process Interaction 2263=head3 Process Interaction
1898 2264
1899Libev grabs C<SIGCHLD> as soon as the default event loop is 2265Libev grabs C<SIGCHLD> as soon as the default event loop is
1900initialised. This is necessary to guarantee proper behaviour even if 2266initialised. This is necessary to guarantee proper behaviour even if the
1901the first child watcher is started after the child exits. The occurrence 2267first child watcher is started after the child exits. The occurrence
1902of C<SIGCHLD> is recorded asynchronously, but child reaping is done 2268of C<SIGCHLD> is recorded asynchronously, but child reaping is done
1903synchronously as part of the event loop processing. Libev always reaps all 2269synchronously as part of the event loop processing. Libev always reaps all
1904children, even ones not watched. 2270children, even ones not watched.
1905 2271
1906=head3 Overriding the Built-In Processing 2272=head3 Overriding the Built-In Processing
1916=head3 Stopping the Child Watcher 2282=head3 Stopping the Child Watcher
1917 2283
1918Currently, the child watcher never gets stopped, even when the 2284Currently, the child watcher never gets stopped, even when the
1919child terminates, so normally one needs to stop the watcher in the 2285child terminates, so normally one needs to stop the watcher in the
1920callback. Future versions of libev might stop the watcher automatically 2286callback. Future versions of libev might stop the watcher automatically
1921when a child exit is detected. 2287when a child exit is detected (calling C<ev_child_stop> twice is not a
2288problem).
1922 2289
1923=head3 Watcher-Specific Functions and Data Members 2290=head3 Watcher-Specific Functions and Data Members
1924 2291
1925=over 4 2292=over 4
1926 2293
2252 // no longer anything immediate to do. 2619 // no longer anything immediate to do.
2253 } 2620 }
2254 2621
2255 ev_idle *idle_watcher = malloc (sizeof (ev_idle)); 2622 ev_idle *idle_watcher = malloc (sizeof (ev_idle));
2256 ev_idle_init (idle_watcher, idle_cb); 2623 ev_idle_init (idle_watcher, idle_cb);
2257 ev_idle_start (loop, idle_cb); 2624 ev_idle_start (loop, idle_watcher);
2258 2625
2259 2626
2260=head2 C<ev_prepare> and C<ev_check> - customise your event loop! 2627=head2 C<ev_prepare> and C<ev_check> - customise your event loop!
2261 2628
2262Prepare and check watchers are usually (but not always) used in pairs: 2629Prepare and check watchers are usually (but not always) used in pairs:
2355 struct pollfd fds [nfd]; 2722 struct pollfd fds [nfd];
2356 // actual code will need to loop here and realloc etc. 2723 // actual code will need to loop here and realloc etc.
2357 adns_beforepoll (ads, fds, &nfd, &timeout, timeval_from (ev_time ())); 2724 adns_beforepoll (ads, fds, &nfd, &timeout, timeval_from (ev_time ()));
2358 2725
2359 /* the callback is illegal, but won't be called as we stop during check */ 2726 /* the callback is illegal, but won't be called as we stop during check */
2360 ev_timer_init (&tw, 0, timeout * 1e-3); 2727 ev_timer_init (&tw, 0, timeout * 1e-3, 0.);
2361 ev_timer_start (loop, &tw); 2728 ev_timer_start (loop, &tw);
2362 2729
2363 // create one ev_io per pollfd 2730 // create one ev_io per pollfd
2364 for (int i = 0; i < nfd; ++i) 2731 for (int i = 0; i < nfd; ++i)
2365 { 2732 {
2595event loop blocks next and before C<ev_check> watchers are being called, 2962event loop blocks next and before C<ev_check> watchers are being called,
2596and only in the child after the fork. If whoever good citizen calling 2963and only in the child after the fork. If whoever good citizen calling
2597C<ev_default_fork> cheats and calls it in the wrong process, the fork 2964C<ev_default_fork> cheats and calls it in the wrong process, the fork
2598handlers will be invoked, too, of course. 2965handlers will be invoked, too, of course.
2599 2966
2967=head3 The special problem of life after fork - how is it possible?
2968
2969Most uses of C<fork()> consist of forking, then some simple calls to ste
2970up/change the process environment, followed by a call to C<exec()>. This
2971sequence should be handled by libev without any problems.
2972
2973This changes when the application actually wants to do event handling
2974in the child, or both parent in child, in effect "continuing" after the
2975fork.
2976
2977The default mode of operation (for libev, with application help to detect
2978forks) is to duplicate all the state in the child, as would be expected
2979when I<either> the parent I<or> the child process continues.
2980
2981When both processes want to continue using libev, then this is usually the
2982wrong result. In that case, usually one process (typically the parent) is
2983supposed to continue with all watchers in place as before, while the other
2984process typically wants to start fresh, i.e. without any active watchers.
2985
2986The cleanest and most efficient way to achieve that with libev is to
2987simply create a new event loop, which of course will be "empty", and
2988use that for new watchers. This has the advantage of not touching more
2989memory than necessary, and thus avoiding the copy-on-write, and the
2990disadvantage of having to use multiple event loops (which do not support
2991signal watchers).
2992
2993When this is not possible, or you want to use the default loop for
2994other reasons, then in the process that wants to start "fresh", call
2995C<ev_default_destroy ()> followed by C<ev_default_loop (...)>. Destroying
2996the default loop will "orphan" (not stop) all registered watchers, so you
2997have to be careful not to execute code that modifies those watchers. Note
2998also that in that case, you have to re-register any signal watchers.
2999
2600=head3 Watcher-Specific Functions and Data Members 3000=head3 Watcher-Specific Functions and Data Members
2601 3001
2602=over 4 3002=over 4
2603 3003
2604=item ev_fork_init (ev_signal *, callback) 3004=item ev_fork_init (ev_signal *, callback)
2633=head3 Queueing 3033=head3 Queueing
2634 3034
2635C<ev_async> does not support queueing of data in any way. The reason 3035C<ev_async> does not support queueing of data in any way. The reason
2636is that the author does not know of a simple (or any) algorithm for a 3036is that the author does not know of a simple (or any) algorithm for a
2637multiple-writer-single-reader queue that works in all cases and doesn't 3037multiple-writer-single-reader queue that works in all cases and doesn't
2638need elaborate support such as pthreads. 3038need elaborate support such as pthreads or unportable memory access
3039semantics.
2639 3040
2640That means that if you want to queue data, you have to provide your own 3041That means that if you want to queue data, you have to provide your own
2641queue. But at least I can tell you how to implement locking around your 3042queue. But at least I can tell you how to implement locking around your
2642queue: 3043queue:
2643 3044
2782 3183
2783If C<timeout> is less than 0, then no timeout watcher will be 3184If C<timeout> is less than 0, then no timeout watcher will be
2784started. Otherwise an C<ev_timer> watcher with after = C<timeout> (and 3185started. Otherwise an C<ev_timer> watcher with after = C<timeout> (and
2785repeat = 0) will be started. C<0> is a valid timeout. 3186repeat = 0) will be started. C<0> is a valid timeout.
2786 3187
2787The callback has the type C<void (*cb)(int revents, void *arg)> and gets 3188The callback has the type C<void (*cb)(int revents, void *arg)> and is
2788passed an C<revents> set like normal event callbacks (a combination of 3189passed an C<revents> set like normal event callbacks (a combination of
2789C<EV_ERROR>, C<EV_READ>, C<EV_WRITE> or C<EV_TIMEOUT>) and the C<arg> 3190C<EV_ERROR>, C<EV_READ>, C<EV_WRITE> or C<EV_TIMER>) and the C<arg>
2790value passed to C<ev_once>. Note that it is possible to receive I<both> 3191value passed to C<ev_once>. Note that it is possible to receive I<both>
2791a timeout and an io event at the same time - you probably should give io 3192a timeout and an io event at the same time - you probably should give io
2792events precedence. 3193events precedence.
2793 3194
2794Example: wait up to ten seconds for data to appear on STDIN_FILENO. 3195Example: wait up to ten seconds for data to appear on STDIN_FILENO.
2795 3196
2796 static void stdin_ready (int revents, void *arg) 3197 static void stdin_ready (int revents, void *arg)
2797 { 3198 {
2798 if (revents & EV_READ) 3199 if (revents & EV_READ)
2799 /* stdin might have data for us, joy! */; 3200 /* stdin might have data for us, joy! */;
2800 else if (revents & EV_TIMEOUT) 3201 else if (revents & EV_TIMER)
2801 /* doh, nothing entered */; 3202 /* doh, nothing entered */;
2802 } 3203 }
2803 3204
2804 ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0); 3205 ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0);
2805 3206
2806=item ev_feed_event (struct ev_loop *, watcher *, int revents)
2807
2808Feeds the given event set into the event loop, as if the specified event
2809had happened for the specified watcher (which must be a pointer to an
2810initialised but not necessarily started event watcher).
2811
2812=item ev_feed_fd_event (struct ev_loop *, int fd, int revents) 3207=item ev_feed_fd_event (loop, int fd, int revents)
2813 3208
2814Feed an event on the given fd, as if a file descriptor backend detected 3209Feed an event on the given fd, as if a file descriptor backend detected
2815the given events it. 3210the given events it.
2816 3211
2817=item ev_feed_signal_event (struct ev_loop *loop, int signum) 3212=item ev_feed_signal_event (loop, int signum)
2818 3213
2819Feed an event as if the given signal occurred (C<loop> must be the default 3214Feed an event as if the given signal occurred (C<loop> must be the default
2820loop!). 3215loop!).
2821 3216
2822=back 3217=back
2902 3297
2903=over 4 3298=over 4
2904 3299
2905=item ev::TYPE::TYPE () 3300=item ev::TYPE::TYPE ()
2906 3301
2907=item ev::TYPE::TYPE (struct ev_loop *) 3302=item ev::TYPE::TYPE (loop)
2908 3303
2909=item ev::TYPE::~TYPE 3304=item ev::TYPE::~TYPE
2910 3305
2911The constructor (optionally) takes an event loop to associate the watcher 3306The constructor (optionally) takes an event loop to associate the watcher
2912with. If it is omitted, it will use C<EV_DEFAULT>. 3307with. If it is omitted, it will use C<EV_DEFAULT>.
2989Example: Use a plain function as callback. 3384Example: Use a plain function as callback.
2990 3385
2991 static void io_cb (ev::io &w, int revents) { } 3386 static void io_cb (ev::io &w, int revents) { }
2992 iow.set <io_cb> (); 3387 iow.set <io_cb> ();
2993 3388
2994=item w->set (struct ev_loop *) 3389=item w->set (loop)
2995 3390
2996Associates a different C<struct ev_loop> with this watcher. You can only 3391Associates a different C<struct ev_loop> with this watcher. You can only
2997do this when the watcher is inactive (and not pending either). 3392do this when the watcher is inactive (and not pending either).
2998 3393
2999=item w->set ([arguments]) 3394=item w->set ([arguments])
3096=item Ocaml 3491=item Ocaml
3097 3492
3098Erkki Seppala has written Ocaml bindings for libev, to be found at 3493Erkki Seppala has written Ocaml bindings for libev, to be found at
3099L<http://modeemi.cs.tut.fi/~flux/software/ocaml-ev/>. 3494L<http://modeemi.cs.tut.fi/~flux/software/ocaml-ev/>.
3100 3495
3496=item Lua
3497
3498Brian Maher has written a partial interface to libev for lua (at the
3499time of this writing, only C<ev_io> and C<ev_timer>), to be found at
3500L<http://github.com/brimworks/lua-ev>.
3501
3101=back 3502=back
3102 3503
3103 3504
3104=head1 MACRO MAGIC 3505=head1 MACRO MAGIC
3105 3506
3258 libev.m4 3659 libev.m4
3259 3660
3260=head2 PREPROCESSOR SYMBOLS/MACROS 3661=head2 PREPROCESSOR SYMBOLS/MACROS
3261 3662
3262Libev can be configured via a variety of preprocessor symbols you have to 3663Libev can be configured via a variety of preprocessor symbols you have to
3263define before including any of its files. The default in the absence of 3664define before including (or compiling) any of its files. The default in
3264autoconf is documented for every option. 3665the absence of autoconf is documented for every option.
3666
3667Symbols marked with "(h)" do not change the ABI, and can have different
3668values when compiling libev vs. including F<ev.h>, so it is permissible
3669to redefine them before including F<ev.h> without breaking compatibility
3670to a compiled library. All other symbols change the ABI, which means all
3671users of libev and the libev code itself must be compiled with compatible
3672settings.
3265 3673
3266=over 4 3674=over 4
3267 3675
3268=item EV_STANDALONE 3676=item EV_STANDALONE (h)
3269 3677
3270Must always be C<1> if you do not use autoconf configuration, which 3678Must always be C<1> if you do not use autoconf configuration, which
3271keeps libev from including F<config.h>, and it also defines dummy 3679keeps libev from including F<config.h>, and it also defines dummy
3272implementations for some libevent functions (such as logging, which is not 3680implementations for some libevent functions (such as logging, which is not
3273supported). It will also not define any of the structs usually found in 3681supported). It will also not define any of the structs usually found in
3274F<event.h> that are not directly supported by the libev core alone. 3682F<event.h> that are not directly supported by the libev core alone.
3275 3683
3276In stanbdalone mode, libev will still try to automatically deduce the 3684In standalone mode, libev will still try to automatically deduce the
3277configuration, but has to be more conservative. 3685configuration, but has to be more conservative.
3278 3686
3279=item EV_USE_MONOTONIC 3687=item EV_USE_MONOTONIC
3280 3688
3281If defined to be C<1>, libev will try to detect the availability of the 3689If defined to be C<1>, libev will try to detect the availability of the
3346be used is the winsock select). This means that it will call 3754be used is the winsock select). This means that it will call
3347C<_get_osfhandle> on the fd to convert it to an OS handle. Otherwise, 3755C<_get_osfhandle> on the fd to convert it to an OS handle. Otherwise,
3348it is assumed that all these functions actually work on fds, even 3756it is assumed that all these functions actually work on fds, even
3349on win32. Should not be defined on non-win32 platforms. 3757on win32. Should not be defined on non-win32 platforms.
3350 3758
3351=item EV_FD_TO_WIN32_HANDLE 3759=item EV_FD_TO_WIN32_HANDLE(fd)
3352 3760
3353If C<EV_SELECT_IS_WINSOCKET> is enabled, then libev needs a way to map 3761If C<EV_SELECT_IS_WINSOCKET> is enabled, then libev needs a way to map
3354file descriptors to socket handles. When not defining this symbol (the 3762file descriptors to socket handles. When not defining this symbol (the
3355default), then libev will call C<_get_osfhandle>, which is usually 3763default), then libev will call C<_get_osfhandle>, which is usually
3356correct. In some cases, programs use their own file descriptor management, 3764correct. In some cases, programs use their own file descriptor management,
3357in which case they can provide this function to map fds to socket handles. 3765in which case they can provide this function to map fds to socket handles.
3766
3767=item EV_WIN32_HANDLE_TO_FD(handle)
3768
3769If C<EV_SELECT_IS_WINSOCKET> then libev maps handles to file descriptors
3770using the standard C<_open_osfhandle> function. For programs implementing
3771their own fd to handle mapping, overwriting this function makes it easier
3772to do so. This can be done by defining this macro to an appropriate value.
3773
3774=item EV_WIN32_CLOSE_FD(fd)
3775
3776If programs implement their own fd to handle mapping on win32, then this
3777macro can be used to override the C<close> function, useful to unregister
3778file descriptors again. Note that the replacement function has to close
3779the underlying OS handle.
3358 3780
3359=item EV_USE_POLL 3781=item EV_USE_POLL
3360 3782
3361If defined to be C<1>, libev will compile in support for the C<poll>(2) 3783If defined to be C<1>, libev will compile in support for the C<poll>(2)
3362backend. Otherwise it will be enabled on non-win32 platforms. It 3784backend. Otherwise it will be enabled on non-win32 platforms. It
3409as well as for signal and thread safety in C<ev_async> watchers. 3831as well as for signal and thread safety in C<ev_async> watchers.
3410 3832
3411In the absence of this define, libev will use C<sig_atomic_t volatile> 3833In the absence of this define, libev will use C<sig_atomic_t volatile>
3412(from F<signal.h>), which is usually good enough on most platforms. 3834(from F<signal.h>), which is usually good enough on most platforms.
3413 3835
3414=item EV_H 3836=item EV_H (h)
3415 3837
3416The name of the F<ev.h> header file used to include it. The default if 3838The name of the F<ev.h> header file used to include it. The default if
3417undefined is C<"ev.h"> in F<event.h>, F<ev.c> and F<ev++.h>. This can be 3839undefined is C<"ev.h"> in F<event.h>, F<ev.c> and F<ev++.h>. This can be
3418used to virtually rename the F<ev.h> header file in case of conflicts. 3840used to virtually rename the F<ev.h> header file in case of conflicts.
3419 3841
3420=item EV_CONFIG_H 3842=item EV_CONFIG_H (h)
3421 3843
3422If C<EV_STANDALONE> isn't C<1>, this variable can be used to override 3844If C<EV_STANDALONE> isn't C<1>, this variable can be used to override
3423F<ev.c>'s idea of where to find the F<config.h> file, similarly to 3845F<ev.c>'s idea of where to find the F<config.h> file, similarly to
3424C<EV_H>, above. 3846C<EV_H>, above.
3425 3847
3426=item EV_EVENT_H 3848=item EV_EVENT_H (h)
3427 3849
3428Similarly to C<EV_H>, this macro can be used to override F<event.c>'s idea 3850Similarly to C<EV_H>, this macro can be used to override F<event.c>'s idea
3429of how the F<event.h> header can be found, the default is C<"event.h">. 3851of how the F<event.h> header can be found, the default is C<"event.h">.
3430 3852
3431=item EV_PROTOTYPES 3853=item EV_PROTOTYPES (h)
3432 3854
3433If defined to be C<0>, then F<ev.h> will not define any function 3855If defined to be C<0>, then F<ev.h> will not define any function
3434prototypes, but still define all the structs and other symbols. This is 3856prototypes, but still define all the structs and other symbols. This is
3435occasionally useful if you want to provide your own wrapper functions 3857occasionally useful if you want to provide your own wrapper functions
3436around libev functions. 3858around libev functions.
3458fine. 3880fine.
3459 3881
3460If your embedding application does not need any priorities, defining these 3882If your embedding application does not need any priorities, defining these
3461both to C<0> will save some memory and CPU. 3883both to C<0> will save some memory and CPU.
3462 3884
3463=item EV_PERIODIC_ENABLE 3885=item EV_PERIODIC_ENABLE, EV_IDLE_ENABLE, EV_EMBED_ENABLE, EV_STAT_ENABLE,
3886EV_PREPARE_ENABLE, EV_CHECK_ENABLE, EV_FORK_ENABLE, EV_SIGNAL_ENABLE,
3887EV_ASYNC_ENABLE, EV_CHILD_ENABLE.
3464 3888
3465If undefined or defined to be C<1>, then periodic timers are supported. If 3889If undefined or defined to be C<1> (and the platform supports it), then
3466defined to be C<0>, then they are not. Disabling them saves a few kB of 3890the respective watcher type is supported. If defined to be C<0>, then it
3467code. 3891is not. Disabling watcher types mainly saves codesize.
3468 3892
3469=item EV_IDLE_ENABLE 3893=item EV_FEATURES
3470
3471If undefined or defined to be C<1>, then idle watchers are supported. If
3472defined to be C<0>, then they are not. Disabling them saves a few kB of
3473code.
3474
3475=item EV_EMBED_ENABLE
3476
3477If undefined or defined to be C<1>, then embed watchers are supported. If
3478defined to be C<0>, then they are not. Embed watchers rely on most other
3479watcher types, which therefore must not be disabled.
3480
3481=item EV_STAT_ENABLE
3482
3483If undefined or defined to be C<1>, then stat watchers are supported. If
3484defined to be C<0>, then they are not.
3485
3486=item EV_FORK_ENABLE
3487
3488If undefined or defined to be C<1>, then fork watchers are supported. If
3489defined to be C<0>, then they are not.
3490
3491=item EV_ASYNC_ENABLE
3492
3493If undefined or defined to be C<1>, then async watchers are supported. If
3494defined to be C<0>, then they are not.
3495
3496=item EV_MINIMAL
3497 3894
3498If you need to shave off some kilobytes of code at the expense of some 3895If you need to shave off some kilobytes of code at the expense of some
3499speed, define this symbol to C<1>. Currently this is used to override some 3896speed (but with the full API), you can define this symbol to request
3500inlining decisions, saves roughly 30% code size on amd64. It also selects a 3897certain subsets of functionality. The default is to enable all features
3501much smaller 2-heap for timer management over the default 4-heap. 3898that can be enabled on the platform.
3899
3900A typical way to use this symbol is to define it to C<0> (or to a bitset
3901with some broad features you want) and then selectively re-enable
3902additional parts you want, for example if you want everything minimal,
3903but multiple event loop support, async and child watchers and the poll
3904backend, use this:
3905
3906 #define EV_FEATURES 0
3907 #define EV_MULTIPLICITY 1
3908 #define EV_USE_POLL 1
3909 #define EV_CHILD_ENABLE 1
3910 #define EV_ASYNC_ENABLE 1
3911
3912The actual value is a bitset, it can be a combination of the following
3913values:
3914
3915=over 4
3916
3917=item C<1> - faster/larger code
3918
3919Use larger code to speed up some operations.
3920
3921Currently this is used to override some inlining decisions (enlarging the roughly
392230% code size on amd64.
3923
3924When optimising for size, use of compiler flags such as C<-Os> with
3925gcc recommended, as well as C<-DNDEBUG>, as libev contains a number of
3926assertions.
3927
3928=item C<2> - faster/larger data structures
3929
3930Replaces the small 2-heap for timer management by a faster 4-heap, larger
3931hash table sizes and so on. This will usually further increase codesize
3932and can additionally have an effect on the size of data structures at
3933runtime.
3934
3935=item C<4> - full API configuration
3936
3937This enables priorities (sets C<EV_MAXPRI>=2 and C<EV_MINPRI>=-2), and
3938enables multiplicity (C<EV_MULTIPLICITY>=1).
3939
3940=item C<8> - full API
3941
3942This enables a lot of the "lesser used" API functions. See C<ev.h> for
3943details on which parts of the API are still available without this
3944feature, and do not complain if this subset changes over time.
3945
3946=item C<16> - enable all optional watcher types
3947
3948Enables all optional watcher types. If you want to selectively enable
3949only some watcher types other than I/O and timers (e.g. prepare,
3950embed, async, child...) you can enable them manually by defining
3951C<EV_watchertype_ENABLE> to C<1> instead.
3952
3953=item C<32> - enable all backends
3954
3955This enables all backends - without this feature, you need to enable at
3956least one backend manually (C<EV_USE_SELECT> is a good choice).
3957
3958=item C<64> - enable OS-specific "helper" APIs
3959
3960Enable inotify, eventfd, signalfd and similar OS-specific helper APIs by
3961default.
3962
3963=back
3964
3965Compiling with C<gcc -Os -DEV_STANDALONE -DEV_USE_EPOLL=1 -DEV_FEATURES=0>
3966reduces the compiled size of libev from 24.7Kb code/2.8Kb data to 6.5Kb
3967code/0.3Kb data on my GNU/Linux amd64 system, while still giving you I/O
3968watchers, timers and monotonic clock support.
3969
3970With an intelligent-enough linker (gcc+binutils are intelligent enough
3971when you use C<-Wl,--gc-sections -ffunction-sections>) functions unused by
3972your program might be left out as well - a binary starting a timer and an
3973I/O watcher then might come out at only 5Kb.
3974
3975=item EV_AVOID_STDIO
3976
3977If this is set to C<1> at compiletime, then libev will avoid using stdio
3978functions (printf, scanf, perror etc.). This will increase the codesize
3979somewhat, but if your program doesn't otherwise depend on stdio and your
3980libc allows it, this avoids linking in the stdio library which is quite
3981big.
3982
3983Note that error messages might become less precise when this option is
3984enabled.
3985
3986=item EV_NSIG
3987
3988The highest supported signal number, +1 (or, the number of
3989signals): Normally, libev tries to deduce the maximum number of signals
3990automatically, but sometimes this fails, in which case it can be
3991specified. Also, using a lower number than detected (C<32> should be
3992good for about any system in existance) can save some memory, as libev
3993statically allocates some 12-24 bytes per signal number.
3502 3994
3503=item EV_PID_HASHSIZE 3995=item EV_PID_HASHSIZE
3504 3996
3505C<ev_child> watchers use a small hash table to distribute workload by 3997C<ev_child> watchers use a small hash table to distribute workload by
3506pid. The default size is C<16> (or C<1> with C<EV_MINIMAL>), usually more 3998pid. The default size is C<16> (or C<1> with C<EV_FEATURES> disabled),
3507than enough. If you need to manage thousands of children you might want to 3999usually more than enough. If you need to manage thousands of children you
3508increase this value (I<must> be a power of two). 4000might want to increase this value (I<must> be a power of two).
3509 4001
3510=item EV_INOTIFY_HASHSIZE 4002=item EV_INOTIFY_HASHSIZE
3511 4003
3512C<ev_stat> watchers use a small hash table to distribute workload by 4004C<ev_stat> watchers use a small hash table to distribute workload by
3513inotify watch id. The default size is C<16> (or C<1> with C<EV_MINIMAL>), 4005inotify watch id. The default size is C<16> (or C<1> with C<EV_FEATURES>
3514usually more than enough. If you need to manage thousands of C<ev_stat> 4006disabled), usually more than enough. If you need to manage thousands of
3515watchers you might want to increase this value (I<must> be a power of 4007C<ev_stat> watchers you might want to increase this value (I<must> be a
3516two). 4008power of two).
3517 4009
3518=item EV_USE_4HEAP 4010=item EV_USE_4HEAP
3519 4011
3520Heaps are not very cache-efficient. To improve the cache-efficiency of the 4012Heaps are not very cache-efficient. To improve the cache-efficiency of the
3521timer and periodics heaps, libev uses a 4-heap when this symbol is defined 4013timer and periodics heaps, libev uses a 4-heap when this symbol is defined
3522to C<1>. The 4-heap uses more complicated (longer) code but has noticeably 4014to C<1>. The 4-heap uses more complicated (longer) code but has noticeably
3523faster performance with many (thousands) of watchers. 4015faster performance with many (thousands) of watchers.
3524 4016
3525The default is C<1> unless C<EV_MINIMAL> is set in which case it is C<0> 4017The default is C<1>, unless C<EV_FEATURES> overrides it, in which case it
3526(disabled). 4018will be C<0>.
3527 4019
3528=item EV_HEAP_CACHE_AT 4020=item EV_HEAP_CACHE_AT
3529 4021
3530Heaps are not very cache-efficient. To improve the cache-efficiency of the 4022Heaps are not very cache-efficient. To improve the cache-efficiency of the
3531timer and periodics heaps, libev can cache the timestamp (I<at>) within 4023timer and periodics heaps, libev can cache the timestamp (I<at>) within
3532the heap structure (selected by defining C<EV_HEAP_CACHE_AT> to C<1>), 4024the heap structure (selected by defining C<EV_HEAP_CACHE_AT> to C<1>),
3533which uses 8-12 bytes more per watcher and a few hundred bytes more code, 4025which uses 8-12 bytes more per watcher and a few hundred bytes more code,
3534but avoids random read accesses on heap changes. This improves performance 4026but avoids random read accesses on heap changes. This improves performance
3535noticeably with many (hundreds) of watchers. 4027noticeably with many (hundreds) of watchers.
3536 4028
3537The default is C<1> unless C<EV_MINIMAL> is set in which case it is C<0> 4029The default is C<1>, unless C<EV_FEATURES> overrides it, in which case it
3538(disabled). 4030will be C<0>.
3539 4031
3540=item EV_VERIFY 4032=item EV_VERIFY
3541 4033
3542Controls how much internal verification (see C<ev_loop_verify ()>) will 4034Controls how much internal verification (see C<ev_loop_verify ()>) will
3543be done: If set to C<0>, no internal verification code will be compiled 4035be done: If set to C<0>, no internal verification code will be compiled
3545called. If set to C<2>, then the internal verification code will be 4037called. If set to C<2>, then the internal verification code will be
3546called once per loop, which can slow down libev. If set to C<3>, then the 4038called once per loop, which can slow down libev. If set to C<3>, then the
3547verification code will be called very frequently, which will slow down 4039verification code will be called very frequently, which will slow down
3548libev considerably. 4040libev considerably.
3549 4041
3550The default is C<1>, unless C<EV_MINIMAL> is set, in which case it will be 4042The default is C<1>, unless C<EV_FEATURES> overrides it, in which case it
3551C<0>. 4043will be C<0>.
3552 4044
3553=item EV_COMMON 4045=item EV_COMMON
3554 4046
3555By default, all watchers have a C<void *data> member. By redefining 4047By default, all watchers have a C<void *data> member. By redefining
3556this macro to a something else you can include more and other types of 4048this macro to a something else you can include more and other types of
3614file. 4106file.
3615 4107
3616The usage in rxvt-unicode is simpler. It has a F<ev_cpp.h> header file 4108The usage in rxvt-unicode is simpler. It has a F<ev_cpp.h> header file
3617that everybody includes and which overrides some configure choices: 4109that everybody includes and which overrides some configure choices:
3618 4110
3619 #define EV_MINIMAL 1 4111 #define EV_FEATURES 8
3620 #define EV_USE_POLL 0 4112 #define EV_USE_SELECT 1
3621 #define EV_MULTIPLICITY 0
3622 #define EV_PERIODIC_ENABLE 0 4113 #define EV_PREPARE_ENABLE 1
4114 #define EV_IDLE_ENABLE 1
3623 #define EV_STAT_ENABLE 0 4115 #define EV_SIGNAL_ENABLE 1
3624 #define EV_FORK_ENABLE 0 4116 #define EV_CHILD_ENABLE 1
4117 #define EV_USE_STDEXCEPT 0
3625 #define EV_CONFIG_H <config.h> 4118 #define EV_CONFIG_H <config.h>
3626 #define EV_MINPRI 0
3627 #define EV_MAXPRI 0
3628 4119
3629 #include "ev++.h" 4120 #include "ev++.h"
3630 4121
3631And a F<ev_cpp.C> implementation file that contains libev proper and is compiled: 4122And a F<ev_cpp.C> implementation file that contains libev proper and is compiled:
3632 4123
3692default loop and triggering an C<ev_async> watcher from the default loop 4183default loop and triggering an C<ev_async> watcher from the default loop
3693watcher callback into the event loop interested in the signal. 4184watcher callback into the event loop interested in the signal.
3694 4185
3695=back 4186=back
3696 4187
4188=head4 THREAD LOCKING EXAMPLE
4189
4190Here is a fictitious example of how to run an event loop in a different
4191thread than where callbacks are being invoked and watchers are
4192created/added/removed.
4193
4194For a real-world example, see the C<EV::Loop::Async> perl module,
4195which uses exactly this technique (which is suited for many high-level
4196languages).
4197
4198The example uses a pthread mutex to protect the loop data, a condition
4199variable to wait for callback invocations, an async watcher to notify the
4200event loop thread and an unspecified mechanism to wake up the main thread.
4201
4202First, you need to associate some data with the event loop:
4203
4204 typedef struct {
4205 mutex_t lock; /* global loop lock */
4206 ev_async async_w;
4207 thread_t tid;
4208 cond_t invoke_cv;
4209 } userdata;
4210
4211 void prepare_loop (EV_P)
4212 {
4213 // for simplicity, we use a static userdata struct.
4214 static userdata u;
4215
4216 ev_async_init (&u->async_w, async_cb);
4217 ev_async_start (EV_A_ &u->async_w);
4218
4219 pthread_mutex_init (&u->lock, 0);
4220 pthread_cond_init (&u->invoke_cv, 0);
4221
4222 // now associate this with the loop
4223 ev_set_userdata (EV_A_ u);
4224 ev_set_invoke_pending_cb (EV_A_ l_invoke);
4225 ev_set_loop_release_cb (EV_A_ l_release, l_acquire);
4226
4227 // then create the thread running ev_loop
4228 pthread_create (&u->tid, 0, l_run, EV_A);
4229 }
4230
4231The callback for the C<ev_async> watcher does nothing: the watcher is used
4232solely to wake up the event loop so it takes notice of any new watchers
4233that might have been added:
4234
4235 static void
4236 async_cb (EV_P_ ev_async *w, int revents)
4237 {
4238 // just used for the side effects
4239 }
4240
4241The C<l_release> and C<l_acquire> callbacks simply unlock/lock the mutex
4242protecting the loop data, respectively.
4243
4244 static void
4245 l_release (EV_P)
4246 {
4247 userdata *u = ev_userdata (EV_A);
4248 pthread_mutex_unlock (&u->lock);
4249 }
4250
4251 static void
4252 l_acquire (EV_P)
4253 {
4254 userdata *u = ev_userdata (EV_A);
4255 pthread_mutex_lock (&u->lock);
4256 }
4257
4258The event loop thread first acquires the mutex, and then jumps straight
4259into C<ev_loop>:
4260
4261 void *
4262 l_run (void *thr_arg)
4263 {
4264 struct ev_loop *loop = (struct ev_loop *)thr_arg;
4265
4266 l_acquire (EV_A);
4267 pthread_setcanceltype (PTHREAD_CANCEL_ASYNCHRONOUS, 0);
4268 ev_loop (EV_A_ 0);
4269 l_release (EV_A);
4270
4271 return 0;
4272 }
4273
4274Instead of invoking all pending watchers, the C<l_invoke> callback will
4275signal the main thread via some unspecified mechanism (signals? pipe
4276writes? C<Async::Interrupt>?) and then waits until all pending watchers
4277have been called (in a while loop because a) spurious wakeups are possible
4278and b) skipping inter-thread-communication when there are no pending
4279watchers is very beneficial):
4280
4281 static void
4282 l_invoke (EV_P)
4283 {
4284 userdata *u = ev_userdata (EV_A);
4285
4286 while (ev_pending_count (EV_A))
4287 {
4288 wake_up_other_thread_in_some_magic_or_not_so_magic_way ();
4289 pthread_cond_wait (&u->invoke_cv, &u->lock);
4290 }
4291 }
4292
4293Now, whenever the main thread gets told to invoke pending watchers, it
4294will grab the lock, call C<ev_invoke_pending> and then signal the loop
4295thread to continue:
4296
4297 static void
4298 real_invoke_pending (EV_P)
4299 {
4300 userdata *u = ev_userdata (EV_A);
4301
4302 pthread_mutex_lock (&u->lock);
4303 ev_invoke_pending (EV_A);
4304 pthread_cond_signal (&u->invoke_cv);
4305 pthread_mutex_unlock (&u->lock);
4306 }
4307
4308Whenever you want to start/stop a watcher or do other modifications to an
4309event loop, you will now have to lock:
4310
4311 ev_timer timeout_watcher;
4312 userdata *u = ev_userdata (EV_A);
4313
4314 ev_timer_init (&timeout_watcher, timeout_cb, 5.5, 0.);
4315
4316 pthread_mutex_lock (&u->lock);
4317 ev_timer_start (EV_A_ &timeout_watcher);
4318 ev_async_send (EV_A_ &u->async_w);
4319 pthread_mutex_unlock (&u->lock);
4320
4321Note that sending the C<ev_async> watcher is required because otherwise
4322an event loop currently blocking in the kernel will have no knowledge
4323about the newly added timer. By waking up the loop it will pick up any new
4324watchers in the next event loop iteration.
4325
3697=head3 COROUTINES 4326=head3 COROUTINES
3698 4327
3699Libev is very accommodating to coroutines ("cooperative threads"): 4328Libev is very accommodating to coroutines ("cooperative threads"):
3700libev fully supports nesting calls to its functions from different 4329libev fully supports nesting calls to its functions from different
3701coroutines (e.g. you can call C<ev_loop> on the same loop from two 4330coroutines (e.g. you can call C<ev_loop> on the same loop from two
3702different coroutines, and switch freely between both coroutines running the 4331different coroutines, and switch freely between both coroutines running
3703loop, as long as you don't confuse yourself). The only exception is that 4332the loop, as long as you don't confuse yourself). The only exception is
3704you must not do this from C<ev_periodic> reschedule callbacks. 4333that you must not do this from C<ev_periodic> reschedule callbacks.
3705 4334
3706Care has been taken to ensure that libev does not keep local state inside 4335Care has been taken to ensure that libev does not keep local state inside
3707C<ev_loop>, and other calls do not usually allow for coroutine switches as 4336C<ev_loop>, and other calls do not usually allow for coroutine switches as
3708they do not call any callbacks. 4337they do not call any callbacks.
3709 4338
3786way (note also that glib is the slowest event library known to man). 4415way (note also that glib is the slowest event library known to man).
3787 4416
3788There is no supported compilation method available on windows except 4417There is no supported compilation method available on windows except
3789embedding it into other applications. 4418embedding it into other applications.
3790 4419
4420Sensible signal handling is officially unsupported by Microsoft - libev
4421tries its best, but under most conditions, signals will simply not work.
4422
3791Not a libev limitation but worth mentioning: windows apparently doesn't 4423Not a libev limitation but worth mentioning: windows apparently doesn't
3792accept large writes: instead of resulting in a partial write, windows will 4424accept large writes: instead of resulting in a partial write, windows will
3793either accept everything or return C<ENOBUFS> if the buffer is too large, 4425either accept everything or return C<ENOBUFS> if the buffer is too large,
3794so make sure you only write small amounts into your sockets (less than a 4426so make sure you only write small amounts into your sockets (less than a
3795megabyte seems safe, but this apparently depends on the amount of memory 4427megabyte seems safe, but this apparently depends on the amount of memory
3799the abysmal performance of winsockets, using a large number of sockets 4431the abysmal performance of winsockets, using a large number of sockets
3800is not recommended (and not reasonable). If your program needs to use 4432is not recommended (and not reasonable). If your program needs to use
3801more than a hundred or so sockets, then likely it needs to use a totally 4433more than a hundred or so sockets, then likely it needs to use a totally
3802different implementation for windows, as libev offers the POSIX readiness 4434different implementation for windows, as libev offers the POSIX readiness
3803notification model, which cannot be implemented efficiently on windows 4435notification model, which cannot be implemented efficiently on windows
3804(Microsoft monopoly games). 4436(due to Microsoft monopoly games).
3805 4437
3806A typical way to use libev under windows is to embed it (see the embedding 4438A typical way to use libev under windows is to embed it (see the embedding
3807section for details) and use the following F<evwrap.h> header file instead 4439section for details) and use the following F<evwrap.h> header file instead
3808of F<ev.h>: 4440of F<ev.h>:
3809 4441
3845 4477
3846Early versions of winsocket's select only supported waiting for a maximum 4478Early versions of winsocket's select only supported waiting for a maximum
3847of C<64> handles (probably owning to the fact that all windows kernels 4479of C<64> handles (probably owning to the fact that all windows kernels
3848can only wait for C<64> things at the same time internally; Microsoft 4480can only wait for C<64> things at the same time internally; Microsoft
3849recommends spawning a chain of threads and wait for 63 handles and the 4481recommends spawning a chain of threads and wait for 63 handles and the
3850previous thread in each. Great). 4482previous thread in each. Sounds great!).
3851 4483
3852Newer versions support more handles, but you need to define C<FD_SETSIZE> 4484Newer versions support more handles, but you need to define C<FD_SETSIZE>
3853to some high number (e.g. C<2048>) before compiling the winsocket select 4485to some high number (e.g. C<2048>) before compiling the winsocket select
3854call (which might be in libev or elsewhere, for example, perl does its own 4486call (which might be in libev or elsewhere, for example, perl and many
3855select emulation on windows). 4487other interpreters do their own select emulation on windows).
3856 4488
3857Another limit is the number of file descriptors in the Microsoft runtime 4489Another limit is the number of file descriptors in the Microsoft runtime
3858libraries, which by default is C<64> (there must be a hidden I<64> fetish 4490libraries, which by default is C<64> (there must be a hidden I<64>
3859or something like this inside Microsoft). You can increase this by calling 4491fetish or something like this inside Microsoft). You can increase this
3860C<_setmaxstdio>, which can increase this limit to C<2048> (another 4492by calling C<_setmaxstdio>, which can increase this limit to C<2048>
3861arbitrary limit), but is broken in many versions of the Microsoft runtime 4493(another arbitrary limit), but is broken in many versions of the Microsoft
3862libraries.
3863
3864This might get you to about C<512> or C<2048> sockets (depending on 4494runtime libraries. This might get you to about C<512> or C<2048> sockets
3865windows version and/or the phase of the moon). To get more, you need to 4495(depending on windows version and/or the phase of the moon). To get more,
3866wrap all I/O functions and provide your own fd management, but the cost of 4496you need to wrap all I/O functions and provide your own fd management, but
3867calling select (O(n²)) will likely make this unworkable. 4497the cost of calling select (O(n²)) will likely make this unworkable.
3868 4498
3869=back 4499=back
3870 4500
3871=head2 PORTABILITY REQUIREMENTS 4501=head2 PORTABILITY REQUIREMENTS
3872 4502
3915=item C<double> must hold a time value in seconds with enough accuracy 4545=item C<double> must hold a time value in seconds with enough accuracy
3916 4546
3917The type C<double> is used to represent timestamps. It is required to 4547The type C<double> is used to represent timestamps. It is required to
3918have at least 51 bits of mantissa (and 9 bits of exponent), which is good 4548have at least 51 bits of mantissa (and 9 bits of exponent), which is good
3919enough for at least into the year 4000. This requirement is fulfilled by 4549enough for at least into the year 4000. This requirement is fulfilled by
3920implementations implementing IEEE 754 (basically all existing ones). 4550implementations implementing IEEE 754, which is basically all existing
4551ones. With IEEE 754 doubles, you get microsecond accuracy until at least
45522200.
3921 4553
3922=back 4554=back
3923 4555
3924If you know of other additional requirements drop me a note. 4556If you know of other additional requirements drop me a note.
3925 4557
3993involves iterating over all running async watchers or all signal numbers. 4625involves iterating over all running async watchers or all signal numbers.
3994 4626
3995=back 4627=back
3996 4628
3997 4629
4630=head1 PORTING FROM LIBEV 3.X TO 4.X
4631
4632The major version 4 introduced some minor incompatible changes to the API.
4633
4634At the moment, the C<ev.h> header file tries to implement superficial
4635compatibility, so most programs should still compile. Those might be
4636removed in later versions of libev, so better update early than late.
4637
4638=over 4
4639
4640=item C<ev_loop_count> renamed to C<ev_iteration>
4641
4642=item C<ev_loop_depth> renamed to C<ev_depth>
4643
4644=item C<ev_loop_verify> renamed to C<ev_verify>
4645
4646Most functions working on C<struct ev_loop> objects don't have an
4647C<ev_loop_> prefix, so it was removed. Note that C<ev_loop_fork> is
4648still called C<ev_loop_fork> because it would otherwise clash with the
4649C<ev_fork> typedef.
4650
4651=item C<EV_TIMEOUT> renamed to C<EV_TIMER> in C<revents>
4652
4653This is a simple rename - all other watcher types use their name
4654as revents flag, and now C<ev_timer> does, too.
4655
4656Both C<EV_TIMER> and C<EV_TIMEOUT> symbols were present in 3.x versions
4657and continue to be present for the forseeable future, so this is mostly a
4658documentation change.
4659
4660=item C<EV_MINIMAL> mechanism replaced by C<EV_FEATURES>
4661
4662The preprocessor symbol C<EV_MINIMAL> has been replaced by a different
4663mechanism, C<EV_FEATURES>. Programs using C<EV_MINIMAL> usually compile
4664and work, but the library code will of course be larger.
4665
4666=back
4667
4668
4669=head1 GLOSSARY
4670
4671=over 4
4672
4673=item active
4674
4675A watcher is active as long as it has been started (has been attached to
4676an event loop) but not yet stopped (disassociated from the event loop).
4677
4678=item application
4679
4680In this document, an application is whatever is using libev.
4681
4682=item callback
4683
4684The address of a function that is called when some event has been
4685detected. Callbacks are being passed the event loop, the watcher that
4686received the event, and the actual event bitset.
4687
4688=item callback invocation
4689
4690The act of calling the callback associated with a watcher.
4691
4692=item event
4693
4694A change of state of some external event, such as data now being available
4695for reading on a file descriptor, time having passed or simply not having
4696any other events happening anymore.
4697
4698In libev, events are represented as single bits (such as C<EV_READ> or
4699C<EV_TIMER>).
4700
4701=item event library
4702
4703A software package implementing an event model and loop.
4704
4705=item event loop
4706
4707An entity that handles and processes external events and converts them
4708into callback invocations.
4709
4710=item event model
4711
4712The model used to describe how an event loop handles and processes
4713watchers and events.
4714
4715=item pending
4716
4717A watcher is pending as soon as the corresponding event has been detected,
4718and stops being pending as soon as the watcher will be invoked or its
4719pending status is explicitly cleared by the application.
4720
4721A watcher can be pending, but not active. Stopping a watcher also clears
4722its pending status.
4723
4724=item real time
4725
4726The physical time that is observed. It is apparently strictly monotonic :)
4727
4728=item wall-clock time
4729
4730The time and date as shown on clocks. Unlike real time, it can actually
4731be wrong and jump forwards and backwards, e.g. when the you adjust your
4732clock.
4733
4734=item watcher
4735
4736A data structure that describes interest in certain events. Watchers need
4737to be started (attached to an event loop) before they can receive events.
4738
4739=item watcher invocation
4740
4741The act of calling the callback associated with a watcher.
4742
4743=back
4744
3998=head1 AUTHOR 4745=head1 AUTHOR
3999 4746
4000Marc Lehmann <libev@schmorp.de>, with repeated corrections by Mikael Magnusson. 4747Marc Lehmann <libev@schmorp.de>, with repeated corrections by Mikael Magnusson.
4001 4748

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines