trusty (3) Jifty::Manual::Continuations.3pm.gz
NAME
Jifty::Manual::Continuations - There And Back Again
DESCRIPTION
Continuations are a powerful concept in computer science -- in a nutshell, they allow you to store away
the state of of the interpreter at any given point. More importantly, they allow you to return to that
state at any later time, by calling the continuation with, and evaluation of that interpreter state will
resume. They are a concept that first arose in LISP, but have implementations these days in Ruby,
Scheme, Haskell, and Smalltalk, to name a few.
Thus, continuations allow you to preserve context, and return to it later. This is amazingly useful in
web programming, which is limited to "HTTP", which is an inherently stateless protocol. By passing
around continuations, we can keep track of the context that got us to the current page.
While we can't construct full continuations at the interpreter level -- because Perl does not support
them -- we can implement them at the level of HTTP requests. In technical terms, because they capture
the control stack up from the beginning of a user's session, they are called delimited continuations.
Continuations are more useful than sessions. Sessions store information across browser windows. Sessions
may also break in the presence of the back button, as the information displayed on the screen, and the
information stored in the session may differ. Since continuations are immutable, and a new one is
produced every time a change is made, the information displayed in the browser cannot get out of sync
with the information contained in any associated continuation.
USING CONTINUATIONS
As simple links in templates
The simplest form of continuation use is in a template, using "tangent" in Jifty::Web, as follows:
<% Jifty->web->tangent( url => "/someplace",
label => "Go someplace") %>
This will create a link, which, when clicked, will store the current request into a continuation, and
jump to the url "/someplace". In the "/someplace" template, you can display information, and possibly
have the user navigate between multiple pages before returning to the previous page:
<% Jifty->web->return( label => "Back to whence you came" ) %>
Because this "return" does not carry a result value, you can think of it as a form of "gosub". In
comparison, ordinary hyperlinks are akin to "goto" statements.
Sometimes, it may be possible for the user to get to a location without having a continuation set. In
that case, clicking on the "Back to whence you came" link will appear to do nothing -- which may be
slightly confusing to the user. To remedy this, Jifty provides a way to specify a default location to
return to:
<% Jifty->web->return( to => "/default", label => "Go back" ) %>
Using return values
All of the above examples generate links, which means that they don't interact at all with actions.
However, continuations can also be useful in creating complex multi-page actions.
Continuations are saved -- and the browser is redirected to the new URL -- just after all actions have
been checked for validation but before any of them are run. This means that the new request has access
to the full validation state of its parent's actions.
When a continuation is called, it first checks that all actions in the request were successful; if any
failed, then the continuation is not called. If the request's actions were all successful, it merges
together the Jifty::Results of current Jifty::Response with those in the Jifty::Response stored in the
continuation. In doing so, parameters are mapped using Jifty::Request::Mapper. This makes it possible
to return values from continuations into arbitrary places. For example:
% my $action = Jifty->web->new_action(class => 'AddTwoNumbers');
<% Jifty->web->form->start %>
<% $action->form_field( 'first_number' ) %>
<% $action->form_field( 'second_number',
default_value => {
request_argument => "number",
}
) %>
<% Jifty->web->tangent(
url => '/pagetwo',
label => 'Enter a second number',
submit => $action
) %>
<% Jifty->web->form->end %>
..and in "/pagetwo":
<% Jifty->web->form->start %>
<input type="text" name="number" />
%# We use as_button to tell Jifty that we want a button, not a link
<% Jifty->web->return( label => 'Pick', as_button => 1 ) %>
<% Jifty->web->form->end %>
..and assuming that "AddTwoNumbers"'s "take_action" resembles:
sub take_action {
my $self = shift;
my $one = $self->argument_value("first_number");
my $two = $self->argument_value("second_number");
$self->result->message("Got " . ($one + $two));
}
The first page renders the entry box for the first number; the second input is hidden because Jifty
notices that it is based on a mapped value: i.e., its default is set to "{request_argument => "number"}"
instead of a plain scalar value.
Pressing the button validates the action but does not complete running it. At this point, the
"second_number" argument to the "AddTwoNumbers" action has no real value -- however, it knows that it
will, at the earliest possible opportunity, fill in its value from the "number" request parameter.
Jifty tangents to "/pagetwo", where we enter and submit a "number" argument. Control then returns to the
original page, where the request mapper maps the "number" value into the "second_number" argument of the
"AddTwoNumbers" action, which then runs because it has received all arguments it requires.
Note that in the example above, the "number" argument is a plain request argument, not part of another
action. More complex mappings are possible, including grabbing the results of or arguments to actions.
This would make it possible, for instance, to use an action on the second page to validate the number
before returning. This is slightly different from placing a validator on the "AddTwoNumbers" action, as
that validator only gets called after control has already returned to the first page.
As dispatcher rules
The "tangent" in Jifty::Web function is context-aware -- if it is called in void context, it immediately
saves the continuation and redirects to the new url. This is particularly useful, say, for
authentication protection in "before" blocks:
before '/protected' => sub {
# shorthand for: Jifty->web->tangent( url => '/login' )
tangent('/login') unless Jifty->web->current_user->id;
};
And in the "/login" template:
% my $action = Jifty->web->new_action(class => 'Login',
% moniker => 'loginbox' );
<% Jifty->web->form->start %>
<% $action->form_field('username') %>
<% $action->form_field('password') %>
<% Jifty->web->return( to => "/protected",
label => 'Login',
submit => $action) %>
<% Jifty->web->form->end %>
This establishes a button, which, if the "Login" action is successful, calls the stored continuation, or,
lacking one, redirects to "/protected".
As currently implemented, these redirect-from-dispatcher tangents works exactly like rendered-as-links
tangents, in that when they return, all rules in the dispatcher are still executed from the start.
Therefore the "unless" guard in the "before '/protected'" rule above is necessary to prevent recursion.
GORY DETAILS
Jifty's continuations are implemented in Jifty::Continuation, which is very little more than a place to
store a Jifty::Request and its associated Jifty::Response.
The following diagram diagrams the stages of continuation handling, and their interaction with the
dispatcher. For clarity, the page region handling code is included, but page regions do not currently
interact with continuation processing.
/--------------\
+---------------------v-+ |
|........Request........| |
+-|-------------------|-+ |
| | RETURN +---|---------------------+
/----\ | \----------> Replace request with |
| +-|--|-+ +==============+ | request in continuation |
| |.v..v.---> SETUP rules | +-------------------------+
| |......| +==============+
| |..D...|
| |..I...| +~~~~~~~~~~~~~~~~~~~+ +-------------------------+
| |..S...---> Validate actions | | Store current request |
| |..P...| +~~~~~|~~~~~~~~~|~~~+ SAVE | and response, redirect |
| |..A...| | \----------> to new scope and URL |
| |..T...| | +-------------------------+
| |..C...| +~~~~~v~~~~~~~~~~~~~+
| |..E...| | Run actions | +-------------------------+
| |..R...| +~~~~~~~~~~~~~~~|~~~+ CALL | Merge results into the |
| |......| \----------> continuation's results; |
| |......| | redirect to return URL |
| |......| +==============+ +-------------------------+
| |......---> RUN rules |
| |......| +=====|========+
| |......| |
| |......| +--v---------------+
| |......| | Show templates |
| |......| +-------|----------+
| |......| |
| |......| +-------v----------+
| |......| | Show page region ---------------------\
| |......| +------------------+ |
| |......| |
| |......| +==============+ |
| |......---> AFTER rules | |
| +------+ +==============+ |
| |
\------------------------------------------------------/
As shown in the diagram above, there are three different operations that continuations use. The first is
"SAVE", which is triggered by the query parameter <J:CREATE>. Continuations are saved after validating
actions; the continuation itself is attached to the user's session object.
The current saved continuation is automatically preserved across requests. When the time comes to call
the continuation, the "CALL" operation is performed; this is usually triggered by the presence of the
<J:CALL> query parameter. This causes the stored request to be query-mapped using
Jifty::Request::Mapper, but using the current request and response (not the continuation!) as the sources
for mapping values. Then, the result objects are merged, with results from the stored response taking
precedence. This new mapped request and new merged response are formed into a new continuation.
In order to ensure that the browser's URL matches the URL of the request in the continuation, Jifty then
does a redirect to the URL of the request stored in the continuation, starting the last continuation
operation, the "RETURN". When Jifty detects the "RETURN" operation, most often by the presence of
"J:RETURN", it loads the continuation and reads the stored request and response into the current request
and response.