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.

cpanm Catalyst::Plugin::Continuation

perl -MCPAN -e shell
install Catalyst::Plugin::Continuation