Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

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

Add psgix cleanup proposal
  • Loading branch information...
commit abf067af9ec7a936098a88f7fbe7dfc21c85072c 2 parents a572c7e + ee99fc9
@miyagawa miyagawa authored
Showing with 41 additions and 0 deletions.
  1. +41 −0 PSGI/Extensions.pod
View
41 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
+destroyed.
+
+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
+ignored.
+
+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.
+
=back
=head1 COPYRIGHT AND LICENSE
Please sign in to comment.
Something went wrong with that request. Please try again.