Browse files

PSGI::Extensions: add a modified PSGI environment cleanup handlers pr…


This is an import of the proposal at
with the following changes:

 * Fixed various typos & grammar error

 * We now say that psgix.cleanup.handlers MUST be ArrayRef

   I don't see any reason for why a server would support cleanup mode but
   wouldn't be capable of initializing psgix.cleanup.handlers to []. Just
   make this a MUST since having the server initialize it is easier, and
   if it can't create an empty ArrayRef in $env at the start of the
   request it probably can't support Plack (or Perl) at all.

 * Add background on what the cleanup handlers are for

   I think it helps to add a bit of background here to be explicit about
   what this feature is for, and in particular make sure that servers
   aren't going to implement this in some blocking fashion while the
   client is still waiting on them.

In addition the pull request originally contained two new boolean
flags, see "PSGI::Extensions: add two new boolean flags to the cleanup
spec", but after discussing it with miyagawa we decided to drop that
  • Loading branch information...
avar committed Sep 30, 2012
1 parent a572c7e commit ee99fc900f90ef6bbf80f6fa83be6c863c23eb07
Showing with 41 additions and 0 deletions.
  1. +41 −0 PSGI/Extensions.pod
@@ -59,6 +59,47 @@ C<psgix.harakiri.commit>: A boolean which is set to true by the PSGI
application or middleware when it wants the server to kill the worker
after the current request.
+=item *
+Cleanup handlers
+Some servers such as Apache support an execution phase that happens
+after all content has been sent to the client and the connection has
+been closed. These should only be set if the server supports such a
+mode of execution that the client doesn't have to wait on, e.g. you
+could C<sleep 10> in a cleanup handler but return a response to the
+client in 10ms.
+This can be used e.g. to close database connections, set keys in a
+cache whose values were generated during the request, send a logging
+event describing the request etc. It can even be used as a poor man's
+job queue (for e.g. resizing and converting uploaded images).
+For most servers the implementation is straightforward, calling the
+callbacks once a request is complete but before C<$env> is
+A CGI handler could run the callbacks after closing C<STDOUT>,
+mod_perl handlers can use C<PerlCleanupHandlers> mechanism.
+C<psgix.cleanup> - A boolean flag indicating whether a PSGI server
+supports cleanup handlers. Absence of the key assumes false
+(i.e. unsupported). Middleware and applications MUST check this key
+before utilizing the cleanup handlers.
+C<psgix.cleanup.handlers> - Array reference to stack callback
+handlers. This reference MUST be initialized as an empty array
+reference by the servers. Applications can register the callbacks by
+simply push()ing a code reference to this array reference. Callbacks
+will be called once a request is complete, and will receive C<$env>
+as its first argument, and return value of the callbacks will be
+simply ignored. An exception thrown inside callbacks MAY also be
+If the server also supports C<psgix.harakiri>, it SHOULD implement in
+a way that cleanup handlers run before harakiri checker, so that the
+cleanup handlers can commit the harakiri flag.

0 comments on commit ee99fc9

Please sign in to comment.