X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=catagits%2FCatalyst-Runtime.git;a=blobdiff_plain;f=lib%2FCatalyst%2FComponent%2FContextClosure.pm;h=8c163e0754bce7da896d78686686a29f79c4b29e;hp=0aaf8bf3a7ae278b82ed9f4c22ca6092fa7c64c7;hb=eefc03e12890c06c9a76d78b4d68e3b2ad781328;hpb=5ad8be8c2865ed519105c506c721114e8e48fc75

diff --git a/lib/Catalyst/Component/ContextClosure.pm b/lib/Catalyst/Component/ContextClosure.pm
index 0aaf8bf..8c163e0 100644
--- a/lib/Catalyst/Component/ContextClosure.pm
+++ b/lib/Catalyst/Component/ContextClosure.pm
@@ -2,13 +2,78 @@ package Catalyst::Component::ContextClosure;
 
 use Moose::Role;
 use Scalar::Util 'weaken';
-use namespace::autoclean;
+use namespace::clean -except => [ 'meta' ];
 
 sub make_context_closure {
     my ($self, $closure, $ctx) = @_;
-    my $weak_ctx = $ctx;
     weaken $ctx;
     return sub { $closure->($ctx, @_) };
 }
 
 1;
+
+__END__
+
+=head1 NAME
+
+Catalyst::Component::ContextClosure - Moose Role for components which need to close over the $ctx, without leaking
+
+=head1 SYNOPSIS
+
+    package MyApp::Controller::Foo;
+    use Moose;
+    use namespace::clean -except => 'meta';
+    BEGIN {
+        extends 'Catalyst::Controller';
+        with 'Catalyst::Component::ContextClosure';
+    }
+
+    sub some_action : Local {
+        my ($self, $ctx) = @_;
+        $ctx->stash(a_closure => $self->make_context_closure(sub {
+            my ($ctx) = @_;
+            $ctx->response->body('body set from closure');
+        }, $ctx));
+    }
+
+=head1 DESCRIPTION
+
+A common problem with stashing a closure, that closes over the Catalyst context
+(often called C<$ctx> or C<$c>), is the circular reference it creates, as the
+closure holds onto a reference to context, and the context holds a reference to
+the closure in its stash. This creates a memory leak, unless you always
+carefully weaken the closures context reference.
+
+This role provides a convenience method to create closures, that closes over
+C<$ctx>.
+
+=head1 METHODS
+
+=head2 make_context_closure ($closure, $ctx)
+
+Returns a code reference, that will invoke C<$closure> with a weakened
+reference to C<$ctx>. All other parameters to the returned code reference will
+be passed along to C<$closure>.
+
+=head1 SEE ALSO
+
+L<Catalyst::Component>
+
+L<Catalyst::Controller>
+
+L<CatalystX::LeakChecker>
+
+=begin stopwords
+
+=head1 AUTHOR
+
+Florian Ragwitz <rafl@debian.org>
+
+=end stopwords
+
+=head1 COPYRIGHT
+
+This library is free software. You can redistribute it and/or modify it under
+the same terms as Perl itself.
+
+=cut