Skip to content
This repository
Browse code

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

Add psgix cleanup proposal
  • Loading branch information...
commit abf067af9ec7a936098a88f7fbe7dfc21c85072c 2 parents a572c7e + ee99fc9
Tatsuhiko Miyagawa authored October 10, 2012

Showing 1 changed file with 41 additions and 0 deletions. Show diff stats Hide diff stats

  1. 41  PSGI/Extensions.pod
41  PSGI/Extensions.pod
Source Rendered
@@ -59,6 +59,47 @@ C<psgix.harakiri.commit>: A boolean which is set to true by the PSGI
59 59
 application or middleware when it wants the server to kill the worker
60 60
 after the current request.
61 61
 
  62
+=item *
  63
+
  64
+Cleanup handlers
  65
+
  66
+Some servers such as Apache support an execution phase that happens
  67
+after all content has been sent to the client and the connection has
  68
+been closed. These should only be set if the server supports such a
  69
+mode of execution that the client doesn't have to wait on, e.g. you
  70
+could C<sleep 10> in a cleanup handler but return a response to the
  71
+client in 10ms.
  72
+
  73
+This can be used e.g. to close database connections, set keys in a
  74
+cache whose values were generated during the request, send a logging
  75
+event describing the request etc. It can even be used as a poor man's
  76
+job queue (for e.g. resizing and converting uploaded images).
  77
+
  78
+For most servers the implementation is straightforward, calling the
  79
+callbacks once a request is complete but before C<$env> is
  80
+destroyed.
  81
+
  82
+A CGI handler could run the callbacks after closing C<STDOUT>,
  83
+mod_perl handlers can use C<PerlCleanupHandlers> mechanism.
  84
+
  85
+C<psgix.cleanup> - A boolean flag indicating whether a PSGI server
  86
+supports cleanup handlers. Absence of the key assumes false
  87
+(i.e. unsupported). Middleware and applications MUST check this key
  88
+before utilizing the cleanup handlers.
  89
+
  90
+C<psgix.cleanup.handlers> - Array reference to stack callback
  91
+handlers. This reference MUST be initialized as an empty array
  92
+reference by the servers. Applications can register the callbacks by
  93
+simply push()ing a code reference to this array reference. Callbacks
  94
+will be called once a request is complete, and will receive C<$env>
  95
+as its first argument, and return value of the callbacks will be
  96
+simply ignored. An exception thrown inside callbacks MAY also be
  97
+ignored.
  98
+
  99
+If the server also supports C<psgix.harakiri>, it SHOULD implement in
  100
+a way that cleanup handlers run before harakiri checker, so that the
  101
+cleanup handlers can commit the harakiri flag.
  102
+
62 103
 =back
63 104
 
64 105
 =head1 COPYRIGHT AND LICENSE

0 notes on commit abf067a

Please sign in to comment.
Something went wrong with that request. Please try again.