Add more documentation

knots/thread-pool.scm

@@ -211,6 +211,52 @@ from there, or #f if that would be an empty string."
                                       (name "unnamed")
                                       (use-default-io-waiters? #t)
                                       default-checkout-timeout)
+  "Create a pool of SIZE threads started immediately.  Use
+@code{call-with-thread} to run a procedure in one of the threads.
+
+Optional keyword arguments:
+
+@table @code
+@item #:thread-initializer
+A thunk called once when each thread starts.  Its return value is
+passed as extra arguments to every procedure run in that thread.
+Defaults to @code{#f} (no extra arguments).
+
+@item #:thread-destructor
+A procedure called with the value returned by @code{#:thread-initializer}
+when a thread exits.  Defaults to @code{#f}.
+
+@item #:thread-lifetime
+Maximum number of procedures a thread will run before restarting (and
+re-running @code{#:thread-initializer}).  Defaults to @code{#f} (no
+limit).
+
+@item #:expire-on-exception?
+When @code{#t}, replace a thread after any unhandled exception.
+Defaults to @code{#f}.
+
+@item #:use-default-io-waiters?
+When @code{#t} (the default), each thread uses blocking I/O waiters so
+that port reads and writes block the thread rather than trying to
+suspend a fiber.
+
+@item #:name
+String used in thread names and log messages.  Defaults to
+@code{\"unnamed\"}.
+
+@item #:default-checkout-timeout
+Seconds to wait for a free thread slot before raising
+@code{&thread-pool-timeout-error}.  Defaults to @code{#f} (wait
+forever).
+
+@item #:delay-logger
+Called as @code{(delay-logger seconds proc)} with the time spent
+waiting for a thread to become available.
+
+@item #:duration-logger
+Called as @code{(duration-logger seconds proc)} after each procedure
+completes.
+@end table"
   (define channel
     (make-channel))
 
@@ -408,8 +454,34 @@ from there, or #f if that would be an empty string."
                            (use-default-io-waiters? #t)
                            default-checkout-timeout
                            default-max-waiters)
-  "Return a channel used to offload work to a dedicated thread.  ARGS are the
-arguments of the thread pool procedure."
+  "Create a dynamic thread pool with up to MAX-SIZE threads.  Use
+@code{call-with-thread} to run a procedure in one of the threads.
+
+Unlike @code{make-fixed-size-thread-pool}, threads are created on
+demand and may be reclaimed when idle (controlled by @code{#:min-size}
+and the resource pool's idle management).
+
+Accepts the same @code{#:thread-initializer}, @code{#:thread-destructor},
+@code{#:thread-lifetime}, @code{#:expire-on-exception?},
+@code{#:use-default-io-waiters?}, @code{#:name},
+@code{#:default-checkout-timeout}, @code{#:delay-logger}, and
+@code{#:duration-logger} arguments as @code{make-fixed-size-thread-pool},
+plus:
+
+@table @code
+@item #:min-size
+Minimum number of threads to keep alive.  Defaults to MAX-SIZE (i.e.@:
+the pool is pre-filled and never shrinks).
+
+@item #:scheduler
+Fibers scheduler for the pool's internal resource pool fiber.  Defaults
+to the current scheduler.
+
+@item #:default-max-waiters
+Maximum number of fibers that may queue waiting for a thread.  Raises
+@code{&thread-pool-timeout-error} when exceeded.  Defaults to
+@code{#f} (no limit).
+@end table"
   (define param
     (make-parameter #f))
 
@@ -444,8 +516,34 @@ arguments of the thread pool procedure."
                            channel
                            destroy-thread-on-exception?
                            (max-waiters 'default))
-  "Send PROC to the thread pool through CHANNEL.  Return the result of PROC.
-If already in the thread pool, call PROC immediately."
+  "Run PROC in THREAD-POOL and return its values, blocking until
+complete.  If called from within a thread that already belongs to
+THREAD-POOL, PROC is called directly in that thread.
+
+Optional keyword arguments:
+
+@table @code
+@item #:checkout-timeout
+Seconds to wait for a free thread before raising
+@code{&thread-pool-timeout-error}.  Defaults to the pool's
+@code{#:default-checkout-timeout}.
+
+@item #:max-waiters
+Maximum number of fibers that may queue waiting for a thread (for
+dynamic pools).  Defaults to the pool's @code{#:default-max-waiters}.
+
+@item #:destroy-thread-on-exception?
+When @code{#t}, destroy the thread after PROC raises an exception.
+Equivalent to per-call @code{#:expire-on-exception?}.  Defaults to
+@code{#f}.
+
+@item #:duration-logger
+Called as @code{(duration-logger seconds)} after PROC completes
+(whether or not it raised an exception).
+
+@item #:channel
+Override the channel used to communicate with the thread.
+@end table"
   (define (handle-proc fixed-size-thread-pool
                        reply-channel
                        start-time