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.