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

Comparing libev/ev.pod (file contents):
Revision 1.68 by root, Fri Dec 7 18:09:43 2007 UTC vs.
Revision 1.75 by root, Sat Dec 8 14:27: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
732=item bool ev_is_pending (ev_TYPE *watcher) 736=item bool ev_is_pending (ev_TYPE *watcher)
733 737
734Returns a true value iff the watcher is pending, (i.e. it has outstanding 738Returns a true value iff the watcher is pending, (i.e. it has outstanding
735events but its callback has not yet been invoked). As long as a watcher 739events but its callback has not yet been invoked). As long as a watcher
736is pending (but not active) you must not call an init function on it (but 740is pending (but not active) you must not call an init function on it (but
737C<ev_TYPE_set> is safe) and you must make sure the watcher is available to 741C<ev_TYPE_set> is safe), you must not change its priority, and you must
738libev (e.g. you cnanot C<free ()> it). 742make sure the watcher is available to libev (e.g. you cannot C<free ()>
743it).
739 744
740=item callback ev_cb (ev_TYPE *watcher) 745=item callback ev_cb (ev_TYPE *watcher)
741 746
742Returns the callback currently set on the watcher. 747Returns the callback currently set on the watcher.
743 748
762watchers on the same event and make sure one is called first. 767watchers on the same event and make sure one is called first.
763 768
764If you need to suppress invocation when higher priority events are pending 769If you need to suppress invocation when higher priority events are pending
765you need to look at C<ev_idle> watchers, which provide this functionality. 770you need to look at C<ev_idle> watchers, which provide this functionality.
766 771
772You I<must not> change the priority of a watcher as long as it is active or
773pending.
774
767The default priority used by watchers when no priority has been set is 775The default priority used by watchers when no priority has been set is
768always C<0>, which is supposed to not be too high and not be too low :). 776always C<0>, which is supposed to not be too high and not be too low :).
769 777
770Setting a priority outside the range of C<EV_MINPRI> to C<EV_MAXPRI> is 778Setting a priority outside the range of C<EV_MINPRI> to C<EV_MAXPRI> is
771fine, as long as you do not mind that the priority value you query might 779fine, as long as you do not mind that the priority value you query might
772or might not have been adjusted to be within valid range. 780or might not have been adjusted to be within valid range.
781
782=item ev_invoke (loop, ev_TYPE *watcher, int revents)
783
784Invoke the C<watcher> with the given C<loop> and C<revents>. Neither
785C<loop> nor C<revents> need to be valid as long as the watcher callback
786can deal with that fact.
787
788=item int ev_clear_pending (loop, ev_TYPE *watcher)
789
790If the watcher is pending, this function returns clears its pending status
791and returns its C<revents> bitset (as if its callback was invoked). If the
792watcher isn't pending it does nothing and returns C<0>.
773 793
774=back 794=back
775 795
776 796
777=head2 ASSOCIATING CUSTOM DATA WITH A WATCHER 797=head2 ASSOCIATING CUSTOM DATA WITH A WATCHER
1740 1760
1741To use it, 1761To use it,
1742 1762
1743 #include <ev++.h> 1763 #include <ev++.h>
1744 1764
1745(it is not installed by default). This automatically includes F<ev.h> 1765This automatically includes F<ev.h> and puts all of its definitions (many
1746and puts all of its definitions (many of them macros) into the global 1766of them macros) into the global namespace. All C++ specific things are
1747namespace. All C++ specific things are put into the C<ev> namespace. 1767put into the C<ev> namespace. It should support all the same embedding
1768options as F<ev.h>, most notably C<EV_MULTIPLICITY>.
1748 1769
1749It should support all the same embedding options as F<ev.h>, most notably 1770Care has been taken to keep the overhead low. The only data member the C++
1750C<EV_MULTIPLICITY>. 1771classes add (compared to plain C-style watchers) is the event loop pointer
1772that the watcher is associated with (or no additional members at all if
1773you disable C<EV_MULTIPLICITY> when embedding libev).
1774
1775Currently, functions, and static and non-static member functions can be
1776used as callbacks. Other types should be easy to add as long as they only
1777need one additional pointer for context. If you need support for other
1778types of functors please contact the author (preferably after implementing
1779it).
1751 1780
1752Here is a list of things available in the C<ev> namespace: 1781Here is a list of things available in the C<ev> namespace:
1753 1782
1754=over 4 1783=over 4
1755 1784
1771 1800
1772All of those classes have these methods: 1801All of those classes have these methods:
1773 1802
1774=over 4 1803=over 4
1775 1804
1776=item ev::TYPE::TYPE (object *, object::method *) 1805=item ev::TYPE::TYPE ()
1777 1806
1778=item ev::TYPE::TYPE (object *, object::method *, struct ev_loop *) 1807=item ev::TYPE::TYPE (struct ev_loop *)
1779 1808
1780=item ev::TYPE::~TYPE 1809=item ev::TYPE::~TYPE
1781 1810
1782The constructor takes a pointer to an object and a method pointer to 1811The constructor (optionally) takes an event loop to associate the watcher
1783the event handler callback to call in this class. The constructor calls 1812with. If it is omitted, it will use C<EV_DEFAULT>.
1784C<ev_init> for you, which means you have to call the C<set> method 1813
1785before starting it. If you do not specify a loop then the constructor 1814The constructor calls C<ev_init> for you, which means you have to call the
1786automatically associates the default loop with this watcher. 1815C<set> method before starting it.
1816
1817It will not set a callback, however: You have to call the templated C<set>
1818method to set a callback before you can start the watcher.
1819
1820(The reason why you have to use a method is a limitation in C++ which does
1821not allow explicit template arguments for constructors).
1787 1822
1788The destructor automatically stops the watcher if it is active. 1823The destructor automatically stops the watcher if it is active.
1824
1825=item w->set<class, &class::method> (object *)
1826
1827This method sets the callback method to call. The method has to have a
1828signature of C<void (*)(ev_TYPE &, int)>, it receives the watcher as
1829first argument and the C<revents> as second. The object must be given as
1830parameter and is stored in the C<data> member of the watcher.
1831
1832This method synthesizes efficient thunking code to call your method from
1833the C callback that libev requires. If your compiler can inline your
1834callback (i.e. it is visible to it at the place of the C<set> call and
1835your compiler is good :), then the method will be fully inlined into the
1836thunking function, making it as fast as a direct C callback.
1837
1838Example: simple class declaration and watcher initialisation
1839
1840 struct myclass
1841 {
1842 void io_cb (ev::io &w, int revents) { }
1843 }
1844
1845 myclass obj;
1846 ev::io iow;
1847 iow.set <myclass, &myclass::io_cb> (&obj);
1848
1849=item w->set<function> (void *data = 0)
1850
1851Also sets a callback, but uses a static method or plain function as
1852callback. The optional C<data> argument will be stored in the watcher's
1853C<data> member and is free for you to use.
1854
1855The prototype of the C<function> must be C<void (*)(ev::TYPE &w, int)>.
1856
1857See the method-C<set> above for more details.
1858
1859Example:
1860
1861 static void io_cb (ev::io &w, int revents) { }
1862 iow.set <io_cb> ();
1789 1863
1790=item w->set (struct ev_loop *) 1864=item w->set (struct ev_loop *)
1791 1865
1792Associates a different C<struct ev_loop> with this watcher. You can only 1866Associates a different C<struct ev_loop> with this watcher. You can only
1793do this when the watcher is inactive (and not pending either). 1867do this when the watcher is inactive (and not pending either).
1794 1868
1795=item w->set ([args]) 1869=item w->set ([args])
1796 1870
1797Basically the same as C<ev_TYPE_set>, with the same args. Must be 1871Basically the same as C<ev_TYPE_set>, with the same args. Must be
1798called at least once. Unlike the C counterpart, an active watcher gets 1872called at least once. Unlike the C counterpart, an active watcher gets
1799automatically stopped and restarted. 1873automatically stopped and restarted when reconfiguring it with this
1874method.
1800 1875
1801=item w->start () 1876=item w->start ()
1802 1877
1803Starts the watcher. Note that there is no C<loop> argument as the 1878Starts the watcher. Note that there is no C<loop> argument, as the
1804constructor already takes the loop. 1879constructor already stores the event loop.
1805 1880
1806=item w->stop () 1881=item w->stop ()
1807 1882
1808Stops the watcher if it is active. Again, no C<loop> argument. 1883Stops the watcher if it is active. Again, no C<loop> argument.
1809 1884
1834 1909
1835 myclass (); 1910 myclass ();
1836 } 1911 }
1837 1912
1838 myclass::myclass (int fd) 1913 myclass::myclass (int fd)
1839 : io (this, &myclass::io_cb),
1840 idle (this, &myclass::idle_cb)
1841 { 1914 {
1915 io .set <myclass, &myclass::io_cb > (this);
1916 idle.set <myclass, &myclass::idle_cb> (this);
1917
1842 io.start (fd, ev::READ); 1918 io.start (fd, ev::READ);
1843 } 1919 }
1844 1920
1845 1921
1846=head1 MACRO MAGIC 1922=head1 MACRO MAGIC
2123will have the C<struct ev_loop *> as first argument, and you can create 2199will have the C<struct ev_loop *> as first argument, and you can create
2124additional independent event loops. Otherwise there will be no support 2200additional independent event loops. Otherwise there will be no support
2125for multiple event loops and there is no first event loop pointer 2201for multiple event loops and there is no first event loop pointer
2126argument. Instead, all functions act on the single default loop. 2202argument. Instead, all functions act on the single default loop.
2127 2203
2204=item EV_MINPRI
2205
2206=item EV_MAXPRI
2207
2208The range of allowed priorities. C<EV_MINPRI> must be smaller or equal to
2209C<EV_MAXPRI>, but otherwise there are no non-obvious limitations. You can
2210provide for more priorities by overriding those symbols (usually defined
2211to be C<-2> and C<2>, respectively).
2212
2213When doing priority-based operations, libev usually has to linearly search
2214all the priorities, so having many of them (hundreds) uses a lot of space
2215and time, so using the defaults of five priorities (-2 .. +2) is usually
2216fine.
2217
2218If your embedding app does not need any priorities, defining these both to
2219C<0> will save some memory and cpu.
2220
2128=item EV_PERIODIC_ENABLE 2221=item EV_PERIODIC_ENABLE
2129 2222
2130If undefined or defined to be C<1>, then periodic timers are supported. If 2223If 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 2224defined to be C<0>, then they are not. Disabling them saves a few kB of
2132code. 2225code.
2234 2327
2235In this section the complexities of (many of) the algorithms used inside 2328In this section the complexities of (many of) the algorithms used inside
2236libev will be explained. For complexity discussions about backends see the 2329libev will be explained. For complexity discussions about backends see the
2237documentation for C<ev_default_init>. 2330documentation for C<ev_default_init>.
2238 2331
2332All of the following are about amortised time: If an array needs to be
2333extended, libev needs to realloc and move the whole array, but this
2334happens asymptotically never with higher number of elements, so O(1) might
2335mean it might do a lengthy realloc operation in rare cases, but on average
2336it is much faster and asymptotically approaches constant time.
2337
2239=over 4 2338=over 4
2240 2339
2241=item Starting and stopping timer/periodic watchers: O(log skipped_other_timers) 2340=item Starting and stopping timer/periodic watchers: O(log skipped_other_timers)
2242 2341
2342This means that, when you have a watcher that triggers in one hour and
2343there are 100 watchers that would trigger before that then inserting will
2344have to skip those 100 watchers.
2345
2243=item Changing timer/periodic watchers (by autorepeat, again): O(log skipped_other_timers) 2346=item Changing timer/periodic watchers (by autorepeat, again): O(log skipped_other_timers)
2244 2347
2348That means that for changing a timer costs less than removing/adding them
2349as only the relative motion in the event queue has to be paid for.
2350
2245=item Starting io/check/prepare/idle/signal/child watchers: O(1) 2351=item Starting io/check/prepare/idle/signal/child watchers: O(1)
2246 2352
2353These just add the watcher into an array or at the head of a list.
2247=item Stopping check/prepare/idle watchers: O(1) 2354=item Stopping check/prepare/idle watchers: O(1)
2248 2355
2249=item Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % EV_PID_HASHSIZE)) 2356=item Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % EV_PID_HASHSIZE))
2250 2357
2358These watchers are stored in lists then need to be walked to find the
2359correct watcher to remove. The lists are usually short (you don't usually
2360have many watchers waiting for the same fd or signal).
2361
2251=item Finding the next timer per loop iteration: O(1) 2362=item Finding the next timer per loop iteration: O(1)
2252 2363
2253=item Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd) 2364=item Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd)
2254 2365
2366A change means an I/O watcher gets started or stopped, which requires
2367libev to recalculate its status (and possibly tell the kernel).
2368
2255=item Activating one watcher: O(1) 2369=item Activating one watcher: O(1)
2256 2370
2371=item Priority handling: O(number_of_priorities)
2372
2373Priorities are implemented by allocating some space for each
2374priority. When doing priority-based operations, libev usually has to
2375linearly search all the priorities.
2376
2257=back 2377=back
2258 2378
2259 2379
2260=head1 AUTHOR 2380=head1 AUTHOR
2261 2381

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines