[Bps-public-commit] r11037 - in Net-Server-Coro: .

[alexmv at bestpractical.com]

Author: alexmv
Date: Mon Mar 10 16:16:55 2008
New Revision: 11037

Modified:
   Net-Server-Coro/   (props changed)
   Net-Server-Coro/Makefile.PL
   Net-Server-Coro/lib/Net/Server/Coro.pm

Log:
 r28396 at kohr-ah:  chmrr | 2008-03-10 16:16:25 -0400
  * POD, fix licensing.


Modified: Net-Server-Coro/Makefile.PL
==============================================================================
--- Net-Server-Coro/Makefile.PL	(original)
+++ Net-Server-Coro/Makefile.PL	Mon Mar 10 16:16:55 2008
@@ -4,7 +4,7 @@
 author ('Alex Vandiver <alexmv at bestpractical.com>');
 version_from ('lib/Net/Server/Coro.pm');
 abstract_from('lib/Net/Server/Coro.pm');
-license('perl');
+license('MIT');
 
 requires('Coro');
 requires('EV');

Modified: Net-Server-Coro/lib/Net/Server/Coro.pm
==============================================================================
--- Net-Server-Coro/lib/Net/Server/Coro.pm	(original)
+++ Net-Server-Coro/lib/Net/Server/Coro.pm	Mon Mar 10 16:16:55 2008
@@ -1,7 +1,8 @@
-package Net::Server::Coro;
-
 use strict;
 use warnings;
+
+package Net::Server::Coro;
+
 use vars qw($VERSION);
 use EV;
 use Coro;
@@ -10,7 +11,36 @@
 
 $VERSION = 0.2;
 
-use vars qw/$SELF @FH/;
+=head1 NAME
+
+Net::Server::Coro - A co-operative multithreaded server using Coro
+
+=head1 SYNOPSIS
+
+    use Coro;
+    use base qw/Net::Server::Coro/;
+
+    __PACKAGE__->new->run;
+
+    sub process_request {
+       ...
+       cede;
+       ...
+    }
+
+=head1 DESCRIPTION
+
+L<Net::Server::Coro> implements multithreaded server for the
+L<Net::Server> architecture, using L<Coro> and L<Coro::Socket> to make
+all reads and writes non-blocking.  Additionally, it supports
+non-blocking SSL negotiation.
+
+=head1 METHODS
+
+Most methods are inherited from L<Net::Server> -- see it for further
+usage details.
+
+=cut
 
 sub post_bind_hook {
     my $self = shift;
@@ -18,6 +48,13 @@
     $prop->{sock} = [ map { make_coro_socket($_) } @{ $prop->{sock} } ];
 }
 
+=head2 make_coro_socket SOCKET
+
+Takes an L<IO::Socket> or L<Net::Server::Proto> object, and converts
+it into a L<Net::Server::Proto::Coro> object.
+
+=cut
+
 sub make_coro_socket {
     my $socket = shift;
     my @extra;
@@ -33,18 +70,42 @@
     return $socket;
 }
 
-sub handler {
+sub coro_instance {
+    my $self = shift;
     my $fh   = shift;
-    my $prop = $SELF->{server};
+    my $prop = $self->{server};
     $Coro::current->desc("Active connection");
     $prop->{client} = $fh;
-    $SELF->run_client_connection;
+    $self->run_client_connection;
     close $fh;
 }
 
-### prepare for connections
+=head2 loop
+
+The main loop uses starts a number of L<Coro> coroutines:
+
+=over 4
+
+=item *
+
+One for each listening socket.
+
+=item *
+
+One for each active connection.  Since these may respawn on a firlay
+frequent basis, L<Coro/async_pool> is used to maintain a pool of
+coroutines.
+
+=item *
+
+The L<EV> event loop.
+
+=back
+
+=cut
+
 sub loop {
-    my $self = $SELF = shift;
+    my $self = shift;
     my $prop = $self->{server};
 
     for my $socket ( @{ $prop->{sock} } ) {
@@ -53,7 +114,7 @@
             while (1) {
                 my $accepted = scalar $socket->accept;
                 next unless $accepted;
-                async_pool \&handler, $accepted;
+                async_pool \&coro_instance, $self, $accepted;
             }
         };
     }
@@ -69,15 +130,59 @@
         # Use EV signal handlers;
         my @shutdown = map EV::signal( $_ => sub { $self->server_close; } ),
             qw/INT TERM QUIT/;
-        my $hup = EV::signal( HUP => sub { $self->sig_hup } );
-        while (1) {
-            EV::loop();
-        }
+        EV::loop() while 1;
     };
 
     schedule;
 }
 
+=head1 DEPENDENCIES
+
+L<Coro>, L<EV>, L<Net::Server>
+
+=head1 BUGS AND LIMITATIONS
+
+Generally, all those of L<Coro>.  Please report any bugs or feature
+requests specific to L<Net::Server::Coro> to
+C<bug-net-server-coro at rt.cpan.org>, or through the web interface at
+L<http://rt.cpan.org>.
+
+=head1 AUTHORS
+
+Alex Vandiver C<< <alexmv at bestpractical.com> >>; code originally from
+Audrey Tang C<< <cpan at audreyt.org> >>
+
+=head1 COPYRIGHT
+
+Copyright 2006 by Audrey Tang <cpan at audreyt.org>
+
+Copyright 2007-2008 by Best Practical Solutions
+
+This software is released under the MIT license cited below.
+
+=head2 The "MIT" License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+=cut
+
 ## Due to outstanding patches for Net::Server
 use Net::Server::Proto::TCP;