From bknr@bknr.net Wed Feb 18 20:30:47 2009
From: BKNR Commits <bknr@bknr.net>
To: bknr-cvs@common-lisp.net
Subject: [bknr-cvs] edi changed trunk/thirdparty/hunchentoot/
Date: Wed, 18 Feb 2009 21:28:27 +0100
Message-ID: <E1LZt1v-000Fc4-Sc@paracetamol.bknr.net>
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="===============2027815849467171187=="

--===============2027815849467171187==
Content-Type: text/plain; charset="utf-8"
Content-Transfer-Encoding: quoted-printable

Revision: 4281
Author: edi
URL: http://bknr.net/trac/changeset/4281

Document logging

U   trunk/thirdparty/hunchentoot/acceptor.lisp
U   trunk/thirdparty/hunchentoot/doc/index.xml
U   trunk/thirdparty/hunchentoot/log.lisp
U   trunk/thirdparty/hunchentoot/request.lisp
U   trunk/thirdparty/hunchentoot/specials.lisp

Modified: trunk/thirdparty/hunchentoot/acceptor.lisp
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
--- trunk/thirdparty/hunchentoot/acceptor.lisp	2009-02-18 19:58:57 UTC (rev 4=
280)
+++ trunk/thirdparty/hunchentoot/acceptor.lisp	2009-02-18 20:28:27 UTC (rev 4=
281)
@@ -139,9 +139,9 @@
                    :accessor acceptor-message-logger
                    :documentation "Designator for a function to call
 to log messages by the acceptor.  It must accept a severity level for
-the message, which will be one of :NOTICE, :INFO, or :WARNING, a
-format string and an arbitary number of formatting arguments.  This
-slot defaults to a function which writes to the file determined by
+the message, which will be one of :ERROR, :INFO, or :WARNING, a format
+string and an arbitary number of formatting arguments.  This slot
+defaults to a function which writes to the file determined by
 *MESSAGE-LOG-PATHNAME* \(unless that value is NIL).
=20
 If the value of this slot is NIL, message logging is turned off for

Modified: trunk/thirdparty/hunchentoot/doc/index.xml
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
--- trunk/thirdparty/hunchentoot/doc/index.xml	2009-02-18 19:58:57 UTC (rev 4=
280)
+++ trunk/thirdparty/hunchentoot/doc/index.xml	2009-02-18 20:28:27 UTC (rev 4=
281)
@@ -384,6 +384,11 @@
     </clix:description>
   </clix:function>
=20
+  <clix:special-variable name=3D'*acceptor*'>
+    <clix:description>The current ACCEPTOR object in the context of a reques=
t.
+    </clix:description>
+  </clix:special-variable>
+
   <clix:readers generic=3D'true'>
     <clix:listed-reader name=3D'acceptor-address'>
     <clix:lambda-list>acceptor
@@ -450,10 +455,10 @@
     </clix:returns>
     </clix:listed-accessor>
=20
-    <clix:listed-accessor name=3D'acceptor-handler-selector'>
+    <clix:listed-accessor name=3D'acceptor-request-dispatcher'>
     <clix:lambda-list>acceptor
     </clix:lambda-list>
-    <clix:returns>handler-selector
+    <clix:returns>request-dispatcher
     </clix:returns>
     </clix:listed-accessor>
=20
@@ -600,11 +605,10 @@
 <clix:ref>ACCEPTOR</clix:ref> object and a LispWorks socket handle or a usoc=
ket socket
 stream object in <clix:arg>socket</clix:arg>.  It reads the request headers,=
 sets up the
 <a href=3D"#requests">request</a> and <a href=3D"#replies">reply</a>
-objects, and hands over to (the unexported
-function) <code>PROCESS-REQUEST</code> which selects and calls a
-handler for the request and sends its reply to the client.  This is
-done in a loop until the stream has to be closed or until a connection
-timeout occurs.
+objects, and hands over to <clix:ref>PROCESS-REQUEST</clix:ref> which
+selects and calls a handler for the request and sends its reply to the
+client.  This is done in a loop until the stream has to be closed or
+until a connection timeout occurs.
=20
 <p>
 It is probably not a good idea to re-implement this method until you
