… | |
… | |
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 | |
51 | |
52 | =head1 GLOBAL FUNCTIONS |
52 | =head1 GLOBAL FUNCTIONS |
|
|
53 | |
|
|
54 | These functions can be called anytime, even before initialising the |
|
|
55 | library in any way. |
53 | |
56 | |
54 | =over 4 |
57 | =over 4 |
55 | |
58 | |
56 | =item ev_tstamp ev_time () |
59 | =item ev_tstamp ev_time () |
57 | |
60 | |
… | |
… | |
560 | 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 |
561 | ignored. Instead, each time the periodic watcher gets scheduled, the |
564 | ignored. Instead, each time the periodic watcher gets scheduled, the |
562 | 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 |
563 | current time as second argument. |
566 | current time as second argument. |
564 | |
567 | |
565 | 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, |
566 | 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, |
567 | 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 |
568 | |
571 | starting a prepare watcher). |
569 | Also, I<< this callback must always return a time that is later than the |
|
|
570 | passed C<now> value >>. Not even C<now> itself will be ok. |
|
|
571 | |
572 | |
572 | 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, |
573 | ev_tstamp now)>, e.g.: |
574 | ev_tstamp now)>, e.g.: |
574 | |
575 | |
575 | 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) |
… | |
… | |
580 | 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 |
581 | (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 |
582 | 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 |
583 | might be called at other times, too. |
584 | might be called at other times, too. |
584 | |
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 I<must> be larger. |
|
|
588 | |
585 | 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 |
586 | 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 |
587 | 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 |
588 | is, again, up to you (but it is not trivial). |
592 | you do this is, again, up to you (but it is not trivial, which is the main |
|
|
593 | reason I omitted it as an example). |
589 | |
594 | |
590 | =back |
595 | =back |
591 | |
596 | |
592 | =item ev_periodic_again (loop, ev_periodic *) |
597 | =item ev_periodic_again (loop, ev_periodic *) |
593 | |
598 | |
… | |
… | |
672 | =back |
677 | =back |
673 | |
678 | |
674 | =head2 C<ev_prepare> and C<ev_check> - customise your event loop |
679 | =head2 C<ev_prepare> and C<ev_check> - customise your event loop |
675 | |
680 | |
676 | Prepare and check watchers are usually (but not always) used in tandem: |
681 | Prepare and check watchers are usually (but not always) used in tandem: |
677 | Prepare watchers get invoked before the process blocks and check watchers |
682 | prepare watchers get invoked before the process blocks and check watchers |
678 | afterwards. |
683 | afterwards. |
679 | |
684 | |
680 | Their main purpose is to integrate other event mechanisms into libev. This |
685 | Their main purpose is to integrate other event mechanisms into libev. This |
681 | could be used, for example, to track variable changes, implement your own |
686 | could be used, for example, to track variable changes, implement your own |
682 | watchers, integrate net-snmp or a coroutine library and lots more. |
687 | watchers, integrate net-snmp or a coroutine library and lots more. |
… | |
… | |
685 | to be watched by the other library, registering C<ev_io> watchers for |
690 | to be watched by the other library, registering C<ev_io> watchers for |
686 | them and starting an C<ev_timer> watcher for any timeouts (many libraries |
691 | them and starting an C<ev_timer> watcher for any timeouts (many libraries |
687 | provide just this functionality). Then, in the check watcher you check for |
692 | provide just this functionality). Then, in the check watcher you check for |
688 | any events that occured (by checking the pending status of all watchers |
693 | any events that occured (by checking the pending status of all watchers |
689 | and stopping them) and call back into the library. The I/O and timer |
694 | and stopping them) and call back into the library. The I/O and timer |
690 | callbacks will never actually be called (but must be valid neverthelles, |
695 | callbacks will never actually be called (but must be valid nevertheless, |
691 | because you never know, you know?). |
696 | because you never know, you know?). |
692 | |
697 | |
693 | As another example, the Perl Coro module uses these hooks to integrate |
698 | As another example, the Perl Coro module uses these hooks to integrate |
694 | coroutines into libev programs, by yielding to other active coroutines |
699 | coroutines into libev programs, by yielding to other active coroutines |
695 | during each prepare and only letting the process block if no coroutines |
700 | during each prepare and only letting the process block if no coroutines |
696 | are ready to run (its actually more complicated, it only runs coroutines |
701 | are ready to run (it's actually more complicated: it only runs coroutines |
697 | with priority higher than the event loop and one lower priority once, |
702 | with priority higher than or equal to the event loop and one coroutine |
698 | using idle watchers to keep the event loop from blocking if lower-priority |
703 | of lower priority, but only once, using idle watchers to keep the event |
699 | coroutines exist, thus mapping low-priority coroutines to idle/background |
704 | loop from blocking if lower-priority coroutines are active, thus mapping |
700 | tasks). |
705 | low-priority coroutines to idle/background tasks). |
701 | |
706 | |
702 | =over 4 |
707 | =over 4 |
703 | |
708 | |
704 | =item ev_prepare_init (ev_prepare *, callback) |
709 | =item ev_prepare_init (ev_prepare *, callback) |
705 | |
710 | |
… | |
… | |
764 | |
769 | |
765 | Feed an event as if the given signal occured (loop must be the default loop!). |
770 | Feed an event as if the given signal occured (loop must be the default loop!). |
766 | |
771 | |
767 | =back |
772 | =back |
768 | |
773 | |
|
|
774 | =head1 LIBEVENT EMULATION |
|
|
775 | |
|
|
776 | TBD. |
|
|
777 | |
|
|
778 | =head1 C++ SUPPORT |
|
|
779 | |
|
|
780 | TBD. |
|
|
781 | |
769 | =head1 AUTHOR |
782 | =head1 AUTHOR |
770 | |
783 | |
771 | Marc Lehmann <libev@schmorp.de>. |
784 | Marc Lehmann <libev@schmorp.de>. |
772 | |
785 | |