… | |
… | |
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; |
… | |
… | |
65 | You register interest in certain events by registering so-called I<event |
65 | You register interest in certain events by registering so-called I<event |
66 | watchers>, which are relatively small C structures you initialise with the |
66 | watchers>, which are relatively small C structures you initialise with the |
67 | details of the event, and then hand it over to libev by I<starting> the |
67 | details of the event, and then hand it over to libev by I<starting> the |
68 | watcher. |
68 | watcher. |
69 | |
69 | |
70 | =head1 FEATURES |
70 | =head2 FEATURES |
71 | |
71 | |
72 | Libev supports C<select>, C<poll>, the Linux-specific C<epoll>, the |
72 | Libev supports C<select>, C<poll>, the Linux-specific C<epoll>, the |
73 | BSD-specific C<kqueue> and the Solaris-specific event port mechanisms |
73 | BSD-specific C<kqueue> and the Solaris-specific event port mechanisms |
74 | for file descriptor events (C<ev_io>), the Linux C<inotify> interface |
74 | for 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 | |
83 | It also is quite fast (see this |
83 | It also is quite fast (see this |
84 | L<benchmark|http://libev.schmorp.de/bench.html> comparing it to libevent |
84 | L<benchmark|http://libev.schmorp.de/bench.html> comparing it to libevent |
85 | for example). |
85 | for example). |
86 | |
86 | |
87 | =head1 CONVENTIONS |
87 | =head2 CONVENTIONS |
88 | |
88 | |
89 | Libev is very configurable. In this manual the default configuration will |
89 | Libev is very configurable. In this manual the default configuration will |
90 | be described, which supports multiple event loops. For more info about |
90 | be described, which supports multiple event loops. For more info about |
91 | various configuration options please have a look at B<EMBED> section in |
91 | various configuration options please have a look at B<EMBED> section in |
92 | this manual. If libev was configured without support for multiple event |
92 | this manual. If libev was configured without support for multiple event |
93 | loops, then all functions taking an initial argument of name C<loop> |
93 | loops, 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 | |
98 | Libev represents time as a single floating point number, representing the |
98 | Libev 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 |
100 | the beginning of 1970, details are complicated, don't ask). This type is |
100 | the beginning of 1970, details are complicated, don't ask). This type is |
101 | called C<ev_tstamp>, which is what you should use too. It usually aliases |
101 | called C<ev_tstamp>, which is what you should use too. It usually aliases |
… | |
… | |
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 | |
2635 | This means that, when you have a watcher that triggers in one hour and |
2635 | This means that, when you have a watcher that triggers in one hour and |
2636 | there are 100 watchers that would trigger before that then inserting will |
2636 | there are 100 watchers that would trigger before that then inserting will |
2637 | have to skip those 100 watchers. |
2637 | have 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 | |
2641 | That means that for changing a timer costs less than removing/adding them |
2641 | That means that changing a timer costs less than removing/adding them |
2642 | as only the relative motion in the event queue has to be paid for. |
2642 | as 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 | |
2646 | These just add the watcher into an array or at the head of a list. |
2646 | These 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 | |
2651 | These watchers are stored in lists then need to be walked to find the |
2652 | These watchers are stored in lists then need to be walked to find the |
2652 | correct watcher to remove. The lists are usually short (you don't usually |
2653 | correct watcher to remove. The lists are usually short (you don't usually |
2653 | have many watchers waiting for the same fd or signal). |
2654 | have 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 | |
|
|
2658 | By virtue of using a binary heap, the next timer is always found at the |
|
|
2659 | beginning 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 | |
2659 | A change means an I/O watcher gets started or stopped, which requires |
2663 | A change means an I/O watcher gets started or stopped, which requires |
2660 | libev to recalculate its status (and possibly tell the kernel). |
2664 | libev to recalculate its status (and possibly tell the kernel, depending |
|
|
2665 | on 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 | |
2666 | Priorities are implemented by allocating some space for each |
2671 | Priorities are implemented by allocating some space for each |
2667 | priority. When doing priority-based operations, libev usually has to |
2672 | priority. When doing priority-based operations, libev usually has to |
2668 | linearly search all the priorities. |
2673 | linearly search all the priorities, but starting/stopping and activating |
|
|
2674 | watchers becomes O(1) w.r.t. prioritiy handling. |
2669 | |
2675 | |
2670 | =back |
2676 | =back |
2671 | |
2677 | |
2672 | |
2678 | |
2673 | =head1 AUTHOR |
2679 | =head1 AUTHOR |