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

Comparing libev/ev.pod (file contents):
Revision 1.67 by root, Fri Dec 7 16:44:12 2007 UTC vs.
Revision 1.69 by root, Fri Dec 7 19:15:39 2007 UTC

… …
47 47
48 return 0; 48 return 0;
49 } 49 }
50 50
51=head1 DESCRIPTION 51=head1 DESCRIPTION
52
53The newest version of this document is also available as a html-formatted
54web page you might find easier to navigate when reading it for the first
55time: L<http://cvs.schmorp.de/libev/ev.html>.
52 56
53Libev is an event loop: you register interest in certain events (such as a 57Libev is an event loop: you register interest in certain events (such as a
54file descriptor being readable or a timeout occuring), and it will manage 58file descriptor being readable or a timeout occuring), and it will manage
55these event sources and provide your program with events. 59these event sources and provide your program with events.
56 60
… …
883it is best to always use non-blocking I/O: An extra C<read>(2) returning 887it is best to always use non-blocking I/O: An extra C<read>(2) returning
884C<EAGAIN> is far preferable to a program hanging until some data arrives. 888C<EAGAIN> is far preferable to a program hanging until some data arrives.
885 889
886If you cannot run the fd in non-blocking mode (for example you should not 890If you cannot run the fd in non-blocking mode (for example you should not
887play around with an Xlib connection), then you have to seperately re-test 891play around with an Xlib connection), then you have to seperately re-test
888wether a file descriptor is really ready with a known-to-be good interface 892whether a file descriptor is really ready with a known-to-be good interface
889such as poll (fortunately in our Xlib example, Xlib already does this on 893such as poll (fortunately in our Xlib example, Xlib already does this on
890its own, so its quite safe to use). 894its own, so its quite safe to use).
891 895
892=over 4 896=over 4
893 897
… …
1844 1848
1845 1849
1846=head1 MACRO MAGIC 1850=head1 MACRO MAGIC
1847 1851
1848Libev can be compiled with a variety of options, the most fundemantal is 1852Libev can be compiled with a variety of options, the most fundemantal is
1849C<EV_MULTIPLICITY>. This option determines wether (most) functions and 1853C<EV_MULTIPLICITY>. This option determines whether (most) functions and
1850callbacks have an initial C<struct ev_loop *> argument. 1854callbacks have an initial C<struct ev_loop *> argument.
1851 1855
1852To make it easier to write programs that cope with either variant, the 1856To make it easier to write programs that cope with either variant, the
1853following macros are defined: 1857following macros are defined:
1854 1858
… …
1888loop, if multiple loops are supported ("ev loop default"). 1892loop, if multiple loops are supported ("ev loop default").
1889 1893
1890=back 1894=back
1891 1895
1892Example: Declare and initialise a check watcher, utilising the above 1896Example: Declare and initialise a check watcher, utilising the above
1893macros so it will work regardless of wether multiple loops are supported 1897macros so it will work regardless of whether multiple loops are supported
1894or not. 1898or not.
1895 1899
1896 static void 1900 static void
1897 check_cb (EV_P_ ev_timer *w, int revents) 1901 check_cb (EV_P_ ev_timer *w, int revents)
1898 { 1902 {
… …
2123will have the C<struct ev_loop *> as first argument, and you can create 2127will have the C<struct ev_loop *> as first argument, and you can create
2124additional independent event loops. Otherwise there will be no support 2128additional independent event loops. Otherwise there will be no support
2125for multiple event loops and there is no first event loop pointer 2129for multiple event loops and there is no first event loop pointer
2126argument. Instead, all functions act on the single default loop. 2130argument. Instead, all functions act on the single default loop.
2127 2131
2132=item EV_MINPRI
2133
2134=item EV_MAXPRI
2135
2136The range of allowed priorities. C<EV_MINPRI> must be smaller or equal to
2137C<EV_MAXPRI>, but otherwise there are no non-obvious limitations. You can
2138provide for more priorities by overriding those symbols (usually defined
2139to be C<-2> and C<2>, respectively).
2140
2141When doing priority-based operations, libev usually has to linearly search
2142all the priorities, so having many of them (hundreds) uses a lot of space
2143and time, so using the defaults of five priorities (-2 .. +2) is usually
2144fine.
2145
2146If your embedding app does not need any priorities, defining these both to
2147C<0> will save some memory and cpu.
2148
2128=item EV_PERIODIC_ENABLE 2149=item EV_PERIODIC_ENABLE
2129 2150
2130If undefined or defined to be C<1>, then periodic timers are supported. If 2151If undefined or defined to be C<1>, then periodic timers are supported. If
2131defined to be C<0>, then they are not. Disabling them saves a few kB of 2152defined to be C<0>, then they are not. Disabling them saves a few kB of
2132code. 2153code.
… …
2238 2259
2239=over 4 2260=over 4
2240 2261
2241=item Starting and stopping timer/periodic watchers: O(log skipped_other_timers) 2262=item Starting and stopping timer/periodic watchers: O(log skipped_other_timers)
2242 2263
2264This means that, when you have a watcher that triggers in one hour and
2265there are 100 watchers that would trigger before that then inserting will
2266have to skip those 100 watchers.
2267
2243=item Changing timer/periodic watchers (by autorepeat, again): O(log skipped_other_timers) 2268=item Changing timer/periodic watchers (by autorepeat, again): O(log skipped_other_timers)
2244 2269
2270That means that for changing a timer costs less than removing/adding them
2271as only the relative motion in the event queue has to be paid for.
2272
2245=item Starting io/check/prepare/idle/signal/child watchers: O(1) 2273=item Starting io/check/prepare/idle/signal/child watchers: O(1)
2246 2274
2275These just add the watcher into an array or at the head of a list. If
2276the array needs to be extended libev needs to realloc and move the whole
2277array, but this happen asymptotically less and less with more watchers,
2278thus amortised O(1).
2279
2247=item Stopping check/prepare/idle watchers: O(1) 2280=item Stopping check/prepare/idle watchers: O(1)
2248 2281
2249=item Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % EV_PID_HASHSIZE)) 2282=item Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % EV_PID_HASHSIZE))
2250 2283
2284These watchers are stored in lists then need to be walked to find the
2285correct watcher to remove. The lists are usually short (you don't usually
2286have many watchers waiting for the same fd or signal).
2287
2251=item Finding the next timer per loop iteration: O(1) 2288=item Finding the next timer per loop iteration: O(1)
2252 2289
2253=item Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd) 2290=item Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd)
2254 2291
2292A change means an I/O watcher gets started or stopped, which requires
2293libev to recalculate its status (and possibly tell the kernel).
2294
2255=item Activating one watcher: O(1) 2295=item Activating one watcher: O(1)
2256 2296
2297=item Priority handling: O(number_of_priorities)
2298
2299Priorities are implemented by allocating some space for each
2300priority. When doing priority-based operations, libev usually has to
2301linearly search all the priorities.
2302
2257=back 2303=back
2258 2304
2259 2305
2260=head1 AUTHOR 2306=head1 AUTHOR
2261 2307

Diff Legend

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