mention that some reactors stop automatically

mojolicious · Aug 8, 2012 · ba33039 · ba33039
1 parent 8193a70
commit ba33039
Show file tree

Hide file tree

Showing 10 changed files with 50 additions and 47 deletions.
diff --git a/examples/connect-proxy.pl b/examples/connect-proxy.pl
@@ -73,7 +73,7 @@
 For testing use something like "HTTPS_PROXY=http://127.0.0.1:3000".
 EOF
 
-# Start loop
+# Start event loop
 Mojo::IOLoop->start;
 
 1;
diff --git a/examples/microhttpd.pl b/examples/microhttpd.pl
@@ -44,7 +44,7 @@
 On a MacBook Pro 13" this results in about 16k req/s.
 EOF
 
-# Start loop
+# Start event loop
 Mojo::IOLoop->start;
 
 1;
diff --git a/lib/Mojo/IOLoop.pm b/lib/Mojo/IOLoop.pm
@@ -282,7 +282,7 @@ sub _stream {
 
 =head1 NAME
 
-Mojo::IOLoop - Minimalistic reactor for non-blocking TCP clients and servers
+Mojo::IOLoop - Minimalistic event loop
 
 =head1 SYNOPSIS
 
@@ -324,14 +324,14 @@ Mojo::IOLoop - Minimalistic reactor for non-blocking TCP clients and servers
     $loop->remove($id);
   });
 
-  # Start loop if necessary
+  # Start event loop if necessary
   Mojo::IOLoop->start unless Mojo::IOLoop->is_running;
 
 =head1 DESCRIPTION
 
-L<Mojo::IOLoop> is a very minimalistic reactor based on L<Mojo::Reactor>, it
-has been reduced to the absolute minimal feature set required to build solid
-and scalable non-blocking TCP clients and servers.
+L<Mojo::IOLoop> is a very minimalistic event loop based on L<Mojo::Reactor>,
+it has been reduced to the absolute minimal feature set required to build
+solid and scalable non-blocking TCP clients and servers.
 
 Optional modules L<EV> (4.0+), L<IO::Socket::IP> (0.16+) and
 L<IO::Socket::SSL> (1.75+) are supported transparently, and used if installed.
@@ -378,9 +378,9 @@ this callback are not captured.
   my $max = $loop->max_accepts;
   $loop   = $loop->max_accepts(1000);
 
-The maximum number of connections this loop is allowed to accept before
+The maximum number of connections this event loop is allowed to accept before
 shutting down gracefully without interrupting existing connections, defaults
-to C<0>. Setting the value to C<0> will allow this loop to accept new
+to C<0>. Setting the value to C<0> will allow this event loop to accept new
 connections indefinitely. Note that up to half of this value can be subtracted
 randomly to improve load balancing between multiple server processes.
 
@@ -389,11 +389,11 @@ randomly to improve load balancing between multiple server processes.
   my $max = $loop->max_connections;
   $loop   = $loop->max_connections(1000);
 
-The maximum number of parallel connections this loop is allowed to handle
-before stopping to accept new incoming connections, defaults to C<1000>.
-Setting the value to C<0> will make this loop stop accepting new connections
-and allow it to shut down gracefully without interrupting existing
-connections.
+The maximum number of parallel connections this event loop is allowed to
+handle before stopping to accept new incoming connections, defaults to
+C<1000>. Setting the value to C<0> will make this event loop stop accepting
+new connections and allow it to shut down gracefully without interrupting
+existing connections.
 
 =head2 C<reactor>
 
@@ -472,7 +472,7 @@ Find a free TCP port, this is a utility function primarily used for tests.
   my $success = Mojo::IOLoop->is_running;
   my $success = $loop->is_running;
 
-Check if loop is running.
+Check if event loop is running.
 
   exit unless Mojo::IOLoop->is_running;
 
@@ -481,8 +481,8 @@ Check if loop is running.
   Mojo::IOLoop->one_tick;
   $loop->one_tick;
 
-Run reactor until an event occurs. Note that this method can recurse back into
-the reactor, so you need to be careful.
+Run event loop until an event occurs. Note that this method can recurse back
+into the reactor, so you need to be careful.
 
 =head2 C<recurring>
 
