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

Comparing libev/ev.pod (file contents):
Revision 1.103 by root, Sun Dec 23 03:44:57 2007 UTC vs.
Revision 1.106 by root, Sun Dec 23 03:57:55 2007 UTC

… …
4 4
5=head1 SYNOPSIS 5=head1 SYNOPSIS
6 6
7 #include <ev.h> 7 #include <ev.h>
8 8
9=head1 EXAMPLE PROGRAM 9=head2 EXAMPLE PROGRAM
10 10
11 #include <ev.h> 11 #include <ev.h>
12 12
13 ev_io stdin_watcher; 13 ev_io stdin_watcher;
14 ev_timer timeout_watcher; 14 ev_timer timeout_watcher;
… …
65You register interest in certain events by registering so-called I<event 65You register interest in certain events by registering so-called I<event
66watchers>, which are relatively small C structures you initialise with the 66watchers>, which are relatively small C structures you initialise with the
67details of the event, and then hand it over to libev by I<starting> the 67details of the event, and then hand it over to libev by I<starting> the
68watcher. 68watcher.
69 69
70=head1 FEATURES 70=head2 FEATURES
71 71
72Libev supports C<select>, C<poll>, the Linux-specific C<epoll>, the 72Libev supports C<select>, C<poll>, the Linux-specific C<epoll>, the
73BSD-specific C<kqueue> and the Solaris-specific event port mechanisms 73BSD-specific C<kqueue> and the Solaris-specific event port mechanisms
74for file descriptor events (C<ev_io>), the Linux C<inotify> interface 74for file descriptor events (C<ev_io>), the Linux C<inotify> interface
75(for C<ev_stat>), relative timers (C<ev_timer>), absolute timers 75(for C<ev_stat>), relative timers (C<ev_timer>), absolute timers
… …
82 82
83It also is quite fast (see this 83It also is quite fast (see this
84L<benchmark|http://libev.schmorp.de/bench.html> comparing it to libevent 84L<benchmark|http://libev.schmorp.de/bench.html> comparing it to libevent
85for example). 85for example).
86 86
87=head1 CONVENTIONS 87=head2 CONVENTIONS
88 88
89Libev is very configurable. In this manual the default configuration will 89Libev is very configurable. In this manual the default configuration will
90be described, which supports multiple event loops. For more info about 90be described, which supports multiple event loops. For more info about
91various configuration options please have a look at B<EMBED> section in 91various configuration options please have a look at B<EMBED> section in
92this manual. If libev was configured without support for multiple event 92this manual. If libev was configured without support for multiple event
93loops, then all functions taking an initial argument of name C<loop> 93loops, then all functions taking an initial argument of name C<loop>
94(which is always of type C<struct ev_loop *>) will not have this argument. 94(which is always of type C<struct ev_loop *>) will not have this argument.
95 95
96=head1 TIME REPRESENTATION 96=head2 TIME REPRESENTATION
97 97
98Libev represents time as a single floating point number, representing the 98Libev represents time as a single floating point number, representing the
99(fractional) number of seconds since the (POSIX) epoch (somewhere near 99(fractional) number of seconds since the (POSIX) epoch (somewhere near
100the beginning of 1970, details are complicated, don't ask). This type is 100the beginning of 1970, details are complicated, don't ask). This type is
101called C<ev_tstamp>, which is what you should use too. It usually aliases 101called C<ev_tstamp>, which is what you should use too. It usually aliases
… …
2526than enough. If you need to manage thousands of children you might want to 2526than enough. If you need to manage thousands of children you might want to
2527increase this value (I<must> be a power of two). 2527increase this value (I<must> be a power of two).
2528 2528
2529=item EV_INOTIFY_HASHSIZE 2529=item EV_INOTIFY_HASHSIZE
2530 2530
2531C<ev_staz> watchers use a small hash table to distribute workload by 2531C<ev_stat> watchers use a small hash table to distribute workload by
2532inotify watch id. The default size is C<16> (or C<1> with C<EV_MINIMAL>), 2532inotify watch id. The default size is C<16> (or C<1> with C<EV_MINIMAL>),
2533usually more than enough. If you need to manage thousands of C<ev_stat> 2533usually more than enough. If you need to manage thousands of C<ev_stat>
2534watchers you might want to increase this value (I<must> be a power of 2534watchers you might want to increase this value (I<must> be a power of
2535two). 2535two).
2536 2536
… …
2632 2632
2633=item Starting and stopping timer/periodic watchers: O(log skipped_other_timers) 2633=item Starting and stopping timer/periodic watchers: O(log skipped_other_timers)
2634 2634
2635This means that, when you have a watcher that triggers in one hour and 2635This means that, when you have a watcher that triggers in one hour and
2636there are 100 watchers that would trigger before that then inserting will 2636there are 100 watchers that would trigger before that then inserting will
2637have to skip those 100 watchers. 2637have to skip roughly seven (C<ld 100>) of these watchers.
2638 2638
2639=item Changing timer/periodic watchers (by autorepeat, again): O(log skipped_other_timers) 2639=item Changing timer/periodic watchers (by autorepeat or calling again): O(log skipped_other_timers)
2640 2640
2641That means that for changing a timer costs less than removing/adding them 2641That means that changing a timer costs less than removing/adding them
2642as only the relative motion in the event queue has to be paid for. 2642as only the relative motion in the event queue has to be paid for.
2643 2643
2644=item Starting io/check/prepare/idle/signal/child watchers: O(1) 2644=item Starting io/check/prepare/idle/signal/child watchers: O(1)
2645 2645
2646These just add the watcher into an array or at the head of a list. 2646These just add the watcher into an array or at the head of a list.
2647
2647=item Stopping check/prepare/idle watchers: O(1) 2648=item Stopping check/prepare/idle watchers: O(1)
2648 2649
2649=item Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % EV_PID_HASHSIZE)) 2650=item Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % EV_PID_HASHSIZE))
2650 2651
2651These watchers are stored in lists then need to be walked to find the 2652These watchers are stored in lists then need to be walked to find the
2652correct watcher to remove. The lists are usually short (you don't usually 2653correct watcher to remove. The lists are usually short (you don't usually
2653have many watchers waiting for the same fd or signal). 2654have many watchers waiting for the same fd or signal).
2654 2655
2655=item Finding the next timer per loop iteration: O(1) 2656=item Finding the next timer in each loop iteration: O(1)
2657
2658By virtue of using a binary heap, the next timer is always found at the
2659beginning of the storage array.
2656 2660
2657=item Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd) 2661=item Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd)
2658 2662
2659A change means an I/O watcher gets started or stopped, which requires 2663A change means an I/O watcher gets started or stopped, which requires
2660libev to recalculate its status (and possibly tell the kernel). 2664libev to recalculate its status (and possibly tell the kernel, depending
2665on backend and wether C<ev_io_set> was used).
2661 2666
2662=item Activating one watcher: O(1) 2667=item Activating one watcher (putting it into the pending state): O(1)
2663 2668
2664=item Priority handling: O(number_of_priorities) 2669=item Priority handling: O(number_of_priorities)
2665 2670
2666Priorities are implemented by allocating some space for each 2671Priorities are implemented by allocating some space for each
2667priority. When doing priority-based operations, libev usually has to 2672priority. When doing priority-based operations, libev usually has to
2668linearly search all the priorities. 2673linearly search all the priorities, but starting/stopping and activating
2674watchers becomes O(1) w.r.t. prioritiy handling.
2669 2675
2670=back 2676=back
2671 2677
2672 2678
2673=head1 AUTHOR 2679=head1 AUTHOR

Diff Legend

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