the beginning of 1970, details are complicated, don't ask). This type is
called C<ev_tstamp>, which is what you should use too. It usually aliases
to the C<double> type in C, and when you need to do any calculations on
-it, you should treat it as such.
+it, you should treat it as some floatingpoint value. Unlike the name
+component C<stamp> might indicate, it is also used for time differences
+throughout libev.
=head1 GLOBAL FUNCTIONS
Kqueue deserves special mention, as at the time of this writing, it
was broken on all BSDs except NetBSD (usually it doesn't work with
-anything but sockets and pipes, except on Darwin, where of course its
-completely useless). For this reason its not being "autodetected"
+anything but sockets and pipes, except on Darwin, where of course it's
+completely useless). For this reason it's not being "autodetected"
unless you explicitly specify it explicitly in the flags (i.e. using
C<EVBACKEND_KQUEUE>).
sense, so e.g. C<ev_is_active> might still return true. It is your
responsibility to either stop all watchers cleanly yoursef I<before>
calling this function, or cope with the fact afterwards (which is usually
-the easiest thing, youc na just ignore the watchers and/or C<free ()> them
+the easiest thing, you can just ignore the watchers and/or C<free ()> them
for example).
+Note that certain global state, such as signal state, will not be freed by
+this function, and related watchers (such as signal and child watchers)
+would need to be stopped manually.
+
+In general it is not advisable to call this function except in the
+rare occasion where you really need to free e.g. the signal handling
+pipe fds. If you need dynamically allocated loops it is better to use
+C<ev_loop_new> and C<ev_loop_destroy>).
+
=item ev_loop_destroy (loop)
Like C<ev_default_destroy>, but destroys an event loop created by an
switched off. Can be changed any time, but changes only take effect when
the periodic timer fires or C<ev_periodic_again> is being called.
+=item ev_tstamp at [read-only]
+
+When active, contains the absolute time that the watcher is supposed to
+trigger next.
+
=back
Example: Call a callback every hour, or, more precisely, whenever the
Stops the watcher if it is active. Again, no C<loop> argument.
-=item w->again () C<ev::timer>, C<ev::periodic> only
+=item w->again () (C<ev::timer>, C<ev::periodic> only)
For C<ev::timer> and C<ev::periodic>, this invokes the corresponding
C<ev_TYPE_again> function.
-=item w->sweep () C<ev::embed> only
+=item w->sweep () (C<ev::embed> only)
Invokes C<ev_embed_sweep>.
-=item w->update () C<ev::stat> only
+=item w->update () (C<ev::stat> only)
Invokes C<ev_stat_stat>.
=head1 MACRO MAGIC
-Libev can be compiled with a variety of options, the most fundemantal is
-C<EV_MULTIPLICITY>. This option determines whether (most) functions and
-callbacks have an initial C<struct ev_loop *> argument.
+Libev can be compiled with a variety of options, the most fundamantal
+of which is C<EV_MULTIPLICITY>. This option determines whether (most)
+functions and callbacks have an initial C<struct ev_loop *> argument.
To make it easier to write programs that cope with either variant, the
following macros are defined:
realtime clock option at compiletime (and assume its availability at
runtime if successful). Otherwise no use of the realtime clock option will
be attempted. This effectively replaces C<gettimeofday> by C<clock_get
-(CLOCK_REALTIME, ...)> and will not normally affect correctness. See tzhe note about libraries
-in the description of C<EV_USE_MONOTONIC>, though.
+(CLOCK_REALTIME, ...)> and will not normally affect correctness. See the
+note about libraries in the description of C<EV_USE_MONOTONIC>, though.
=item EV_USE_SELECT
avoid the C<struct ev_loop *> as first argument in all cases, or to use
method calls instead of plain function calls in C++.
+=head2 EXPORTED API SYMBOLS
+
+If you need to re-export the API (e.g. via a dll) and you need a list of
+exported symbols, you can use the provided F<Symbol.*> files which list
+all public symbols, one per line:
+
+ Symbols.ev for libev proper
+ Symbols.event for the libevent emulation
+
+This can also be used to rename all public symbols to avoid clashes with
+multiple versions of libev linked together (which is obviously bad in
+itself, but sometimes it is inconvinient to avoid this).
+
+A sed comamnd like this will create wrapper C<#define>'s that you need to
+include before including F<ev.h>:
+
+ <Symbols.ev sed -e "s/.*/#define & myprefix_&/" >wrap.h
+
+This would create a file F<wrap.h> which essentially looks like this:
+
+ #define ev_backend myprefix_ev_backend
+ #define ev_check_start myprefix_ev_check_start
+ #define ev_check_stop myprefix_ev_check_stop
+ ...
+
=head2 EXAMPLES
For a real-world example of a program the includes libev
projects / software / libev.git / blobdiff