doc: minor clarifications on workspace_prealloc

src/vdp_pesi.vcc

@@ -263,24 +263,25 @@ See the detailled discussion in `THREADS`_ for details.
 
 $Function VOID workspace_prealloc(BYTES min_free=4096, INT max_nodes=32)
 
-Configure workspace pre-allocation of objects in variable-sized
-internal data structures.
-
-For each request, the VDP builds such a structure, whose size is
-roughly proportional to the size of the ESI tree -- the conceptual
-tree with the top-level response at the root, and its includes and all
-of their nested includes as branches. The nodes in this structure have
-a fixed size, but the number of nodes used by the VDP varies with the
-size of the ESI tree.
-
-The VDP pre-allocates a constant number of such nodes in client
-workspace, and initially takes nodes from the pre-allocation. If more
-are needed for larger ESI trees, they are obtained from a global
-memory pool as described below. The use of pre-allocated nodes from
-workspace is preferred, since it never requires new system memory
-allocations (workspaces themselves are pre-allocated by Varnish), and
-because they are local to each request, so locking is never required
-to access them (but is required for the memory pool).
+Configure the amount of workspace used for pesi internal data
+structures.
+
+The pesi VDP builds a structure, whose size is roughly proportional to
+the size of the ESI tree -- the conceptual tree with the top-level
+response at the root, and its includes and all of their nested
+includes as branches. The nodes in this structure have a fixed size,
+but the number of nodes used by the VDP varies with the size of the
+ESI tree.
+
+For each (sub)request, the VDP pre-allocates a constant number of such
+nodes in client workspace, and initially uses the pre-allocation for
+child nodes of that (sub)request. If more are needed, they are
+obtained from a global memory pool as described below. The use of
+pre-allocated nodes from workspace is preferred, since it never
+requires new system memory allocations (workspaces themselves are
+pre-allocated by Varnish), and because they are local to each request,
+so locking is never required to access them (but is required for the
+memory pool).
 
 The pre-allocation contributes a fixed size to client workspace usage,
 since the number of pre-allocated nodes is constant. So any adjustment
@@ -296,7 +297,11 @@ pre-allocation will always leave free in client workspace; if the
 targeted number of pre-allocated nodes would result in less free space
 than ``min_free`` bytes in workspace, then fewer nodes are
 allocated. This ensures that free workspace is always left over for
-other VMODs, VCL usage, and so forth. ``min_free`` defaults to 4 KiB.
+other VMODs, VCL usage, and so forth. Note that most of the operations
+typically requiring workspace have already finished when VDP pesi
+makes the pre-allocation, because it starts after `vcl_deliver
+{}`. Thus, the reservation is mostly for other VDPs and VMODs using
+`PRIV_TOP`. ``min_free`` defaults to 4 KiB.
 
 The ``max_nodes`` parameter sets the number of nodes to be allocated,
 unless the limit imposed by ``min_free`` is exceeded; ``max_nodes``