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

Comparing libev/ev.pod (file contents):
Revision 1.172 by root, Wed Aug 6 07:01:25 2008 UTC vs.
Revision 1.176 by root, Mon Sep 8 17:24:39 2008 UTC

… …
572Returns the current "event loop time", which is the time the event loop 572Returns the current "event loop time", which is the time the event loop
573received events and started processing them. This timestamp does not 573received events and started processing them. This timestamp does not
574change as long as callbacks are being processed, and this is also the base 574change as long as callbacks are being processed, and this is also the base
575time used for relative timers. You can treat it as the timestamp of the 575time used for relative timers. You can treat it as the timestamp of the
576event occurring (or more correctly, libev finding out about it). 576event occurring (or more correctly, libev finding out about it).
577
578=item ev_now_update (loop)
579
580Establishes the current time by querying the kernel, updating the time
581returned by C<ev_now ()> in the progress. This is a costly operation and
582is usually done automatically within C<ev_loop ()>.
583
584This function is rarely useful, but when some event callback runs for a
585very long time without entering the event loop, updating libev's idea of
586the current time is a good idea.
587
588See also "The special problem of time updates" in the C<ev_timer> section.
577 589
578=item ev_loop (loop, int flags) 590=item ev_loop (loop, int flags)
579 591
580Finally, this is it, the event handler. This function usually is called 592Finally, this is it, the event handler. This function usually is called
581after you initialised all your watchers and you want to start handling 593after you initialised all your watchers and you want to start handling
… …
1134C<EVBACKEND_POLL>. 1146C<EVBACKEND_POLL>.
1135 1147
1136=head3 The special problem of SIGPIPE 1148=head3 The special problem of SIGPIPE
1137 1149
1138While not really specific to libev, it is easy to forget about SIGPIPE: 1150While not really specific to libev, it is easy to forget about SIGPIPE:
1139when reading from a pipe whose other end has been closed, your program 1151when writing to a pipe whose other end has been closed, your program gets
1140gets send a SIGPIPE, which, by default, aborts your program. For most 1152send a SIGPIPE, which, by default, aborts your program. For most programs
1141programs this is sensible behaviour, for daemons, this is usually 1153this is sensible behaviour, for daemons, this is usually undesirable.
1142undesirable.
1143 1154
1144So when you encounter spurious, unexplained daemon exits, make sure you 1155So when you encounter spurious, unexplained daemon exits, make sure you
1145ignore SIGPIPE (and maybe make sure you log the exit status of your daemon 1156ignore SIGPIPE (and maybe make sure you log the exit status of your daemon
1146somewhere, as that would have given you a big clue). 1157somewhere, as that would have given you a big clue).
1147 1158
… …
1198times out after an hour and you reset your system clock to January last 1209times out after an hour and you reset your system clock to January last
1199year, it will still time out after (roughly) and hour. "Roughly" because 1210year, it will still time out after (roughly) and hour. "Roughly" because
1200detecting time jumps is hard, and some inaccuracies are unavoidable (the 1211detecting time jumps is hard, and some inaccuracies are unavoidable (the
1201monotonic clock option helps a lot here). 1212monotonic clock option helps a lot here).
1202 1213
1214The callback is guaranteed to be invoked only after its timeout has passed,
1215but if multiple timers become ready during the same loop iteration then
1216order of execution is undefined.
1217
1218=head3 The special problem of time updates
1219
1220Establishing the current time is a costly operation (it usually takes at
1221least two system calls): EV therefore updates its idea of the current
1222time only before and after C<ev_loop> polls for new events, which causes
1223a growing difference between C<ev_now ()> and C<ev_time ()> when handling
1224lots of events.
1225
1203The relative timeouts are calculated relative to the C<ev_now ()> 1226The relative timeouts are calculated relative to the C<ev_now ()>
1204time. This is usually the right thing as this timestamp refers to the time 1227time. This is usually the right thing as this timestamp refers to the time
1205of the event triggering whatever timeout you are modifying/starting. If 1228of the event triggering whatever timeout you are modifying/starting. If
1206you suspect event processing to be delayed and you I<need> to base the timeout 1229you suspect event processing to be delayed and you I<need> to base the
1207on the current time, use something like this to adjust for this: 1230timeout on the current time, use something like this to adjust for this:
1208 1231
1209 ev_timer_set (&timer, after + ev_now () - ev_time (), 0.); 1232 ev_timer_set (&timer, after + ev_now () - ev_time (), 0.);
1210 1233
1211The callback is guaranteed to be invoked only after its timeout has passed, 1234If the event loop is suspended for a long time, one can also force an
1212but if multiple timers become ready during the same loop iteration then 1235update of the time returned by C<ev_now ()> by calling C<ev_now_update
1213order of execution is undefined. 1236()>.
1214 1237
1215=head3 Watcher-Specific Functions and Data Members 1238=head3 Watcher-Specific Functions and Data Members
1216 1239
1217=over 4 1240=over 4
1218 1241
… …
1569handler, you can override it easily by installing your own handler for 1592handler, you can override it easily by installing your own handler for
1570C<SIGCHLD> after initialising the default loop, and making sure the 1593C<SIGCHLD> after initialising the default loop, and making sure the
1571default loop never gets destroyed. You are encouraged, however, to use an 1594default loop never gets destroyed. You are encouraged, however, to use an
1572event-based approach to child reaping and thus use libev's support for 1595event-based approach to child reaping and thus use libev's support for
1573that, so other libev users can use C<ev_child> watchers freely. 1596that, so other libev users can use C<ev_child> watchers freely.
1597
1598=head3 Stopping the Child Watcher
1599
1600Currently, the child watcher never gets stopped, even when the
1601child terminates, so normally one needs to stop the watcher in the
1602callback. Future versions of libev might stop the watcher automatically
1603when a child exit is detected.
1574 1604
1575=head3 Watcher-Specific Functions and Data Members 1605=head3 Watcher-Specific Functions and Data Members
1576 1606
1577=over 4 1607=over 4
1578 1608

Diff Legend

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