view release on metacpan or  search on metacpan

lib/Squatting/On/Continuity.pm  view on Meta::CPAN

  use App 'On::Continuity';
  App->init;
  App->continue(port => 2012);

=head1 DESCRIPTION

The purpose of this module is to add a C<continue> method to your app that will
start a Continuity-based web server when invoked.  To use this module, pass the
string C<'On::Continuity'> to the C<use> statement that loads your Squatting
app.

=head1 API 

=head2 Continuity meets MVC (or just VC, actually)

=head3 App->continue(%options)

This method starts a Continuity-based web server.  The %options are passed
straight through to Continuity, and they let you specify things like what port
to run the server on.

=head1 EXPLANATION

=head2 The Special Powers of Continuity

L<Continuity> has 2 highly unusual (but useful) capabilities.

=over 4

=item 1. It can hold many simultaneous HTTP connections open.

=item 2. It can "pause" execution until the next request comes in.

=back

The easiest way to explain this is by example.

=head2 Becoming RESTless

Consider this controller which has an infinite loop in it.

  C(
    Count => [ '/@count' ],
    get => sub {
      my ($self) = @_;
      my $cr     = $self->cr;
      my $i      = 1;
      while (1) {
        $cr->print($i++);
        $cr->next;
      }
    },
    continuity => 1,
  )

Here, the code is dropping down to the Continuity level.  The C<$cr> variable
contains a L<Continuity::Request> object, and with that in hand, we can try
something as audacious as an infinite loop.  However, this while loop does not
spin out of control and eat up all your CPU.  The C<$cr-E<gt>next> statement
will pause execution of the current coroutine, and it will wait until the
next HTTP request to come in.  Thus, you can hit reload multiple times and
watch C<$i> increment each time.

However, not just any HTTP request will wake this coroutine up.  To make
C<$cr-E<gt>next> stop blocking, a request with the following properties will
have to come in.

=over 4

=item It has to have the same session_id.

=item It has to be for the same controller.

=item It has to be a GET request.

=back

The key is this line:

  queue => { get => 'name_of_queue' }

When you're squatting on Continuity, you're allowed to define your controllers
with a C<queue> attribute.  It should contain a hashref where the keys are HTTP
methods (in lower case) and the values are unique strings that will be used
internally by Continuity to differentiate one queue of requests from another.

Every method mentioned in C<queue> will be given its own coroutine to run in.

=head2 Pausing for Other Events

TO BE CONTINUED...

For a sneak peak, take a look at the Chat application in the F<eg/> directory.

=head1 SEE ALSO

L<Coro>, L<Continuity>, L<Continuity::Mapper>, L<Squatting::Mapper>

=cut

# Local Variables: ***
# mode: cperl ***
# indent-tabs-mode: nil ***
# cperl-close-paren-offset: -2 ***
# cperl-continued-statement-offset: 2 ***
# cperl-indent-level: 2 ***
# cperl-indent-parens-as-block: t ***
# cperl-tab-always-indent: nil ***
# End: ***
# vim:tabstop=8 softtabstop=2 shiftwidth=2 shiftround expandtab