Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Loading…

Add psgix cleanup proposal #26

Merged
merged 1 commit into from

2 participants

@avar

I think this pull request is ready as-is, but I'm mostly submitting it so that there's a place to discuss this on GitHub without discussions being nuked away by non-fast-forward commits.

@miyagawa
Owner

Just for the sake of logs, I do not like the complexity of so many flags introduced by this.

@avar

You mean for the sake of the changelogs?

I don't like the complexity of these flags either, but I like the complexity of not having them even less.

Maybe I'm being overly paranoid but by having flags indicating what sort of cleanup implementation the server provides you can easily ensure on the application level that your code is going to behave the way you expect it to.

Without a flag you either can't, or you end up having to manage that information outside of PSGI somehow, or more likely your code will just silently start acting slightly differently.

@miyagawa
Owner
@avar

Fair enough, does it look good otherwise? I'll update the pull request to drop that patch.

@avar

Updated the request to omit the patch adding the two new boolean flags.

@avar avar PSGI::Extensions: add a modified PSGI environment cleanup handlers pr…
…oposal

This is an import of the proposal at
https://github.com/Plack/psgi-specs/wiki/Proposal%3A-PSGI-environment-cleanup-handlers
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
part.
ee99fc9
@miyagawa miyagawa merged commit abf067a into from
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Commits on Oct 10, 2012
  1. @avar

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

    avar authored
    …oposal
    
    This is an import of the proposal at
    https://github.com/Plack/psgi-specs/wiki/Proposal%3A-PSGI-environment-cleanup-handlers
    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
    part.
This page is out of date. Refresh to see the latest.
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
Something went wrong with that request. Please try again.