NAME

       Jifty::Continuation - Allows for basic continuation-based programming

DESCRIPTION

       In programming, a continuation is a construct that allows you to freeze the current state of a program
       and then recover that state later by calling the continuation. For example, you could save a continuation
       when throwing an exception to save the state, an exception handler could resolve the problem that caused
       the exception, and then call the continuation to resume execution at the point where the exception was
       thrown now that the problem has been solved.

       In Jifty, continuations are used to save the state of a request (and sometimes the response).
       Continuations can be used in situations such as these:

       1.  A  user visits a page that requires login to view. The dispatcher saves a continuation and then sends
           the user off to the login page. Once the user logs in successfully, the login  action  can  call  the
           continuation to return the user back to the original page.

       2.  A  blogging  application  might  have  a  "Edit" link on each post to allow the editor to jump to the
           change page. If this link includes a saved continuation, then the "Save" button  could  trigger  that
           continuation  to  be  called  to return the user back to the original page where they clicked "Edit".
           This way, it could return the user to the view page, or  a  list  page,  or  an  administrative  view
           depending on which page the user started the edit process from.

       3.  If  you  have  a  wizard for editing some information in your application, but entering some data may
           require jumping to another page you can save a  continuation  to  allow  the  user  to  return  after
           editing.  If  that  page also requires a jump to yet another page, you can save another continuation.
           Since continuations save a stack of previous continuations, you can return twice to get back  to  the
           wizard.

       "Jifty::Continuation"  handles  the  details  of  saving  this  information  for  later  recovery. When a
       continuation is saved, the current request and response are saved to the database in the  current  user's
       session.  When a continuation is called, the current request and response become those that were saved in
       the continuation. A continuation can be called at any point in the same session.

       Continuations store a Jifty::Request object and the Jifty::Response object for  the  request.   They  can
       also store arbitrary code to be run when the continuation is called.

       Continuations  can also be arbitrarily nested.  This means that returning from one continuation will drop
       you into the continuation that is one higher in the stack.

       Continuations are generally created just before  their  request  would  take  effect,  activated  by  the
       presence of certain query parameters.  The rest of the request is saved, its execution is to be continued
       at a later time.

       Continuations  are  run  after any actions have run.  When a continuation is run, it restores the request
       that it has saved away into it, and pulls into that request  the  values  any  return  values  that  were
       specified  when  it  was  created.   The  continuations  code block, if any, is then called, and then the
       filled-in request is then passed to the Jifty::Dispatcher.

   new PARAMHASH
       Saves a continuation at the current state.  Possible arguments in the "PARAMHASH":

       parent
           A Jifty::Continuation object, or the "id"  of  one.   This  represents  the  continuation  that  this
           continuation should return to when it is called.  Defaults to the current continuation of the current
           Jifty::Request.

       request
           The Jifty::Request object to save away.  Defaults to an empty Jifty::Request object.

       response
           The  Jifty::Response  object  that will be loaded up when the continuation is run.  Most of the time,
           the response isn't stored in the continuation, since the  continuation  was  saved  away  before  the
           actions  got  run.   In  the  case  when  continuations are used to preserve state across a redirect,
           however, we tuck the Jifty::Response value of the previous request into  the  continuation  as  well.
           Defaults to an empty Jifty::Response object.

       code
           An optional subroutine reference to evaluate when the continuation is called.

   return_path_matches
       Returns true if the continuation matches the current request's path, and it would return to its caller in
       this context.  This can be used to ask "are we about to call a continuation?"

   call
       Call  the  continuation;  this  is generally done during request processing, after actions have been run.
       Jifty::Request::Mapper-controlled values are filled into the stored request based on the current  request
       and  response.   During  the  process, another continuation is created, with the filled-in results of the
       current actions included, and the browser is redirected to the proper path, with that continuation.

   return
       Returns from the continuation by pulling out the stored request,  and  setting  that  to  be  the  active
       request.   This  shouldn't need to be called by hand -- use "return_from_continuation" in Jifty::Request,
       which ensures that all requirements are met before it calls this.

   delete
       Remove the continuation, and any continuations that would return to its scope, from the session.

SEE ALSO

       Jifty::Manual::Continuations

LICENSE

       Jifty is Copyright 2005-2010 Best Practical Solutions, LLC.  Jifty is distributed under the same terms as
       Perl itself.

perl v5.14.2                                       2010-12-10                           Jifty::Continuation(3pm)