NAME
    Catalyst::Plugin::Continuation - Catalyst Continuation Plugin

SYNOPSIS
        # Make sure to load session plugins too!
        package MyApp;
        use Catalyst qw/Session Session::Store::File
          Session::State::Cookie Continuation/;

        # Create a controller
        package MyApp::Controller::Test;
        use base 'Catalyst::Controller';

        # Add a action with attached action class
        sub counter : Global {
            my ( $self, $c ) = @_;
            my $up      = $c->continue('up');
            my $down    = $c->continue('down');
            my $counter = $c->stash->{counter} || 0;
            $c->res->body(<<"EOF");
        Counter: $counter<br/>
        <a href="$up">++</a>
        <a href="$down">--</a>
        EOF
        }

        # Add private actions for continuations
        sub up   : Private { $_[1]->stash->{counter}++ }
        sub down : Private { $_[1]->stash->{counter}-- }

DESCRIPTION
    Catalyst Continuation Plugin.

OVERLOADED METHODS
  prepare_action
  dispatch
    These methods are overridden to allow the special continuation dispatch.

METHODS
  continuation
    Contains the continuation object that was restored.

  set_continuation $id, $structure
  get_continuation $id
  delete_continuation $id
  active_continuations
  clear_continuations
  generate_continuation_id
    These are internal methods which you can override.

    They default to storing inside "$c->session", and using
    "generate_session_id" in Catalyst::Plugin::Session.

    If you want your continuations to be garbage collected in some way you
    need to override this to store the data in some other backend.

    Note that "active_continuations" returns a hash reference which you can
    edit. Be careful.

  $c->continuation_expired( $id )
    This handler is called when the continuation with the ID $id tried to
    get invoked but did not exist

  $c->resume_continuation( $cont_or_id );
    Resume a continuation based on an ID or an object.

    This is a convenience method intended on saving you the need to load and
    execute the continuation yourself.

  $c->continue($method)
  $c->cont($method)
    Returns the Catalyst::Continuation object for given method.

    Takes the same arguments as "forward" in Catalyst and it's relatives.

  $c->caller_continuation
    A pseudo-cc - a continuation to your caller.

    Note that this does NOT honor the call stack in any way - it is ONLY to
    reinvoke the immediate caller. See the NeedsLogin test controller in the
    test suite for an example of how to use this effectively.

  $c->cont_class
    Returns the string "Catalyst::Continuation" by default. You may override
    this to replace the continuation class.

CAVEATS
    Continuations take up space, and are by default stored in the session.

    When invoked a session will delete itself by default, but anything else
    will leak, until the session expires.

    If this is a concern for you, override the "get_continuation" family of
    functions to have a better scheme for storage.

    Some approaches you could implement, depending on how you use
    continuations:

    size limiting
        Store up to $x continuations, and toss out old ones once this starts
        to overflow. This is essentially an LRU policy.

    continuation grouping
        Group all the continuations saved in a single request together. When
        one of them is deleted, all the rest go with it.

    use the fine grained session expiry feature
        Catalyst::Plugin::Session allows you to expire some session keys
        before the entire session expired. You can associate each session
        with it's own unique key, and avoid extending the continuation's
        time-to-live.

    If you override all these functions then you don't need the
    Catalyst::Plugin::Session dependency.

SEE ALSO
    Catalyst, Seaside (http://www.seaside.st/), Jifty, Coro::Cont,
    psychiatrist(1).

AUTHOR
    Sebastian Riedel, "sri@oook.de" Yuval Kogman, "nothingmuch@woobling.org"

LICENSE
    This library is free software, you can redistribute it and/or modify it
    under the same terms as Perl itself.