[ViewVC] Diff of: cvs/EV/EV.pm

Comparing EV/EV.pm (file contents):
Revision 1.98 by root, Sat May 31 23:17:50 2008 UTC vs.
Revision 1.118 by root, Tue Jul 14 20:31:21 2009 UTC

 =head1 DESCRIPTION
 This module provides an interface to libev
 (L<http://software.schmorp.de/pkg/libev.html>). While the documentation
-below is comprehensive, one might also consult the documentation of libev
+below is comprehensive, one might also consult the documentation of
-itself (L<http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod>) for more
+libev itself (L<http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod> or
-subtle details on watcher semantics or some discussion on the available
+F<perldoc EV::libev>) for more subtle details on watcher semantics or some
-backends, or how to force a specific backend with C<LIBEV_FLAGS>, or just
+discussion on the available backends, or how to force a specific backend
-about in any case because it has much more detailed information.
+with C<LIBEV_FLAGS>, or just about in any case because it has much more
+detailed information.
 This module is very fast and scalable. It is actually so fast that you
 can use it through the L<AnyEvent> module, stay portable to other event
 loops (if you don't rely on any watcher types not available through it)
 and still be faster than with any other event loop currently supported in
 Perl.
+=head2 MODULE EXPORTS
+This module does not export any symbols.
 =cut
 package EV;
-use strict;
+use common::sense;
 BEGIN {
-   our $VERSION = '3.42';
+   our $VERSION = '3.7';
    use XSLoader;
    XSLoader::load "EV", $VERSION;
 }
 @EV::IO::ISA       =
 default loop as this is fastest (perl-wise), best supported by other
 modules (e.g. AnyEvent or Coro) and most portable event loop.
 For specific programs you can create additional event loops dynamically.
-=over 4
+If you want to take advantage of kqueue (which often works properly for
+sockets only) even though the default loop doesn't enable it, you can
+I<embed> a kqueue loop into the default loop: running the default loop
+will then also service the kqueue loop to some extent. See the example in
+the section about embed watchers for an example on how to achieve that.
+=over 4
-=item $loop = new EV::loop [$flags]
+=item $loop = new EV::Loop [$flags]
-Create a new event loop as per the specified flags. Please refer to the
+Create a new event loop as per the specified flags. Please refer to
-C<ev_loop_new ()> function description in the libev documentation
+the C<ev_loop_new ()> function description in the libev documentation
-(L<http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod#GLOBAL_FUNCTIONS>)
+(L<http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod#GLOBAL_FUNCTIONS>,
-for more info.
+or locally-installed as F<EV::libev> manpage) for more info.
 The loop will automatically be destroyed when it is no longer referenced
 by any watcher and the loop object goes out of scope.
-Using C<EV::FLAG_FORKCHECK> is recommended, as only the default event loop
+If you are not embedding the loop, then Using C<EV::FLAG_FORKCHECK>
-is protected by this module.
+is recommended, as only the default event loop is protected by this
+module. If you I<are> embedding this loop in the default loop, this is not
+necessary, as C<EV::embed> automatically does the right thing on fork.
 =item $loop->loop_fork
 Must be called after a fork in the child, before entering or continuing
 the event loop. An alternative is to use C<EV::FLAG_FORKCHECK> which calls
 documentation).
 =item $loop->loop_verify
 Calls C<ev_verify> to make internal consistency checks (for debugging
-libev) and abort the program if any data structures wree found to be
+libev) and abort the program if any data structures were found to be
 corrupted.
 =item $loop = EV::default_loop [$flags]
 Return the default loop (which is a singleton object). Since this module
 already creates the default loop with default flags, specifying flags here
-will not have any effect unless you destroy the default loop.
+will not have any effect unless you destroy the default loop first, which
+isn't supported. So in short: don't do it, and if you break it, you get to
+keep the pieces.
 =back
 =head1 BASIC INTERFACE
 =item $time = EV::now
 =item $time = $loop->now
 Returns the time the last event loop iteration has been started. This
-is the time that (relative) timers are based on, and refering to it is
+is the time that (relative) timers are based on, and referring to it is
 usually faster then calling EV::time.
+=item EV::now_update
+=item $loop->now_update
+Establishes the current time by querying the kernel, updating the time
+returned by C<EV::now> in the progress. This is a costly operation and
+is usually done automatically within C<EV::loop>.
+This function is rarely useful, but when some event callback runs for a
+very long time without entering the event loop, updating libev's idea of
+the current time is a good idea.
+=item EV::suspend
+=item $loop->suspend
+=item EV::resume
+=item $loop->resume
+These two functions suspend and resume a loop, for use when the loop is
+not used for a while and timeouts should not be processed.
+A typical use case would be an interactive program such as a game:  When
+the user presses C<^Z> to suspend the game and resumes it an hour later it
+would be best to handle timeouts as if no time had actually passed while
+the program was suspended. This can be achieved by calling C<suspend>
+in your C<SIGTSTP> handler, sending yourself a C<SIGSTOP> and calling
+C<resume> directly afterwards to resume timer processing.
+Effectively, all C<timer> watchers will be delayed by the time spend
+between C<suspend> and C<resume>, and all C<periodic> watchers
+will be rescheduled (that is, they will lose any events that would have
+occured while suspended).
+After calling C<suspend> you B<must not> call I<any> function on the given
+loop other than C<resume>, and you B<must not> call C<resume>
+without a previous call to C<suspend>.
+Calling C<suspend>/C<resume> has the side effect of updating the event
+loop time (see C<now_update>).
 =item $backend = EV::backend
 =item $backend = $loop->backend
-Returns an integer describing the backend used by libev (EV::METHOD_SELECT
+Returns an integer describing the backend used by libev (EV::BACKEND_SELECT
-or EV::METHOD_EPOLL).
+or EV::BACKEND_EPOLL).
 =item EV::loop [$flags]
 =item $loop->loop ([$flags])
 =item $count = EV::loop_count
 =item $count = $loop->loop_count
 Return the number of times the event loop has polled for new
-events. Sometiems useful as a generation counter.
+events. Sometimes useful as a generation counter.
 =item EV::once $fh_or_undef, $events, $timeout, $cb->($revents)
 =item $loop->once ($fh_or_undef, $events, $timeout, $cb->($revents))
 =item $loop->set_timeout_collect_interval ($time)
 These advanced functions set the minimum block interval when polling for I/O events and the minimum
 wait interval for timer events. See the libev documentation at
-L<http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod#FUNCTIONS_CONTROLLING_THE_EVENT_LOOP> for
+L<http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod#FUNCTIONS_CONTROLLING_THE_EVENT_LOOP>
-a more detailed discussion.
+(locally installed as F<EV::libev>) for a more detailed discussion.
 =back
 =head1 WATCHER OBJECTS
 called with at least two arguments: the watcher and a bitmask of received
 events.
 Each watcher type has its associated bit in revents, so you can use the
 same callback for multiple watchers. The event mask is named after the
-type, i..e. EV::child sets EV::CHILD, EV::prepare sets EV::PREPARE,
+type, i.e. EV::child sets EV::CHILD, EV::prepare sets EV::PREPARE,
 EV::periodic sets EV::PERIODIC and so on, with the exception of I/O events
 (which can set both EV::READ and EV::WRITE bits), and EV::timer (which
 uses EV::TIMEOUT).
 In the rare case where one wants to create a watcher but not start it at
 because you happen to have this long-running UDP port watcher.
 In this case you can clear the keepalive status, which means that even
 though your watcher is active, it won't keep C<EV::loop> from returning.
-The initial value for keepalive is true (enabled), and you cna change it
+The initial value for keepalive is true (enabled), and you can change it
 any time.
 Example: Register an I/O watcher for some UDP socket but do not keep the
 event loop from running just because of that watcher.
       # make the dispatcher handle any new stuff
       ... not shown
    };
 The callbacks of the created watchers will not be called as the watchers
