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

Comparing EV/EV.pm (file contents):
Revision 1.73 by root, Fri Dec 21 05:10:01 2007 UTC vs.
Revision 1.79 by root, Sat Dec 22 16:37:07 2007 UTC

 selecting a working backend (which for example rules out kqueue on most
 BSDs). Modules should, unless they have "special needs" always use the
 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 cna create additional event loops dynamically.
+For specific programs you can create additional event loops dynamically.
 =over 4
 =item $loop = new EV::loop [$flags]
 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
 this fucntion automatically, at some performance loss (refer to the libev
 documentation).
+=item $loop = EV::default_loop [$flags]
+Return the default loop (which is a singleton object).
 =back
 =head1 BASIC INTERFACE
 Must contain a reference to a function that is called when a callback
 throws an exception (with $@ containing the error). The default prints an
 informative message and continues.
 If this callback throws an exception it will be silently ignored.
+=item $flags = EV::supported_backends
+=item $flags = EV::recommended_backends
+=item $flags = EV::embeddable_backends
+Returns the set (see C<EV::BACKEND_*> flags) of backends supported by this
+instance of EV, the set of recommended backends (supposed to be good) for
+this platform and the set of embeddable backends (see EMBED WATCHERS).
 =item $time = EV::time
 Returns the current time in (fractional) seconds since the epoch.
 If timeout is C<undef> or negative, then there will be no
 timeout. Otherwise a EV::timer with this value will be started.
 When an error occurs or either the timeout or I/O watcher triggers, then
 the callback will be called with the received event set (in general
-you can expect it to be a combination of C<EV:ERROR>, C<EV::READ>,
+you can expect it to be a combination of C<EV::ERROR>, C<EV::READ>,
 C<EV::WRITE> and C<EV::TIMEOUT>).
 EV::once doesn't return anything: the watchers stay active till either
 of them triggers, then they will be stopped and freed, and the callback
 invoked.
 =item EV::feed_signal_event ($signal)
 Feed a signal event into EV. EV will react to this call as if the signal
 specified by C<$signal> had occured.
+=item EV::set_io_collect_interval $time
+=item $loop->set_io_collect_interval ($time)
+=item EV::set_timeout_collect_interval $time
+=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
+a more detailed discussion.
 =back
 =head1 WATCHER OBJECTS
 event. For instance, if you want to wait for STDIN to become readable, you
 would create an EV::io watcher for that:
   my $watcher = EV::io *STDIN, EV::READ, sub {
      my ($watcher, $revents) = @_;
-     warn "yeah, STDIN should not be readable without blocking!\n"
+     warn "yeah, STDIN should now be readable without blocking!\n"
   };
 All watchers can be active (waiting for events) or inactive (paused). Only
 active watchers will have their callbacks invoked. All callbacks will be
 called with at least two arguments: the watcher and a bitmask of received
 Feed some events on this watcher into EV. EV will react to this call as if
 the watcher had received the given C<$revents> mask.
 =item $revents = $w->clear_pending
-If the watcher is pending, this function returns clears its pending status
+If the watcher is pending, this function clears its pending status and
-and returns its C<$revents> bitset (as if its callback was invoked). If the
+returns its C<$revents> bitset (as if its callback was invoked). If the
 watcher isn't pending it does nothing and returns C<0>.
 =item $previous_state = $w->keepalive ($bool)
 Normally, C<EV::loop> will return when there are no active watchers
 (which is a "deadlock" because no progress can be made anymore). This is
 convinient because it allows you to start your watchers (and your jobs),
 call C<EV::loop> once and when it returns you know that all your jobs are
 finished (or they forgot to register some watchers for their task :).
-Sometimes, however, this gets in your way, for example when you the module
+Sometimes, however, this gets in your way, for example when the module
 that calls C<EV::loop> (usually the main program) is not the same module
 as a long-living watcher (for example a DNS client module written by
 somebody else even). Then you might want any outstanding requests to be
 handled, but you would not want to keep C<EV::loop> from returning just
 because you happen to have this long-running UDP port watcher.
 Example: Register an I/O watcher for some UDP socket but do not keep the
 event loop from running just because of that watcher.
    my $udp_socket = ...
    my $udp_watcher = EV::io $udp_socket, EV::READ, sub { ... };
-   $udp_watcher->keepalive (0);
+   $1000udp_watcher->keepalive (0);
+=item $loop = $w->loop
+Return the loop that this watcher is attached to.
 =back
 =head1 WATCHER TYPES
 =item $w = EV::io $fileno_or_fh, $eventmask, $callback
 =item $w = EV::io_ns $fileno_or_fh, $eventmask, $callback
-=item $w = $loop->io 8$fileno_or_fh, $eventmask, $callback)
+=item $w = $loop->io ($fileno_or_fh, $eventmask, $callback)
 =item $w = $loop->io_ns ($fileno_or_fh, $eventmask, $callback)
 As long as the returned watcher object is alive, call the C<$callback>
 when at least one of events specified in C<$eventmask> occurs.
 =item $w = EV::prepare_ns $callback
 =item $w = $loop->prepare ($callback)
-=item $w = $loop->prepare_ns 8$callback)
+=item $w = $loop->prepare_ns ($callback)
 Call the callback just before the process would block. You can still
 create/modify any watchers at this point.
 See the EV::check watcher, below, for explanations and an example.
 The C<fork_ns> variant doesn't start (activate) the newly created watcher.
 =back
+=head3 EMBED WATCHERS - when one backend isn't enough...
+This is a rather advanced watcher type that lets you embed one event loop
+into another (currently only IO events are supported in the embedded
+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.
+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;
+  # check wether we use SELECT or POLL _and_ KQUEUE is supported
+  if (
+    (EV::backend & (EV::BACKEND_POLL | EV::BACKEND_SELECT))
+    && (EV::supported_backends & EV::embeddable_backends & EV::BACKEND_KQUEUE)
+  ) {
+    # use kqueue for sockets
+    $socket_loop = new EV::Loop EV::BACKEND_KQUEUE | EV::FLAG_NOENV;
+  }
+  # use the default loop otherwise
+  $socket_loop ||= EV::default_loop;
+=over 4
+=item $w = EV::embed $otherloop, $callback
+=item $w = EV::embed_ns $otherloop, $callback
+=item $w = $loop->embed ($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
+this version of EV, which means the embedded event loop will be managed
+automatically.
+The C<embed_ns> variant doesn't start (activate) the newly created watcher.
+=back
 =head1 PERL SIGNALS
 While Perl signal handling (C<%SIG>) is not affected by EV, the behaviour
 with EV is as the same as any other C library: Perl-signals will only be
 handled when Perl runs, which means your signal handler might be invoked
 to be called on every event loop iteration by installing a C<EV::check>
 watcher:
    my $async_check = EV::check sub { };
-This ensures that perl shortly gets into control for a short time, and
+This ensures that perl gets into control for a short time to handle any
-also ensures slower overall operation.
+pending signals, and also ensures (slightly) slower overall operation.
 =head1 THREADS
 Threads 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

Diff Legend

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

Comparing EV/EV.pm (file contents): Revision 1.73 by root, Fri Dec 21 05:10:01 2007 UTC vs. Revision 1.79 by root, Sat Dec 22 16:37:07 2007 UTC

Diff Legend

Comparing EV/EV.pm (file contents):
Revision 1.73 by root, Fri Dec 21 05:10:01 2007 UTC vs.
Revision 1.79 by root, Sat Dec 22 16:37:07 2007 UTC