Browse files

Merge pull request #26 from avar/add-psgix-cleanup-proposal

Add psgix cleanup proposal
  • Loading branch information...
miyagawa committed Oct 10, 2012
2 parents a572c7e + ee99fc9 commit abf067af9ec7a936098a88f7fbe7dfc21c85072c
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 abf067a

Please sign in to comment.