-are destroyed before this cna happen (remember EV::check gets called
+are destroyed before this can happen (remember EV::check gets called
 first).
 The C<check_ns> variant doesn't start (activate) the newly created watcher.
 =back
 loop, other types of watchers might be handled in a delayed or incorrect
 fashion and must not be used).
 See the libev documentation at
 L<http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod#code_ev_embed_code_when_one_backend_>
-for more details.
+(locally installed as F<EV::libev>) for more details.
 In short, this watcher is most useful on BSD systems without working
 kqueue to still be able to handle a large number of sockets:
    my $socket_loop;
    # use the default loop otherwise
    $socket_loop ||= EV::default_loop;
 =over 4
-=item $w = EV::embed $otherloop, $callback
+=item $w = EV::embed $otherloop[, $callback]
-=item $w = EV::embed_ns $otherloop, $callback
+=item $w = EV::embed_ns $otherloop[, $callback]
-=item $w = $loop->embed ($otherloop, $callback)
+=item $w = $loop->embed ($otherloop[, $callback])
-=item $w = $loop->embed_ns ($otherloop, $callback)
+=item $w = $loop->embed_ns ($otherloop[, $callback])
 Call the callback when the embedded event loop (C<$otherloop>) has any
-I/O activity. The C<$callback> should alwas be specified as C<undef> in
+I/O activity. The C<$callback> is optional: if it is missing, then the
-this version of EV, which means the embedded event loop will be managed
+embedded event loop will be managed automatically (which is recommended),
-automatically.
+otherwise you have to invoke C<sweep> yourself.
 The C<embed_ns> variant doesn't start (activate) the newly created watcher.
 =back
 =head3 ASYNC WATCHERS - how to wake up another event loop
-Async watchers are provided by EV, but have little use in perl directly, as perl
+Async watchers are provided by EV, but have little use in perl directly,
-neither supports threads nor direct access to signal handlers or other
+as perl neither supports threads running in parallel nor direct access to
-contexts where they could be of value.
+signal handlers or other contexts where they could be of value.
 It is, however, possible to use them from the XS level.
 Please see the libev documentation for further details.
    my $async_check = EV::check sub { };
 This ensures that perl gets into control for a short time to handle any
 pending signals, and also ensures (slightly) slower overall operation.
-=head1 THREADS
+=head1 ITHREADS
-Threads are not supported by this module in any way. Perl pseudo-threads
+Ithreads are not supported by this module in any way. Perl pseudo-threads
-is evil stuff and must die. As soon as Perl gains real threads I will work
+is evil stuff and must die. Real threads as provided by Coro are fully
-on thread support for it.
+supported (and enhanced support is available via L<Coro::EV>).
 =head1 FORK
 Most of the "improved" event delivering mechanisms of modern operating
 systems have quite a few problems with fork(2) (to put it bluntly: it is

Diff Legend

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

Comparing EV/EV.pm (file contents): Revision 1.98 by root, Sat May 31 23:17:50 2008 UTC vs. Revision 1.118 by root, Tue Jul 14 20:31:21 2009 UTC

Diff Legend

Comparing EV/EV.pm (file contents):
Revision 1.98 by root, Sat May 31 23:17:50 2008 UTC vs.
Revision 1.118 by root, Tue Jul 14 20:31:21 2009 UTC