@@ -1102,6 +1106,90 @@
     </clix:subchapter>
=20
     <clix:subchapter name=3D"logging" title=3D"Logging">
+
+By default, Hunchentoot logs accesses and errors to two separate files
+in the file system, but <em>only</em> if the special variables
+<clix:ref>*MESSAGE-LOG-PATHNAME*</clix:ref> and <clix:ref>*ACCESS-LOG-PATHNA=
ME*</clix:ref> are set accordingly.
+Access logging is done in a format similar to what
+the Apache web server can write so that logfile analysis using
+standard tools is possible.  Errors during request processing are
+logged to a separate file.
+<p>
+The standard logging mechanism is deliberately simple and slow.  The
+log files are opened for each log entry and closed again after
+writing, and access to them is protected by a global lock.  If you
+want more sophisticated logging, use
+the <a href=3D"#acceptor-access-logger"><code>:access-logger</code></a>
+and <a href=3D"#acceptor-message-logger"><code>:message-logger</code></a>
+initargs of the acceptor class to establish your own logging
+functions.  See the docstrings of the corresponding slots for more
+information.
+</p>
+<p>
+Errors happening within a <a href=3D"#handlers">handler</a> which are
+not caught by the handler itself are handled by Hunchentoot by logging
+them to the log file.
+</p>
+
+  <clix:function name=3D'log-message'>
+  <clix:lambda-list>log-level format-string=20
+  <clix:lkw>rest
+  </clix:lkw> format-arguments
+  </clix:lambda-list>
+  <clix:returns>result
+  </clix:returns>
+    <clix:description>Convenience function which calls the message
+logger of the current acceptor (if there is one) with the same
+arguments it accepts.  Returns <code>NIL</code> if there is no message
+logger or whatever the message logger returns.
+<p>
+This is the function which Hunchentoot itself uses to log errors it
+catches during request processing.
+</p>
+    </clix:description>
+  </clix:function>
+
+  <clix:special-variable name=3D'*message-log-pathname*'>
+    <clix:description>
+A designator for the pathname of the message log file used by the
+<a href=3D"#logging">default message logger</a>.  The initial value is <code=
>NIL</code> which
+means that <em>nothing</em> will be logged!
+    </clix:description>
+  </clix:special-variable>
+
+  <clix:special-variable name=3D'*access-log-pathname*'>
+    <clix:description>
+A designator for the pathname of the access log file used by the
+<a href=3D"#logging">default access logger</a>.  The initial value is <code>=
NIL</code> which
+means that <em>nothing</em> will be logged!
+    </clix:description>
+  </clix:special-variable>
+
+  <clix:special-variable name=3D'*log-lisp-errors-p*'>
+    <clix:description>Whether Lisp errors in request handlers should be logg=
ed.
+    </clix:description>
+  </clix:special-variable>
+
+  <clix:special-variable name=3D'*log-lisp-warnings-p*'>
+    <clix:description>Whether Lisp warnings in request handlers should be lo=
gged.
+    </clix:description>
+  </clix:special-variable>
+
+  <clix:special-variable name=3D'*lisp-errors-log-level*'>
+    <clix:description>Log level for Lisp errors.  Should be one
+of <code>:ERROR</code> (the default), <code>:WARNING</code>,
+or <code>:INFO</code>.
+    </clix:description>
+  </clix:special-variable>
+
+  <clix:special-variable name=3D'*lisp-warnings-log-level*'>
+    <clix:description>Log level for Lisp warnings.
+Should be one of <code>:ERROR</code>, <code>:WARNING</code>
+(the default), or <code>:INFO</code>.
+    </clix:description>
+  </clix:special-variable>
+
+
     </clix:subchapter>
=20
     <clix:subchapter name=3D"conditions" title=3D"Conditions">
@@ -1113,16 +1201,7 @@
   </clix:chapter>
=20
     <clix:chapter name=3D'dict' title=3D'The HUNCHENTOOT dictionary'>
-  <clix:special-variable name=3D'*acceptor*'>
-    <clix:description>The current ACCEPTOR object.
-    </clix:description>
-  </clix:special-variable>
-  <clix:special-variable name=3D'*access-log-pathname*'>
-    <clix:description>A designator for the pathname of the access log file u=
sed by the
-LOG-ACCESS-TO-FILE function.  The initial value is NIL which means
-that nothingq will be logged.
-    </clix:description>
-  </clix:special-variable>
+
   <clix:special-variable name=3D'*approved-return-codes*'>
     <clix:description>A list of return codes the server should not treat as =
an error -
 see *HANDLE-HTTP-ERRORS-P*.
@@ -1202,28 +1281,7 @@
     <clix:description>The external format used to compute the REQUEST object.
     </clix:description>
   </clix:special-variable>
-  <clix:special-variable name=3D'*lisp-errors-log-level*'>
-    <clix:description>Log level for Lisp errors.
-    </clix:description>
-  </clix:special-variable>
-  <clix:special-variable name=3D'*lisp-warnings-log-level*'>
-    <clix:description>Log level for Lisp warnings.
-    </clix:description>
-  </clix:special-variable>
-  <clix:special-variable name=3D'*log-lisp-errors-p*'>
-    <clix:description>Whether Lisp errors should be logged.
-    </clix:description>
-  </clix:special-variable>
-  <clix:special-variable name=3D'*log-lisp-warnings-p*'>
-    <clix:description>Whether Lisp warnings should be logged.
-    </clix:description>
-  </clix:special-variable>
-  <clix:special-variable name=3D'*message-log-pathname*'>
-    <clix:description>A designator for the pathname of the message log file =
used by the
-LOG-MESSAGE-TO-FILE function.  The initial value is NIL which means
-that nothing will be logged.
-    </clix:description>
-  </clix:special-variable>
+
   <clix:special-variable name=3D'*methods-for-post-parameters*'>
     <clix:description>A list of the request method types (as keywords) for w=
hich
 Hunchentoot will try to compute POST-PARAMETERS.
@@ -2018,17 +2076,6 @@
   </clix:condition>
=20
=20
-  <clix:function name=3D'log-message'>
-  <clix:lambda-list>log-level format-string=20
-  <clix:lkw>rest
-  </clix:lkw> format-arguments
-  </clix:lambda-list>
-  <clix:returns>result
-  </clix:returns>
-    <clix:description>Convenience function which calls the message logger of=
 the current
-acceptor (if there is one) with the same arguments it accepts.
-    </clix:description>
-  </clix:function>
   <clix:function name=3D'mime-type'>
   <clix:lambda-list>pathspec
   </clix:lambda-list>
@@ -2548,6 +2595,33 @@
 name doesn&#039;t exist, it is created.
     </clix:description>
   </clix:function>
+
+
+  <clix:function generic=3D'true' name=3D'process-request'>
+  <clix:lambda-list>request
+  </clix:lambda-list>
+  <clix:returns>nil
+  </clix:returns>
+    <clix:description>
+This function is called by <clix:ref>PROCESS-CONNECTION</clix:ref>
+after the incoming headers have been read.  It selects and calls a
+handler and sends the output of this handler to the client.  It also
+sets up simple error handling for the request handler.  Note
+that <clix:ref>PROCESS-CONNECTION</clix:ref> is called once per
+connection and loops in case of a persistent connection
+while <clix:ref>PROCESS-REQUEST</clix:ref> is called anew for each
+request.
+<p>
+Like <clix:ref>PROCESS-CONNECTION</clix:ref>, this might be a good
+place to introduce around methods which bind special variables or do
+other interesting things.
+</p>
+<p>
+The return value of this function is ignored.
+</p>
+    </clix:description>
+  </clix:function>
+
     </clix:chapter>
=20
   <clix:chapter name=3D"testing" title=3D"Testing">

Modified: trunk/thirdparty/hunchentoot/log.lisp
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
--- trunk/thirdparty/hunchentoot/log.lisp	2009-02-18 19:58:57 UTC (rev 4280)
+++ trunk/thirdparty/hunchentoot/log.lisp	2009-02-18 20:28:27 UTC (rev 4281)
@@ -30,6 +30,11 @@
 (in-package :hunchentoot)
