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