[bknr-cvs] edi changed trunk/thirdparty/hunchentoot/

[BKNR Commits]

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

More documentation

U   trunk/thirdparty/hunchentoot/acceptor.lisp
U   trunk/thirdparty/hunchentoot/taskmaster.lisp

Modified: trunk/thirdparty/hunchentoot/acceptor.lisp
===================================================================
--- trunk/thirdparty/hunchentoot/acceptor.lisp	2009-02-16 21:24:05 UTC (rev 4259)
+++ trunk/thirdparty/hunchentoot/acceptor.lisp	2009-02-16 21:53:06 UTC (rev 4260)
@@ -105,7 +105,9 @@
    #+:lispworks
    (process :accessor acceptor-process
             :documentation "The Lisp process which accepts incoming
-requests.")
+requests.  This is the process started by COMM:START-UP-SERVER and no
+matter what kind of taskmaster you are using this will always be a new
+process different from the one where START was called.")
    #-:lispworks
    (listen-socket :accessor acceptor-listen-socket
                   :documentation "The socket listening for incoming

Modified: trunk/thirdparty/hunchentoot/taskmaster.lisp
===================================================================
--- trunk/thirdparty/hunchentoot/taskmaster.lisp	2009-02-16 21:24:05 UTC (rev 4259)
+++ trunk/thirdparty/hunchentoot/taskmaster.lisp	2009-02-16 21:53:06 UTC (rev 4260)
@@ -31,22 +31,18 @@
 
 (defclass taskmaster ()
   ((acceptor :accessor taskmaster-acceptor
-             :documentation "The acceptor instance that this
-taskmaster works for."))
-  (:documentation "Base class for all taskmaster classes.  Its purpose
-is to carry the back pointer to the acceptor instance."))
+             :documentation "A backpointer to the acceptor instance
+this taskmaster works for."))
+  (:documentation "An instance of this class is responsible for
+distributing the work of handling requests when its acceptor "))
 
 (defgeneric execute-acceptor (taskmaster)
-  (:documentation
-   "This function is called once Hunchentoot has performed all initial
-processing to start listening for incoming connections.  It does so by
-calling the ACCEPT-CONNECTIONS functions of the acceptor, taken from
-the ACCEPTOR slot of the taskmaster instance.
+  (:documentation "This is a callback called by the acceptor once it
+has performed all initial processing to start listening for incoming
+connections \(see START-LISTENING).  It usually calls the
+ACCEPT-CONNECTIONS method of the acceptor, but depending on the
+taskmaster instance the method might be called from a new thread."))
 
-In a multi-threaded environment, the taskmaster starts a new
-thread and calls THUNK in that thread.  In a single-threaded
-environment, the thunk will be called directly."))
-
 (defgeneric handle-incoming-connection (taskmaster socket)
   (:documentation
    "This function is called by Hunchentoot to start processing of
@@ -63,28 +59,36 @@
 is called directly."))
 
 (defgeneric shutdown (taskmaster)
-  (:documentation "Terminate all threads that are currently associated
-with the taskmaster, if any."))
+  (:documentation "Shuts down the taskmaster, i.e. frees all resources
+that were set up by it.  For example, a multi-threaded taskmaster
+might terminate all threads that are currently associated with it."))
 
 (defclass single-threaded-taskmaster (taskmaster)
   ()
-  (:documentation "Taskmaster that runs synchronously in the
-thread that invoked the START-SERVER function."))
+  (:documentation "A taskmaster that runs synchronously in the thread
+where the START function was invoked \(or in the case of LispWorks in
+the thread started by COMM:START-UP-SERVER).  This is the simplest
+possible taskmaster implementation in that its methods do nothing but
+calling their acceptor \"sister\" methods - EXECUTE-ACCEPTOR calls
+ACCEPT-CONNECTIONS, HANDLE-INCOMING-CONNECTION calls
+PROCESS-CONNECTION."))
 
 (defmethod execute-acceptor ((taskmaster single-threaded-taskmaster))
+  ;; in a single-threaded environment we just call ACCEPT-CONNECTIONS
   (accept-connections (taskmaster-acceptor taskmaster)))
 
 (defmethod handle-incoming-connection ((taskmaster single-threaded-taskmaster) socket)
+  ;; in a single-threaded environment we just call PROCESS-CONNECTION
   (process-connection (taskmaster-acceptor taskmaster) socket))
 
 (defclass one-thread-per-connection-taskmaster (taskmaster)
-  ((acceptor-process :accessor acceptor-process
-                     :documentation "Process that accepts incoming
+  (#-:lispworks
+   (acceptor-process :accessor acceptor-process
+                     :documentation "A process that accepts incoming
 connections and hands them off to new processes for request
 handling."))
-  (:documentation "Taskmaster that starts one thread for
-listening to incoming requests and one thread for each incoming
-connection."))
+  (:documentation "A taskmaster that starts one thread for listening
+to incoming requests and one thread for each incoming connection."))
 
 ;; usocket implementation
 
@@ -104,7 +108,7 @@
   (setf (acceptor-process taskmaster)
         (bt:make-thread (lambda ()
                           (accept-connections (taskmaster-acceptor taskmaster)))
-                        :name (format nil "Hunchentoot acceptor \(~A:~A)"
+                        :name (format nil "Hunchentoot listener \(~A:~A)"
                                       (or (acceptor-address (taskmaster-acceptor taskmaster)) "*")
                                       (acceptor-port (taskmaster-acceptor taskmaster))))))