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

Comparing libev/ev.pod (file contents):
Revision 1.83 by root, Wed Dec 12 17:55:31 2007 UTC vs.
Revision 1.89 by root, Wed Dec 19 01:59:29 2007 UTC

… …
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
102to the C<double> type in C, and when you need to do any calculations on 102to the C<double> type in C, and when you need to do any calculations on
103it, you should treat it as such. 103it, you should treat it as some floatingpoint value. Unlike the name
104component C<stamp> might indicate, it is also used for time differences
105throughout libev.
104 106
105=head1 GLOBAL FUNCTIONS 107=head1 GLOBAL FUNCTIONS
106 108
107These functions can be called anytime, even before initialising the 109These functions can be called anytime, even before initialising the
108library in any way. 110library in any way.
… …
402Destroys the default loop again (frees all memory and kernel state 404Destroys the default loop again (frees all memory and kernel state
403etc.). None of the active event watchers will be stopped in the normal 405etc.). None of the active event watchers will be stopped in the normal
404sense, so e.g. C<ev_is_active> might still return true. It is your 406sense, so e.g. C<ev_is_active> might still return true. It is your
405responsibility to either stop all watchers cleanly yoursef I<before> 407responsibility to either stop all watchers cleanly yoursef I<before>
406calling this function, or cope with the fact afterwards (which is usually 408calling this function, or cope with the fact afterwards (which is usually
407the easiest thing, youc na just ignore the watchers and/or C<free ()> them 409the easiest thing, you can just ignore the watchers and/or C<free ()> them
408for example). 410for example).
411
412Note that certain global state, such as signal state, will not be freed by
413this function, and related watchers (such as signal and child watchers)
414would need to be stopped manually.
415
416In general it is not advisable to call this function except in the
417rare occasion where you really need to free e.g. the signal handling
418pipe fds. If you need dynamically allocated loops it is better to use
419C<ev_loop_new> and C<ev_loop_destroy>).
409 420
410=item ev_loop_destroy (loop) 421=item ev_loop_destroy (loop)
411 422
412Like C<ev_default_destroy>, but destroys an event loop created by an 423Like C<ev_default_destroy>, but destroys an event loop created by an
413earlier call to C<ev_loop_new>. 424earlier call to C<ev_loop_new>.
… …
1220 1231
1221The current reschedule callback, or C<0>, if this functionality is 1232The current reschedule callback, or C<0>, if this functionality is
1222switched off. Can be changed any time, but changes only take effect when 1233switched off. Can be changed any time, but changes only take effect when
1223the periodic timer fires or C<ev_periodic_again> is being called. 1234the periodic timer fires or C<ev_periodic_again> is being called.
1224 1235
1236=item ev_tstamp at [read-only]
1237
1238When active, contains the absolute time that the watcher is supposed to
1239trigger next.
1240
1225=back 1241=back
1226 1242
1227Example: Call a callback every hour, or, more precisely, whenever the 1243Example: Call a callback every hour, or, more precisely, whenever the
1228system clock is divisible by 3600. The callback invocation times have 1244system clock is divisible by 3600. The callback invocation times have
1229potentially a lot of jittering, but good long-term stability. 1245potentially a lot of jittering, but good long-term stability.
… …
2019 2035
2020=item w->stop () 2036=item w->stop ()
2021 2037
2022Stops the watcher if it is active. Again, no C<loop> argument. 2038Stops the watcher if it is active. Again, no C<loop> argument.
2023 2039
2024=item w->again () C<ev::timer>, C<ev::periodic> only 2040=item w->again () (C<ev::timer>, C<ev::periodic> only)
2025 2041
2026For C<ev::timer> and C<ev::periodic>, this invokes the corresponding 2042For C<ev::timer> and C<ev::periodic>, this invokes the corresponding
2027C<ev_TYPE_again> function. 2043C<ev_TYPE_again> function.
2028 2044
2029=item w->sweep () C<ev::embed> only 2045=item w->sweep () (C<ev::embed> only)
2030 2046
2031Invokes C<ev_embed_sweep>. 2047Invokes C<ev_embed_sweep>.
2032 2048
2033=item w->update () C<ev::stat> only 2049=item w->update () (C<ev::stat> only)
2034 2050
2035Invokes C<ev_stat_stat>. 2051Invokes C<ev_stat_stat>.
2036 2052
2037=back 2053=back
2038 2054
… …
2058 } 2074 }
2059 2075
2060 2076
2061=head1 MACRO MAGIC 2077=head1 MACRO MAGIC
2062 2078
2063Libev can be compiled with a variety of options, the most fundemantal is 2079Libev can be compiled with a variety of options, the most fundamantal
2064C<EV_MULTIPLICITY>. This option determines whether (most) functions and 2080of which is C<EV_MULTIPLICITY>. This option determines whether (most)
2065callbacks have an initial C<struct ev_loop *> argument. 2081functions and callbacks have an initial C<struct ev_loop *> argument.
2066 2082
2067To make it easier to write programs that cope with either variant, the 2083To make it easier to write programs that cope with either variant, the
2068following macros are defined: 2084following macros are defined:
2069 2085
2070=over 4 2086=over 4
… …
2429definition and a statement, respectively. See the F<ev.v> header file for 2445definition and a statement, respectively. See the F<ev.v> header file for
2430their default definitions. One possible use for overriding these is to 2446their default definitions. One possible use for overriding these is to
2431avoid the C<struct ev_loop *> as first argument in all cases, or to use 2447avoid the C<struct ev_loop *> as first argument in all cases, or to use
2432method calls instead of plain function calls in C++. 2448method calls instead of plain function calls in C++.
2433 2449
2450=head2 EXPORTED API SYMBOLS
2451
2452If you need to re-export the API (e.g. via a dll) and you need a list of
2453exported symbols, you can use the provided F<Symbol.*> files which list
2454all public symbols, one per line:
2455
2456 Symbols.ev for libev proper
2457 Symbols.event for the libevent emulation
2458
2459This can also be used to rename all public symbols to avoid clashes with
2460multiple versions of libev linked together (which is obviously bad in
2461itself, but sometimes it is inconvinient to avoid this).
2462
2463A sed comamnd like this will create wrapper C<#define>'s that you need to
2464include before including F<ev.h>:
2465
2466 <Symbols.ev sed -e "s/.*/#define & myprefix_&/" >wrap.h
2467
2468This would create a file F<wrap.h> which essentially looks like this:
2469
2470 #define ev_backend myprefix_ev_backend
2471 #define ev_check_start myprefix_ev_check_start
2472 #define ev_check_stop myprefix_ev_check_stop
2473 ...
2474
2434=head2 EXAMPLES 2475=head2 EXAMPLES
2435 2476
2436For a real-world example of a program the includes libev 2477For a real-world example of a program the includes libev
2437verbatim, you can have a look at the EV perl module 2478verbatim, you can have a look at the EV perl module
2438(L<http://software.schmorp.de/pkg/EV.html>). It has the libev files in 2479(L<http://software.schmorp.de/pkg/EV.html>). It has the libev files in

Diff Legend

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