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

Comparing libev/ev.pod (file contents):
Revision 1.17 by root, Mon Nov 12 08:57:03 2007 UTC vs.
Revision 1.21 by root, Mon Nov 12 09:07:10 2007 UTC

… …
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 51
52=head1 GLOBAL FUNCTIONS 52=head1 GLOBAL FUNCTIONS
53
54These functions can be called anytime, even before initialising the
55library 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
… …
560In 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
561ignored. Instead, each time the periodic watcher gets scheduled, the 564ignored. Instead, each time the periodic watcher gets scheduled, the
562reschedule callback will be called with the watcher as first, and the 565reschedule callback will be called with the watcher as first, and the
563current time as second argument. 566current time as second argument.
564 567
565NOTE: 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,
566periodic watcher, ever, or make any event loop modifications>. If you need 569ever, or make any event loop modifications>. If you need to stop it,
567to 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
568 571starting a prepare watcher).
569Also, I<< this callback must always return a time that is later than the
570passed C<now> value >>. Not even C<now> itself will be ok.
571 572
572Its prototype is C<ev_tstamp (*reschedule_cb)(struct ev_periodic *w, 573Its prototype is C<ev_tstamp (*reschedule_cb)(struct ev_periodic *w,
573ev_tstamp now)>, e.g.: 574ev_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)
… …
580It 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
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
582will usually be called just before the callback will be triggered, but 583will usually be called just before the callback will be triggered, but
583might be called at other times, too. 584might be called at other times, too.
584 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
585This 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
586triggers 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
587next 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
588is, 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).
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
676Prepare and check watchers are usually (but not always) used in tandem: 681Prepare and check watchers are usually (but not always) used in tandem:
677Prepare watchers get invoked before the process blocks and check watchers 682prepare watchers get invoked before the process blocks and check watchers
678afterwards. 683afterwards.
679 684
680Their main purpose is to integrate other event mechanisms into libev. This 685Their main purpose is to integrate other event mechanisms into libev. This
681could be used, for example, to track variable changes, implement your own 686could be used, for example, to track variable changes, implement your own
682watchers, integrate net-snmp or a coroutine library and lots more. 687watchers, integrate net-snmp or a coroutine library and lots more.
… …
685to be watched by the other library, registering C<ev_io> watchers for 690to be watched by the other library, registering C<ev_io> watchers for
686them and starting an C<ev_timer> watcher for any timeouts (many libraries 691them and starting an C<ev_timer> watcher for any timeouts (many libraries
687provide just this functionality). Then, in the check watcher you check for 692provide just this functionality). Then, in the check watcher you check for
688any events that occured (by checking the pending status of all watchers 693any events that occured (by checking the pending status of all watchers
689and stopping them) and call back into the library. The I/O and timer 694and stopping them) and call back into the library. The I/O and timer
690callbacks will never actually be called (but must be valid neverthelles, 695callbacks will never actually be called (but must be valid nevertheless,
691because you never know, you know?). 696because you never know, you know?).
692 697
693As another example, the Perl Coro module uses these hooks to integrate 698As another example, the Perl Coro module uses these hooks to integrate
694coroutines into libev programs, by yielding to other active coroutines 699coroutines into libev programs, by yielding to other active coroutines
695during each prepare and only letting the process block if no coroutines 700during each prepare and only letting the process block if no coroutines
696are ready to run (its actually more complicated, it only runs coroutines 701are ready to run (it's actually more complicated: it only runs coroutines
697with priority higher than the event loop and one lower priority once, 702with priority higher than or equal to the event loop and one coroutine
698using idle watchers to keep the event loop from blocking if lower-priority 703of lower priority, but only once, using idle watchers to keep the event
699coroutines exist, thus mapping low-priority coroutines to idle/background 704loop from blocking if lower-priority coroutines are active, thus mapping
700tasks). 705low-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
… …
733started. Otherwise an C<ev_timer> watcher with after = C<timeout> (and 738started. Otherwise an C<ev_timer> watcher with after = C<timeout> (and
734repeat = 0) will be started. While C<0> is a valid timeout, it is of 739repeat = 0) will be started. While C<0> is a valid timeout, it is of
735dubious value. 740dubious value.
736 741
737The callback has the type C<void (*cb)(int revents, void *arg)> and gets 742The callback has the type C<void (*cb)(int revents, void *arg)> and gets
738passed an events set like normal event callbacks (with a combination of 743passed an C<revents> set like normal event callbacks (a combination of
739C<EV_ERROR>, C<EV_READ>, C<EV_WRITE> or C<EV_TIMEOUT>) and the C<arg> 744C<EV_ERROR>, C<EV_READ>, C<EV_WRITE> or C<EV_TIMEOUT>) and the C<arg>
740value passed to C<ev_once>: 745value passed to C<ev_once>:
741 746
742 static void stdin_ready (int revents, void *arg) 747 static void stdin_ready (int revents, void *arg)
743 { 748 {
… …
764 769
765Feed an event as if the given signal occured (loop must be the default loop!). 770Feed 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
776TBD.
777
778=head1 C++ SUPPORT
779
780TBD.
781
769=head1 AUTHOR 782=head1 AUTHOR
770 783
771Marc Lehmann <libev@schmorp.de>. 784Marc Lehmann <libev@schmorp.de>.
772 785

Diff Legend

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