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

Comparing libev/ev.pod (file contents):
Revision 1.285 by root, Tue Mar 16 00:20:17 2010 UTC vs.
Revision 1.289 by root, Tue Mar 16 17:11:49 2010 UTC

1032=item C<EV_WRITE> 1032=item C<EV_WRITE>
1033 1033
1034The file descriptor in the C<ev_io> watcher has become readable and/or 1034The file descriptor in the C<ev_io> watcher has become readable and/or
1035writable. 1035writable.
1036 1036
1037=item C<EV_TIMEOUT> 1037=item C<EV_TIMER>
1038 1038
1039The C<ev_timer> watcher has timed out. 1039The C<ev_timer> watcher has timed out.
1040 1040
1041=item C<EV_PERIODIC> 1041=item C<EV_PERIODIC>
1042 1042
1764to the current time (meaning we just have some activity :), then call the 1764to the current time (meaning we just have some activity :), then call the
1765callback, which will "do the right thing" and start the timer: 1765callback, which will "do the right thing" and start the timer:
1766 1766
1767 ev_init (timer, callback); 1767 ev_init (timer, callback);
1768 last_activity = ev_now (loop); 1768 last_activity = ev_now (loop);
1769 callback (loop, timer, EV_TIMEOUT); 1769 callback (loop, timer, EV_TIMER);
1770 1770
1771And when there is some activity, simply store the current time in 1771And when there is some activity, simply store the current time in
1772C<last_activity>, no libev calls at all: 1772C<last_activity>, no libev calls at all:
1773 1773
1774 last_actiivty = ev_now (loop); 1774 last_actiivty = ev_now (loop);
3179 3179
3180If C<timeout> is less than 0, then no timeout watcher will be 3180If C<timeout> is less than 0, then no timeout watcher will be
3181started. Otherwise an C<ev_timer> watcher with after = C<timeout> (and 3181started. Otherwise an C<ev_timer> watcher with after = C<timeout> (and
3182repeat = 0) will be started. C<0> is a valid timeout. 3182repeat = 0) will be started. C<0> is a valid timeout.
3183 3183
3184The callback has the type C<void (*cb)(int revents, void *arg)> and gets 3184The callback has the type C<void (*cb)(int revents, void *arg)> and is
3185passed an C<revents> set like normal event callbacks (a combination of 3185passed an C<revents> set like normal event callbacks (a combination of
3186C<EV_ERROR>, C<EV_READ>, C<EV_WRITE> or C<EV_TIMEOUT>) and the C<arg> 3186C<EV_ERROR>, C<EV_READ>, C<EV_WRITE> or C<EV_TIMER>) and the C<arg>
3187value passed to C<ev_once>. Note that it is possible to receive I<both> 3187value passed to C<ev_once>. Note that it is possible to receive I<both>
3188a timeout and an io event at the same time - you probably should give io 3188a timeout and an io event at the same time - you probably should give io
3189events precedence. 3189events precedence.
3190 3190
3191Example: wait up to ten seconds for data to appear on STDIN_FILENO. 3191Example: wait up to ten seconds for data to appear on STDIN_FILENO.
3192 3192
3193 static void stdin_ready (int revents, void *arg) 3193 static void stdin_ready (int revents, void *arg)
3194 { 3194 {
3195 if (revents & EV_READ) 3195 if (revents & EV_READ)
3196 /* stdin might have data for us, joy! */; 3196 /* stdin might have data for us, joy! */;
3197 else if (revents & EV_TIMEOUT) 3197 else if (revents & EV_TIMER)
3198 /* doh, nothing entered */; 3198 /* doh, nothing entered */;
3199 } 3199 }
3200 3200
3201 ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0); 3201 ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0);
3202 3202
3891If you need to shave off some kilobytes of code at the expense of some 3891If you need to shave off some kilobytes of code at the expense of some
3892speed (but with the full API), you can define this symbol to request 3892speed (but with the full API), you can define this symbol to request
3893certain subsets of functionality. The default is to enable all features 3893certain subsets of functionality. The default is to enable all features
3894that can be enabled on the platform. 3894that can be enabled on the platform.
3895 3895
3896Note that using autoconf will usually override most of the features, so
3897using this symbol makes sense mostly when embedding libev.
3898
3899A typical way to use this symbol is to define it to C<0> (or to a bitset 3896A typical way to use this symbol is to define it to C<0> (or to a bitset
3900with some broad features you want) and then selectively re-enable 3897with some broad features you want) and then selectively re-enable
3901additional parts you want, for example if you want everything minimal, 3898additional parts you want, for example if you want everything minimal,
3902but multiple event loop support, async and child watchers and the poll 3899but multiple event loop support, async and child watchers and the poll
3903backend, use this: 3900backend, use this:
3918Use larger code to speed up some operations. 3915Use larger code to speed up some operations.
3919 3916
3920Currently this is used to override some inlining decisions (enlarging the roughly 3917Currently this is used to override some inlining decisions (enlarging the roughly
392130% code size on amd64. 391830% code size on amd64.
3922 3919
3923Also disables C<assert>'s in the code, unless you define C<NDEBUG> 3920When optimising for size, use of compiler flags such as C<-Os> with
3924explicitly to C<0>. 3921gcc recommended, as well as C<-DNDEBUG>, as libev contains a number of
3925 3922assertions.
3926Use of compiler flags such as C<-Os> with gcc that optimise for size are
3927recommended when disabling this feature.
3928 3923
3929=item C<2> - faster/larger data structures 3924=item C<2> - faster/larger data structures
3930 3925
3931Replaces the small 2-heap for timer management by a faster 4-heap, larger 3926Replaces the small 2-heap for timer management by a faster 4-heap, larger
3932hash table sizes and so on. This will usually further increase codesize 3927hash table sizes and so on. This will usually further increase codesize
3936=item C<4> - full API configuration 3931=item C<4> - full API configuration
3937 3932
3938This enables priorities (sets C<EV_MAXPRI>=2 and C<EV_MINPRI>=-2), and 3933This enables priorities (sets C<EV_MAXPRI>=2 and C<EV_MINPRI>=-2), and
3939enables multiplicity (C<EV_MULTIPLICITY>=1). 3934enables multiplicity (C<EV_MULTIPLICITY>=1).
3940 3935
3936=item C<8> - full API
3937
3941It also enables a lot of the "lesser used" core API functions. See C<ev.h> 3938This enables a lot of the "lesser used" API functions. See C<ev.h> for
3942for details on which parts of the API are still available without this 3939details on which parts of the API are still available without this
3943feature, and do not complain if this subset changes over time. 3940feature, and do not complain if this subset changes over time.
3944 3941
3945=item C<8> - enable all optional watcher types 3942=item C<16> - enable all optional watcher types
3946 3943
3947Enables all optional watcher types. If you want to selectively enable 3944Enables all optional watcher types. If you want to selectively enable
3948only some watcher types other than I/O and timers (e.g. prepare, 3945only some watcher types other than I/O and timers (e.g. prepare,
3949embed, async, child...) you can enable them manually by defining 3946embed, async, child...) you can enable them manually by defining
3950C<EV_watchertype_ENABLE> to C<1> instead. 3947C<EV_watchertype_ENABLE> to C<1> instead.
3951 3948
3952=item C<16> - enable all backends 3949=item C<32> - enable all backends
3953 3950
3954This enables all backends - without this feature, you need to enable at 3951This enables all backends - without this feature, you need to enable at
3955least one backend manually (C<EV_USE_SELECT> is a good choice). 3952least one backend manually (C<EV_USE_SELECT> is a good choice).
3956 3953
3957=item C<32> - enable OS-specific "helper" APIs 3954=item C<64> - enable OS-specific "helper" APIs
3958 3955
3959Enable inotify, eventfd, signalfd and similar OS-specific helper APIs by 3956Enable inotify, eventfd, signalfd and similar OS-specific helper APIs by
3960default. 3957default.
3961 3958
3962=back 3959=back
3963 3960
3964Compiling with C<gcc -Os -DEV_STANDALONE -DEV_USE_EPOLL=1 -DEV_FEATURES=0> 3961Compiling with C<gcc -Os -DEV_STANDALONE -DEV_USE_EPOLL=1 -DEV_FEATURES=0>
3965reduces the compiled size of libev from 24.7Kb to 6.5Kb on my GNU/Linux 3962reduces the compiled size of libev from 24.7Kb code/2.8Kb data to 6.5Kb
3966amd64 system, while still giving you I/O watchers, timers and monotonic 3963code/0.3Kb data on my GNU/Linux amd64 system, while still giving you I/O
3967clock support. 3964watchers, timers and monotonic clock support.
3968 3965
3969With an intelligent-enough linker (gcc+binutils are intelligent enough 3966With an intelligent-enough linker (gcc+binutils are intelligent enough
3970when you use C<-Wl,--gc-sections -ffunction-sections>) functions unused by 3967when you use C<-Wl,--gc-sections -ffunction-sections>) functions unused by
3971your program might be left out as well - a binary starting a timer and an 3968your program might be left out as well - a binary starting a timer and an
3972I/O watcher then might come out at only 5Kb. 3969I/O watcher then might come out at only 5Kb.
4105file. 4102file.
4106 4103
4107The usage in rxvt-unicode is simpler. It has a F<ev_cpp.h> header file 4104The usage in rxvt-unicode is simpler. It has a F<ev_cpp.h> header file
4108that everybody includes and which overrides some configure choices: 4105that everybody includes and which overrides some configure choices:
4109 4106
4110 #define EV_FEATURES 0 4107 #define EV_FEATURES 8
4111 #define EV_USE_SELECT 1 4108 #define EV_USE_SELECT 1
4109 #define EV_PREPARE_ENABLE 1
4110 #define EV_IDLE_ENABLE 1
4111 #define EV_SIGNAL_ENABLE 1
4112 #define EV_CHILD_ENABLE 1
4113 #define EV_USE_STDEXCEPT 0
4112 #define EV_CONFIG_H <config.h> 4114 #define EV_CONFIG_H <config.h>
4113 4115
4114 #include "ev++.h" 4116 #include "ev++.h"
4115 4117
4116And a F<ev_cpp.C> implementation file that contains libev proper and is compiled: 4118And a F<ev_cpp.C> implementation file that contains libev proper and is compiled:
4619involves iterating over all running async watchers or all signal numbers. 4621involves iterating over all running async watchers or all signal numbers.
4620 4622
4621=back 4623=back
4622 4624
4623 4625
4626=head1 PORTING FROM 3.X TO 4.X
4627
4628The major version 4 introduced some minor incompatible changes to the API.
4629
4630=over 4
4631
4632=item C<EV_TIMEOUT> replaced by C<EV_TIMER> in C<revents>
4633
4634This is a simple rename - all other watcher types use their name
4635as revents flag, and now C<ev_timer> does, too.
4636
4637Both C<EV_TIMER> and C<EV_TIMEOUT> symbols were present in 3.x versions
4638and continue to be present for the forseeable future, so this is mostly a
4639documentation change.
4640
4641=item C<EV_MINIMAL> mechanism replaced by C<EV_FEATURES>
4642
4643The preprocessor symbol C<EV_MINIMAL> has been replaced by a different
4644mechanism, C<EV_FEATURES>. Programs using C<EV_MINIMAL> usually compile
4645and work, but the library code will of course be larger.
4646
4647=back
4648
4649
4624=head1 GLOSSARY 4650=head1 GLOSSARY
4625 4651
4626=over 4 4652=over 4
4627 4653
4628=item active 4654=item active
4649A change of state of some external event, such as data now being available 4675A change of state of some external event, such as data now being available
4650for reading on a file descriptor, time having passed or simply not having 4676for reading on a file descriptor, time having passed or simply not having
4651any other events happening anymore. 4677any other events happening anymore.
4652 4678
4653In libev, events are represented as single bits (such as C<EV_READ> or 4679In libev, events are represented as single bits (such as C<EV_READ> or
4654C<EV_TIMEOUT>). 4680C<EV_TIMER>).
4655 4681
4656=item event library 4682=item event library
4657 4683
4658A software package implementing an event model and loop. 4684A software package implementing an event model and loop.
4659 4685

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines