- Fixed the unit tests for apache.register_cleanup server.register_cl…

…eanup. There is not way it could have passed before, yet it did ???

- Corrected the documentation about those two functions, it was badly broken.
- Added a warning so that users don't try to pass a request object as the argument to the callable.

Doc/modpython4.tex

@@ -401,10 +401,14 @@ \subsection{Functions\label{pyapi-apmeth}}
     parameter by calling \code{apache.exists_config_define('FOOBAR')}.
 \end{funcdesc}
 
-\begin{methoddesc}[server]{register_cleanup}{handler\optional{, data}}
-  Registers a cleanup. Equivalent to \function{req.register_cleanup()}
-  or \function{req.server.register_cleanup()}, except that a server or request
-  object is not required.
+\begin{funcdesc}{register_cleanup}{interpreter, server, callable\optional{, data}}
+  Registers a cleanup that will be performed at child shutdown time. Equivalent to 
+  \function{Server.register_cleanup()}, except that a request object is not required.
+  Instead, an interpreter name must be given.
+  \emph{Warning:} do not pass directly or indirectly a request object in the data parameter.
+  Since the callable will be called at server shutdown time, the request object
+  won't exist anymore and any manipulation of it in the handler will give
+  undefined behaviour.
 \end{methoddesc}
 
 \begin{funcdesc}{config_tree}{}
@@ -1323,7 +1327,14 @@ \subsubsection{Server Methods\label{pyapi-mpsrv-meth}}
 \begin{methoddesc}[server]{register_cleanup}{request, callable\optional{, data}}
   Registers a cleanup. Very similar to \function{req.register_cleanup()}, except
   this cleanup will be executed at child termination time. This function
-  requires one extra argument - the request object.
+  requires uses the request object to infer the interpreter name.
+  If you don't have any request object at hand, then you must use the
+  \function{apache.register_cleanup} variant, but you'll have to provide an
+  interpreter name.
+  \emph{Warning:} do not pass directly or indirectly a request object in the
+  data parameter. Since the callable will be called at server shutdown time,
+  the request object won't exist anymore and any manipulation of it in the
+  callable will give undefined behaviour.
 \end{methoddesc}
 
 \subsubsection{Server Members\label{pyapi-mpsrv-mem}}

test/htdocs/tests.py

@@ -707,6 +707,11 @@ def cleanup(data):
 
     data.log_error(data.cleanup_data)
 
+def server_cleanup(data):
+    # for srv_register_cleanup and apache_register_cleanup below
+
+    apache.log_error(data)
+
 def req_headers_out(req):
 
     req.headers_out["X-Test-Header"] = "test ok"
@@ -773,16 +778,14 @@ def fileupload(req):
 
 def srv_register_cleanup(req):
 
-    req.cleanup_data = "test ok"
-    req.server.register_cleanup(req, cleanup, req)
+    req.server.register_cleanup(req, server_cleanup, "test ok")
     req.write("registered server cleanup that will write to log")
 
     return apache.OK
 
 def apache_register_cleanup(req):
 
-    req.cleanup_data = "test 2 ok"
-    apache.register_cleanup(cleanup, req)
+    apache.register_cleanup(req.interpreter, req.server, server_cleanup, "test 2 ok")
     req.write("registered server cleanup that will write to log")
 
     return apache.OK