=20
 (defmacro with-log-file ((stream-var pathname lock) &body body)
+  "Helper macro which executes BODY only if PATHNAME \(which is
+evaluated) is not NIL.  In this case, the file designated by PATHNAME
+is opened for writing \(appending) and created if it doesn't exist.
+STREAM-VAR is then bound to a flexi stream which can be used to write
+characters to the file in UTF-8 format."
   (with-unique-names (binary-stream)
     (with-rebinding (pathname)
       `(when ,pathname
@@ -77,7 +82,13 @@
=20
 (defun log-message (log-level format-string &rest format-arguments)
   "Convenience function which calls the message logger of the current
-acceptor \(if there is one) with the same arguments it accepts."
+acceptor \(if there is one) with the same arguments it accepts.
+
+Returns NIL if there is no message logger or whatever the message
+logger returns.
+
+This is the function which Hunchentoot itself uses to log errors it
+catches during request processing."
   (when-let (message-logger (acceptor-message-logger *acceptor*))
     (apply message-logger log-level format-string format-arguments)))
  =20

Modified: trunk/thirdparty/hunchentoot/request.lisp
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
--- trunk/thirdparty/hunchentoot/request.lisp	2009-02-18 19:58:57 UTC (rev 42=
80)
+++ trunk/thirdparty/hunchentoot/request.lisp	2009-02-18 20:28:27 UTC (rev 42=
81)
@@ -99,10 +99,10 @@
   (:documentation "This function is called by PROCESS-CONNECTION after
 the incoming headers have been read.  It selects and calls a handler
 and sends the output of this handler to the client using START-OUTPUT.
-It also sets up simple error handling for the actual request handler.
-Note that PROCESS-CONNECTION is called once per connection and loops
-in case of a persistent connection while PROCESS-REQUEST is called
-anew for each request.
+It also sets up simple error handling for the request handler.  Note
+that PROCESS-CONNECTION is called once per connection and loops in
+case of a persistent connection while PROCESS-REQUEST is called anew
+for each request.
=20
 Like PROCESS-CONNECTION, this might be a good place to introduce
 around methods which bind special variables or do other interesting

Modified: trunk/thirdparty/hunchentoot/specials.lisp
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
--- trunk/thirdparty/hunchentoot/specials.lisp	2009-02-18 19:58:57 UTC (rev 4=
280)
+++ trunk/thirdparty/hunchentoot/specials.lisp	2009-02-18 20:28:27 UTC (rev 4=
281)
@@ -194,19 +194,21 @@
 purposes.")
=20
 (defvar *show-lisp-errors-p* nil
-  "Whether Lisp errors should be shown in HTML output.")
+  "Whether Lisp errors in request handlers should be shown in HTML output.")
=20
 (defvar *log-lisp-errors-p* t
-  "Whether Lisp errors should be logged.")
+  "Whether Lisp errors in request handlers should be logged.")
=20
 (defvar *log-lisp-warnings-p* t
-  "Whether Lisp warnings should be logged.")
+  "Whether Lisp warnings in request handlers should be logged.")
=20
 (defvar *lisp-errors-log-level* :error
-  "Log level for Lisp errors.")
+  "Log level for Lisp errors.  Should be one of :ERROR \(the default),
+:WARNING, or :INFO.")
=20
 (defvar *lisp-warnings-log-level* :warning
-  "Log level for Lisp warnings.")
+  "Log level for Lisp warnings.  Should be one of :ERROR, :WARNING
+\(the default), or :INFO.")
=20
 (defvar *message-log-pathname* nil
   "A designator for the pathname of the message log file used by the
@@ -216,7 +218,7 @@
 (defvar *access-log-pathname* nil
   "A designator for the pathname of the access log file used by the
 LOG-ACCESS-TO-FILE function.  The initial value is NIL which means
-that nothingq will be logged.")
+that nothing will be logged.")
=20
 (defvar *message-log-lock* (make-lock "global-message-log-lock")
   "A global lock to prevent concurrent access to the log file



--===============2027815849467171187==--