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.