@@ -522,8 +522,8 @@ as L<Mojo::IOLoop::Server/"listen">.
 
   my $loop = Mojo::IOLoop->singleton;
 
-The global L<Mojo::IOLoop> singleton, used to access a single shared loop
-object from everywhere inside the process.
+The global L<Mojo::IOLoop> singleton, used to access a single shared event
+loop object from everywhere inside the process.
 
   # Many methods also allow you to take shortcuts
   Mojo::IOLoop->timer(2 => sub { Mojo::IOLoop->stop });
@@ -534,18 +534,19 @@ object from everywhere inside the process.
   Mojo::IOLoop->start;
   $loop->start;
 
-Start the loop, this will block until C<stop> is called.
+Start the event loop, this will block until C<stop> is called. Note that some
+reactors stop automatically if there are no events being watched anymore.
 
-  # Start loop only if it is not running already
+  # Start event loop only if it is not running already
   Mojo::IOLoop->start unless Mojo::IOLoop->is_running;
 
 =head2 C<stop>
 
   Mojo::IOLoop->stop;
   $loop->stop;
 
-Stop the loop, this will not interrupt any existing connections and the loop
-can be restarted by running C<start> again.
+Stop the event loop, this will not interrupt any existing connections and the
+event loop can be restarted by running C<start> again.
 
 =head2 C<stream>
 

diff --git a/lib/Mojo/IOLoop/Delay.pm b/lib/Mojo/IOLoop/Delay.pm
@@ -78,7 +78,8 @@ L<Mojo::IOLoop::Delay> implements the following attributes.
   my $ioloop = $delay->ioloop;
   $delay     = $delay->ioloop(Mojo::IOLoop->new);
 
-Loop object to control, defaults to the global L<Mojo::IOLoop> singleton.
+Event loop object to control, defaults to the global L<Mojo::IOLoop>
+singleton.
 
 =head1 METHODS
 

diff --git a/lib/Mojo/Reactor.pm b/lib/Mojo/Reactor.pm
@@ -155,7 +155,8 @@ Remove handle or timer. Meant to be overloaded in a subclass.
   $reactor->start;
 
 Start watching for I/O and timer events, this will block until C<stop> is
-called. Meant to be overloaded in a subclass.
+called. Note that some reactors stop automatically if there are no events
+being watched anymore. Meant to be overloaded in a subclass.
 
 =head2 C<stop>
 

diff --git a/lib/Mojo/Server/Daemon.pm b/lib/Mojo/Server/Daemon.pm
@@ -341,8 +341,8 @@ inactive indefinitely.
   my $loop = $daemon->ioloop;
   $daemon  = $daemon->ioloop(Mojo::IOLoop->new);
 
-Loop object to use for I/O operations, defaults to the global L<Mojo::IOLoop>
-singleton.
+Event loop object to use for I/O operations, defaults to the global
+L<Mojo::IOLoop> singleton.
 
 =head2 C<listen>
 

diff --git a/lib/Mojo/UserAgent.pm b/lib/Mojo/UserAgent.pm
@@ -117,7 +117,7 @@ sub start {
   }
   $self->_start($tx => sub { $tx = $_[1] });
 
-  # Start loop
+  # Start event loop
   $self->ioloop->start;
 
   return $tx;
@@ -352,7 +352,7 @@ sub _handle {
       unless $self->_redirect($c, $old);
   }
 
-  # Stop loop if necessary
+  # Stop event loop if necessary
   $self->ioloop->stop if !$self->{nb} && !keys %{$self->{connections}};
 }
 
@@ -720,8 +720,8 @@ inactive indefinitely.
   my $loop = $ua->ioloop;
   $ua      = $ua->ioloop(Mojo::IOLoop->new);
 
-Loop object to use for blocking I/O operations, defaults to a L<Mojo::IOLoop>
-object.
+Event loop object to use for blocking I/O operations, defaults to a
+L<Mojo::IOLoop> object.
 
 =head2 C<key>
 

