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

Comparing libev/ev.pod (file contents):
Revision 1.16 by root, Mon Nov 12 08:47:14 2007 UTC vs.
Revision 1.19 by root, Mon Nov 12 09:02:16 2007 UTC

… …
39F<README.embed> in the libev distribution. If libev was configured without 39F<README.embed> in the libev distribution. If libev was configured without
40support for multiple event loops, then all functions taking an initial 40support for multiple event loops, then all functions taking an initial
41argument of name C<loop> (which is always of type C<struct ev_loop *>) 41argument of name C<loop> (which is always of type C<struct ev_loop *>)
42will not have this argument. 42will not have this argument.
43 43
44=head1 TIME AND OTHER GLOBAL FUNCTIONS 44=head1 TIME REPRESENTATION
45 45
46Libev represents time as a single floating point number, representing the 46Libev represents time as a single floating point number, representing the
47(fractional) number of seconds since the (POSIX) epoch (somewhere near 47(fractional) number of seconds since the (POSIX) epoch (somewhere near
48the beginning of 1970, details are complicated, don't ask). This type is 48the beginning of 1970, details are complicated, don't ask). This type is
49called C<ev_tstamp>, which is what you should use too. It usually aliases 49called C<ev_tstamp>, which is what you should use too. It usually aliases
50to the double type in C. 50to the double type in C.
51
52=head1 GLOBAL FUNCTIONS
53
54These functions can be called anytime, even before initialising the
55library in any way.
51 56
52=over 4 57=over 4
53 58
54=item ev_tstamp ev_time () 59=item ev_tstamp ev_time ()
55 60
… …
99An event loop is described by a C<struct ev_loop *>. The library knows two 104An event loop is described by a C<struct ev_loop *>. The library knows two
100types of such loops, the I<default> loop, which supports signals and child 105types of such loops, the I<default> loop, which supports signals and child
101events, and dynamically created loops which do not. 106events, and dynamically created loops which do not.
102 107
103If you use threads, a common model is to run the default event loop 108If you use threads, a common model is to run the default event loop
104in your main thread (or in a separate thrad) and for each thread you 109in your main thread (or in a separate thread) and for each thread you
105create, you also create another event loop. Libev itself does no locking 110create, you also create another event loop. Libev itself does no locking
106whatsoever, so if you mix calls to the same event loop in different 111whatsoever, so if you mix calls to the same event loop in different
107threads, make sure you lock (this is usually a bad idea, though, even if 112threads, make sure you lock (this is usually a bad idea, though, even if
108done correctly, because it's hideous and inefficient). 113done correctly, because it's hideous and inefficient).
109 114
… …
558In this mode the values for C<interval> and C<at> are both being 563In this mode the values for C<interval> and C<at> are both being
559ignored. Instead, each time the periodic watcher gets scheduled, the 564ignored. Instead, each time the periodic watcher gets scheduled, the
560reschedule callback will be called with the watcher as first, and the 565reschedule callback will be called with the watcher as first, and the
561current time as second argument. 566current time as second argument.
562 567
563NOTE: I<This callback MUST NOT stop or destroy the periodic or any other 568NOTE: I<This callback MUST NOT stop or destroy any periodic watcher,
564periodic watcher, ever, or make any event loop modifications>. If you need 569ever, or make any event loop modifications>. If you need to stop it,
565to stop it, return C<now + 1e30> (or so, fudge fudge) and stop it afterwards. 570return C<now + 1e30> (or so, fudge fudge) and stop it afterwards (e.g. by
566 571starting a prepare watcher).
567Also, I<< this callback must always return a time that is later than the
568passed C<now> value >>. Not even C<now> itself will be ok.
569 572
570Its prototype is C<ev_tstamp (*reschedule_cb)(struct ev_periodic *w, 573Its prototype is C<ev_tstamp (*reschedule_cb)(struct ev_periodic *w,
571ev_tstamp now)>, e.g.: 574ev_tstamp now)>, e.g.:
572 575
573 static ev_tstamp my_rescheduler (struct ev_periodic *w, ev_tstamp now) 576 static ev_tstamp my_rescheduler (struct ev_periodic *w, ev_tstamp now)
… …
578It must return the next time to trigger, based on the passed time value 581It must return the next time to trigger, based on the passed time value
579(that is, the lowest time value larger than to the second argument). It 582(that is, the lowest time value larger than to the second argument). It
580will usually be called just before the callback will be triggered, but 583will usually be called just before the callback will be triggered, but
581might be called at other times, too. 584might be called at other times, too.
582 585
586NOTE: I<< This callback must always return a time that is later than the
587passed C<now> value >>. Not even C<now> itself will do, it I<must> be larger.
588
583This can be used to create very complex timers, such as a timer that 589This can be used to create very complex timers, such as a timer that
584triggers on each midnight, local time. To do this, you would calculate the 590triggers on each midnight, local time. To do this, you would calculate the
585next midnight after C<now> and return the timestamp value for this. How you do this 591next midnight after C<now> and return the timestamp value for this. How
586is, again, up to you (but it is not trivial). 592you do this is, again, up to you (but it is not trivial, which is the main
593reason I omitted it as an example).
587 594
588=back 595=back
589 596
590=item ev_periodic_again (loop, ev_periodic *) 597=item ev_periodic_again (loop, ev_periodic *)
591 598

Diff Legend

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