*** empty log message ***

[software/libev.git] / ev.pod

diff --git a/ev.pod b/ev.pod
index 237af6fe9ed975ce03bd526622fe30d3e51ac256..2269dff05bf943283e66142983eb0ff7c7b2ba2a 100644 (file)
--- a/ev.pod
+++ b/ev.pod
@@ -6,7 +6,7 @@ libev - a high performance full-featured event loop written in C
 
   #include <ev.h>
 
 
   #include <ev.h>
 

-=head1 EXAMPLE PROGRAM
+=head2 EXAMPLE PROGRAM

 
   #include <ev.h>
 
 
   #include <ev.h>
 


@@ -67,7 +67,7 @@ watchers>, which are relatively small C structures you initialise with the
 details of the event, and then hand it over to libev by I<starting> the
 watcher.
 
 details of the event, and then hand it over to libev by I<starting> the
 watcher.
 

-=head1 FEATURES
+=head2 FEATURES

 
 Libev supports C<select>, C<poll>, the Linux-specific C<epoll>, the
 BSD-specific C<kqueue> and the Solaris-specific event port mechanisms
 
 Libev supports C<select>, C<poll>, the Linux-specific C<epoll>, the
 BSD-specific C<kqueue> and the Solaris-specific event port mechanisms


@@ -84,7 +84,7 @@ It also is quite fast (see this
 L<benchmark|http://libev.schmorp.de/bench.html> comparing it to libevent
 for example).
 
 L<benchmark|http://libev.schmorp.de/bench.html> comparing it to libevent
 for example).
 

-=head1 CONVENTIONS
+=head2 CONVENTIONS

 
 Libev is very configurable. In this manual the default configuration will
 be described, which supports multiple event loops. For more info about
 
 Libev is very configurable. In this manual the default configuration will
 be described, which supports multiple event loops. For more info about


@@ -93,7 +93,7 @@ this manual. If libev was configured without support for multiple event
 loops, then all functions taking an initial argument of name C<loop>
 (which is always of type C<struct ev_loop *>) will not have this argument.
 
 loops, then all functions taking an initial argument of name C<loop>
 (which is always of type C<struct ev_loop *>) will not have this argument.
 

-=head1 TIME REPRESENTATION
+=head2 TIME REPRESENTATION

 
 Libev represents time as a single floating point number, representing the
 (fractional) number of seconds since the (POSIX) epoch (somewhere near
 
 Libev represents time as a single floating point number, representing the
 (fractional) number of seconds since the (POSIX) epoch (somewhere near


@@ -2528,7 +2528,7 @@ increase this value (I<must> be a power of two).
 
 =item EV_INOTIFY_HASHSIZE
 
 
 =item EV_INOTIFY_HASHSIZE
 

-C<ev_staz> watchers use a small hash table to distribute workload by
+C<ev_stat> watchers use a small hash table to distribute workload by

 inotify watch id. The default size is C<16> (or C<1> with C<EV_MINIMAL>),
 usually more than enough. If you need to manage thousands of C<ev_stat>
 watchers you might want to increase this value (I<must> be a power of
 inotify watch id. The default size is C<16> (or C<1> with C<EV_MINIMAL>),
 usually more than enough. If you need to manage thousands of C<ev_stat>
 watchers you might want to increase this value (I<must> be a power of


@@ -2634,16 +2634,17 @@ it is much faster and asymptotically approaches constant time.
 
 This means that, when you have a watcher that triggers in one hour and
 there are 100 watchers that would trigger before that then inserting will
 
 This means that, when you have a watcher that triggers in one hour and
 there are 100 watchers that would trigger before that then inserting will

-have to skip those 100 watchers.
+have to skip roughly seven (C<ld 100>) of these watchers.

 
 

-=item Changing timer/periodic watchers (by autorepeat, again): O(log skipped_other_timers)
+=item Changing timer/periodic watchers (by autorepeat or calling again): O(log skipped_other_timers)

 
 

-That means that for changing a timer costs less than removing/adding them
+That means that changing a timer costs less than removing/adding them

 as only the relative motion in the event queue has to be paid for.
 
 =item Starting io/check/prepare/idle/signal/child watchers: O(1)
 
 These just add the watcher into an array or at the head of a list.
 as only the relative motion in the event queue has to be paid for.
 
 =item Starting io/check/prepare/idle/signal/child watchers: O(1)
 
 These just add the watcher into an array or at the head of a list.

+

 =item Stopping check/prepare/idle watchers: O(1)
 
 =item Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % EV_PID_HASHSIZE))
 =item Stopping check/prepare/idle watchers: O(1)
 
 =item Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % EV_PID_HASHSIZE))


@@ -2652,20 +2653,25 @@ These watchers are stored in lists then need to be walked to find the
 correct watcher to remove. The lists are usually short (you don't usually
 have many watchers waiting for the same fd or signal).
 
 correct watcher to remove. The lists are usually short (you don't usually
 have many watchers waiting for the same fd or signal).
 

-=item Finding the next timer per loop iteration: O(1)
+=item Finding the next timer in each loop iteration: O(1)
+
+By virtue of using a binary heap, the next timer is always found at the
+beginning of the storage array.

 
 =item Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd)
 
 A change means an I/O watcher gets started or stopped, which requires
 
 =item Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd)
 
 A change means an I/O watcher gets started or stopped, which requires

-libev to recalculate its status (and possibly tell the kernel).
+libev to recalculate its status (and possibly tell the kernel, depending
+on backend and wether C<ev_io_set> was used).

 
 

-=item Activating one watcher: O(1)
+=item Activating one watcher (putting it into the pending state): O(1)

 
 =item Priority handling: O(number_of_priorities)
 
 Priorities are implemented by allocating some space for each
 priority. When doing priority-based operations, libev usually has to
 
 =item Priority handling: O(number_of_priorities)
 
 Priorities are implemented by allocating some space for each
 priority. When doing priority-based operations, libev usually has to

-linearly search all the priorities.
+linearly search all the priorities, but starting/stopping and activating
+watchers becomes O(1) w.r.t. prioritiy handling.

 
 =back
 
 
 =back