diff --git a/lib/Mojolicious/Guides/Cookbook.pod b/lib/Mojolicious/Guides/Cookbook.pod
@@ -11,8 +11,8 @@ This document cotains many fun recipes for cooking with L<Mojolicious>.
 
 Getting L<Mojolicious> and L<Mojolicious::Lite> applications running on
 different platforms. Note that many real-time web features are based on the
-L<Mojo::IOLoop> reactor, and therefore require one of the built-in web servers
-to be able to use them to their full potential.
+L<Mojo::IOLoop> event loop, and therefore require one of the built-in web
+servers to be able to use them to their full potential.
 
 =head2 Built-in web server
 
@@ -274,13 +274,13 @@ The real-time web is a collection of technologies that include Comet
 (long-polling), EventSource and WebSockets, which allow content to be pushed
 to consumers with long-lived connections as soon as it is generated, instead
 of relying on the more traditional pull model. All built-in web servers use
-non-blocking I/O and are based on the L<Mojo::IOLoop> reactor, which provides
-many very powerful features that allow real-time web applications to scale up
-to thousands of clients.
+non-blocking I/O and are based on the L<Mojo::IOLoop> event loop, which
+provides many very powerful features that allow real-time web applications to
+scale up to thousands of clients.
 
 =head2 Backend web services
 
-Since L<Mojo::UserAgent> is also based on the L<Mojo::IOLoop> reactor, it
+Since L<Mojo::UserAgent> is also based on the L<Mojo::IOLoop> event loop, it
 won't block the built-in web servers when used non-blocking, even for high
 latency backend web services.
 
@@ -344,8 +344,8 @@ L<Mojo::IOLoop> delay.
 
 =head2 Timers
 
-Another primary feature of the L<Mojo::IOLoop> reactor are timers, which can
-for example be used to delay rendering of a response, and unlike C<sleep>,
+Another primary feature of the L<Mojo::IOLoop> event loop are timers, which
+can for example be used to delay rendering of a response, and unlike C<sleep>,
 won't block any other requests that might be processed in parallel.
 
   use Mojolicious::Lite;
@@ -621,9 +621,9 @@ which can be combined to solve some of hardest problems in web development.
 
 =head2 Event loops
 
-Internally the L<Mojo::IOLoop> reactor can use multiple event loop backends,
-L<EV> for example will be automatically used if installed. Which in turn
-allows event loops like L<AnyEvent> to just work.
+Internally the L<Mojo::IOLoop> event loop can use multiple event loop
+backends, L<EV> for example will be automatically used if installed. Which in
+turn allows event loops like L<AnyEvent> to just work.
 
   use Mojolicious::Lite;
   use EV;
@@ -908,11 +908,11 @@ can keep many parallel connections active at the same time.
   # Start a bunch of parallel crawlers sharing the same user agent
   crawl($_) for 1 .. 3;
 
-  # Start reactor if necessary
+  # Start event loop if necessary
   Mojo::IOLoop->start unless Mojo::IOLoop->is_running;
 
-You can take full control of the L<Mojo::IOLoop> reactor. Note that real web
-crawlers should respect C<robots.txt> files, and not overwhelm web servers
+You can take full control of the L<Mojo::IOLoop> event loop. Note that real
+web crawlers should respect C<robots.txt> files, and not overwhelm web servers
 with too frequent requests.
 
 =head2 Parallel blocking requests

diff --git a/t/mojo/reactor_ev.t b/t/mojo/reactor_ev.t
@@ -156,7 +156,7 @@ ok !$writable, 'io event was not triggered again';
 my $reactor2 = Mojo::Reactor::EV->new;
 is ref $reactor2, 'Mojo::Reactor::Poll', 'right object';
 
-# Parallel loops
+# Parallel reactors
 $timer = 0;
 $reactor->recurring(0 => sub { $timer++ });
 my $timer2 = 0;

diff --git a/t/mojo/reactor_poll.t b/t/mojo/reactor_poll.t
@@ -156,7 +156,7 @@ ok !$writable, 'io event was not triggered again';
 my $reactor2 = Mojo::Reactor::Poll->new;
 is ref $reactor2, 'Mojo::Reactor::Poll', 'right object';
 
-# Parallel loops
+# Parallel reactors
 $timer = 0;
 $reactor->recurring(0 => sub { $timer++ });
 my $timer2 = 0;