NAME

SYNOPSIS

  #!/usr/bin/perl

  use strict;
  use Continuity;

  my $server = new Continuity;
  $server->loop;

  sub main {
    my $request = shift;
    $request->print("Your name: <form><input type=text name=name></form>");
    $request->next; # this waits for the form to be submitted!
    my $name = $request->param('name');
    $request->print("Hello $name!");
  }

DESCRIPTION

The program is passed a $request variable which holds the request (including any form data) sent from the browser. In concept, this is a lot like a $cgi object from CGI.pm with one very very significant difference. At any point in the code you can call $request->next. Your program will then suspend, waiting for the next request in the session. Since the program doesn't actually halt, all state is preserved, including lexicals -- getting input from the browser is then similar to doing "$line = <>" in a command-line application.

GETTING STARTED

Here's a simple example:

  #!/usr/bin/perl

  use strict;
  use Continuity;

  my $server = new Continuity;
  $server->loop;

  sub main {
    my $request = shift;
    while(1) {
      $request->print("Hello, world!");
      $request->next;
      $request->print("Hello again!");
    }
  }

First, check out the small demo applications in the eg/ directory of the distribution. Sample code there ranges from simple counters to more complex multi-user ajax applications. All of the basic uses and some of the advanced uses of Continuity are covered there.

Here is an brief explanation of what you will find in a typical application.

Declare all your globals, then declare and create your server. Parameters to the server will determine how sessions are tracked, what ports it listens on, what will be served as static content, and things of that nature. You are literally initializing a web server that will serve your application to client browsers. Then call the "loop" method of the server, which will get the server listening for incoming requests and starting new sessions (this never exits).

  use Continuity;
  my $server = Continuity->new( port => 8080 );
  $server->loop;

Continuity must have a starting point when starting new sessions for your application. The default is "\&::main" (a sub named "main" in the default global scope), which is passed the $request handle. See the Continuity::Request documentation for details on the methods available from the $request object beyond this introduction.

  sub main {
    my $request = shift;
    # ...
  }

Outputting to the client (that is, sending text to the browser) is done by calling the "$request->print(...)" method, rather than the plain "print" used in CGI.pm applications.

  $request->print("Hello, guvne'<br>");
  $request->print("'ow ya been?");

HTTP query parameters (both GET and POST) are also gotten through the $request handle, by calling "$p = $request->param('x')", just like in CGI.pm.

  # If they go to http://webapp/?x=7
  my $input = $request->param('x');
  # now $input is 7

Once you have output your HTML, call "$request->next" to wait for the next response from the client browser. While waiting other sessions will handle other requests, allowing the single process to handle many simultaneous sessions.

  $request->print("Name: <form><input type=text name=n></form>");
  $request->next;                   # <-- this is where we suspend execution
  my $name = $request->param('n');  # <-- start here once they submit

Anything declared lexically (using my) inside of "main" is private to the session, and anything you make global is available to all sessions. When "main" returns the session is terminated, so that another request from the same client will get a new session. Only one continuation is ever executing at a given time, so there is no immediate need to worry about locking shared global variables when modifying them.

ADVANCED USAGE

  use Continuity;
  use strict;
  my @callbacks;
  my $callback_count;
  Continuity->new->loop;
  sub gen_link {
    my ($text, $code) = @_;
    $callbacks[$callback_count++] = $code;
    return qq{<a href="?cb=$callback_count">$text</a>};
  }
  sub process_links {
    my $request = shift;
    my $cb = $request->param('cb');
    if(exists $callbacks[$cb]) {
      $callbacks[$cb]->($request);
      delete $callbacks[$cb];
    }
  }
  sub main {
    my $request = shift;
    my $x;
    my $link1 = gen_link('This is a link to stuff' => sub { $x = 7  });
    my $link2 = gen_link('This is another link'    => sub { $x = 42 });
    $request->print($link1, $link2);
    $request->next;
    process_links($request);
    $request->print("\$x is now: $x");
  }

EXTENDING AND CUSTOMIZING

The Adapter, such as the default Continuity::Adapt::HttpDaemon, actually makes the HTTP connections with the client web browser. If you want to use FastCGI or even a non-HTTP protocol, then you will use or create an Adapter.

The Mapper, such as the default Continuity::Mapper, identifies incoming requests from The Adapter and maps them to instances of your program. In other words, Mappers keep track of sessions, figuring out which requests belong to which session. The default mapper can identify sessions based on any combination of cookie, IP address, and URL path. Override The Mapper to create alternative session identification and management.

METHODS

SEE ALSO

Website/Wiki: <http://continuity.tlt42.org/>

Continuity::Request, Continuity::RequestCallbacks, Continuity::Mapper, Continuity::Adapt::HttpDaemon, Coro

AnyEvent::DBI and Coro::Mysql for concurrent database access.

AUTHOR

  Brock Wilcox <awwaiid@thelackthereof.org> - http://thelackthereof.org/
  Scott Walters <scott@slowass.net> - http://slowass.net/
  Special thanks to Marc Lehmann for creating (and maintaining) Coro

COPYRIGHT

  Copyright (c) 2004-2014 Brock Wilcox <awwaiid@thelackthereof.org>. All
  rights reserved.  This program is free software; you can redistribute it
  and/or modify it under the same terms as Perl itself.