Add some resource pool documentation

knots/resource-pool.scm

@@ -154,6 +154,33 @@
                                         (name "unnamed")
                                         default-checkout-timeout
                                         default-max-waiters)
+  "Create a resource pool from RESOURCES-LIST-OR-VECTOR, a list or
+vector of pre-existing resource values.
+
+Use @code{with-resource-from-pool} or
+@code{call-with-resource-from-pool} to borrow a resource and return it
+automatically when done.
+
+Optional keyword arguments:
+
+@table @code
+@item #:name
+A optional string used in log messages.
+Defaults to @code{\"unnamed\"}.
+
+@item #:default-checkout-timeout
+Default checkout timeout when requesting a resource from the pool,
+unset by default.
+
+@item #:default-max-waiters
+Maximum number of fibers that may queue waiting for a resource.  When
+this limit is exceeded, @code{&resource-pool-too-many-waiters} is
+raised when a resource is requested.  Defaults to @code{#f} (no limit).
+
+@item #:scheduler
+The Fibers scheduler to use for the pool's internal fiber.  Defaults
+to the current scheduler.
+@end table"
   (define channel (make-channel))
   (define destroy-condition
     (make-condition))
@@ -513,6 +540,59 @@
                              (add-resources-parallelism 1)
                              default-checkout-timeout
                              default-max-waiters)
+  "Create a dynamic resource pool.  RETURN-NEW-RESOURCE is a thunk
+called to create each new resource value.  MAX-SIZE is the maximum
+number of resources the pool will hold simultaneously.
+
+Resources are created on demand when a checkout is requested and the
+pool is not yet at MAX-SIZE.  Use @code{with-resource-from-pool} or
+@code{call-with-resource-from-pool} to request a resource and return
+it automatically when done.
+
+Optional keyword arguments:
+
+@table @code
+@item #:min-size
+Minimum number of resources to keep alive even when idle.  Defaults to
+@code{0}.
+
+@item #:idle-seconds
+Seconds a resource may remain unused before being destroyed, provided
+the pool is above @code{#:min-size}.  Defaults to @code{#f} (never
+expire idle resources).
+
+@item #:lifetime
+Maximum number of checkouts a single resource will serve before being
+destroyed and replaced by a fresh one.  Defaults to @code{#f} (no
+limit).
+
+@item #:destructor
+A procedure called as @code{(destructor resource)} when a resource is
+removed from the pool. Defaults to @code{#f}.
+
+@item #:add-resources-parallelism
+Maximum number of concurrent calls to RETURN-NEW-RESOURCE when the
+pool needs to grow. Allowing resources to be created in parallel can
+result in more resources being created than can fit inside the pool,
+if this happens, the surplus resources are destroyed. Defaults to
+@code{1}.
+
+@item #:name
+A string used in log messages.  Defaults to @code{\"unnamed\"}.
+
+@item #:default-checkout-timeout
+Default checkout timeout when requesting a resource from the pool,
+unset by default.
+
+@item #:default-max-waiters
+Maximum number of fibers that may queue waiting for a resource.  When
+this limit is exceeded, @code{&resource-pool-too-many-waiters} is
+raised when a resource is requested.  Defaults to @code{#f} (no limit).
+
+@item #:scheduler
+The Fibers scheduler to use for the pool's internal fiber.  Defaults
+to the current scheduler.
+@end table"
   (define channel (make-channel))
   (define destroy-condition
     (make-condition))