Document Plack::Component and derived classes lifecycle. Fixes plackg…

…h-165

lib/Plack/Component.pm

@@ -81,9 +81,9 @@ Plack::App::* you should inherit from this directly.
 
 =item call ($env)
 
-You are expected to implement a C<call> method in your component. This is
-where all the work gets done. It receives the PSGI C<$env> hash-ref as an
-argument and is expected to return a proper PSGI response value.
+You are expected to implement a C<call> method in your component. This
+is where all the work gets done. It receives the PSGI C<$env> hash-ref
+as an argument and is expected to return a proper PSGI response value.
 
 =back
 
@@ -111,6 +111,21 @@ instead.
 
 =back
 
+=head1 OBJECT LIFECYCLE
+
+Objects for the derived classes (Plack::App::* or
+Plack::Middleware::*) are created at the PSGI application compile
+phase using C<new>, C<prepare_app> and C<to_app>, and the created
+object persists during the web server lifecycle, unless it is running
+on the non-persisten environment like CGI. C<call> is invoked against
+the same object whenever a new request comes in.
+
+You can check if it is running in a persisten environment by checking
+C<psgi.run_once> key in the C<$env> being true (non-persistent) or
+false (persistent), but it is best for you to write your middleware
+safe in the persistent environment. To accomplish that, you should
+avoid saving per-request data like C<$env> in your object.
+
 =head1 BACKWARDS COMPATIBILITY
 
 The L<Plack::Middleware> module used to inherit from L<Class::Accessor::Fast>,

lib/Plack/Middleware.pm

@@ -60,12 +60,18 @@ Plack::Middleware - Base class for easy-to-use PSGI middleware
 
 =head1 DESCRIPTION
 
-Plack::Middleware is an utility base class to write PSGI
+Plack::Middleware is a utility base class to write PSGI
 middleware. All you have to do is to inherit from Plack::Middleware
 and then implement the callback C<call> method (or C<to_app> method
 that would return the PSGI code reference) to do the actual work. You
 can use C<< $self->app >> to call the original (wrapped) application.
 
+Your middleware object is created at a PSGI application compile time
+and is persistent during the web server life cycle (unless it is a
+non-persisten environment such as CGI), so you should never set or
+cache per-request data like C<$env> in your middleware object. See
+also L<Plack::Component/"OBJECT LIFECYCLE">.
+
 See L<Plack::Builder> how to actually enable middlewares in your
 I<.psgi> application file using the DSL. If you do not like our
 builder DSL, you can also use C<wrap> method to wrap your application
@@ -79,6 +85,6 @@ with a middleware:
 
 =head1 SEE ALSO
 
-L<Plack> L<Plack::Builder>
+L<Plack> L<Plack::Builder> L<Plack::Component>
 
 =cut