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

Comparing EV/EV.pm (file contents):
Revision 1.75 by root, Fri Dec 21 10:36:22 2007 UTC vs.
Revision 1.80 by root, Sat Dec 22 16:48:33 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 EV::sleep $seconds
+Block the process for the given number of (fractional) seconds.
 =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.
 =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.
 Call the callback before the event loop is resumed in the child process
 after a fork.
 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

Diff Legend

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

Comparing EV/EV.pm (file contents): Revision 1.75 by root, Fri Dec 21 10:36:22 2007 UTC vs. Revision 1.80 by root, Sat Dec 22 16:48:33 2007 UTC

Diff Legend

Comparing EV/EV.pm (file contents):
Revision 1.75 by root, Fri Dec 21 10:36:22 2007 UTC vs.
Revision 1.80 by root, Sat Dec 22 16:48:33 2007 UTC