Update the docs about VCL cold/warm transitions.

README.rst

@@ -118,13 +118,13 @@ transaction.
 
 .. |vcl.use| replace:: ``vcl.use``
 
-When a VCL instance transitions to the cold state, the file update
-checks for any of the instance's objects are suspended (see
-|vcl.state|_ in `varnish-cli(7)`_). When it transitions back to the
-warm state (which also happens during an invocation of |vcl.use|_ if
-the VCL had previously been cold), then the files are immediately
-checked for changes, updating the cached contents if necessary, and
-the update checks in the background resume at the TTL interval.
+When a VCL instance transitions to the cold state, the file cache is
+unmapped, and file update checks for any of the instance's objects are
+suspended (see |vcl.state|_ in `varnish-cli(7)`_). When it transitions
+back to the warm state (which also happens during an invocation of
+|vcl.use|_ if the VCL had previously been cold), then the files are
+immediately re-read and cached, and the update checks in the
+background resume at the TTL interval.
 
 File deletion and file updates
 ------------------------------
@@ -682,19 +682,33 @@ they are cached by many VMOD objects in many VCL instances.
 
 .. |vcl.discard| replace:: ``vcl.discard``
 
-File caches are unmapped, and timers are deleted, when the VMOD's
-reader objects are finalized. This happens when the |vcl.discard|_
-command is used to unload VCL instances. While it is not uncommon for
-Varnish admins to neglect ``vcl.discard``, it can become a resource
-leak if too many obsolete VCL instances that use VMOD file are allowed
-to accumulate. Consider implementing a housekeeping procedure to clean
-up old VCLs.
-
-If the file unmappings and timer deletions fail during object
-finalization, error messages are written to the Varnish log using the
-tag ``Error`` (visible with raw grouping). While these errors are
-unlikely, if they do happen, they may be indications of resource
-leaks. Consider monitoring the log for such errors.
+.. _vcl_cooldown: https://varnish-cache.org/docs/trunk/reference/varnishd.html#vcl-cooldown
+
+.. |vcl_cooldown| replace:: ``vcl_cooldown``
+
+File caches are unmapped and timers are suspended when the VCL
+instance transitions to the cold state. Timers are deleted when the
+VMOD's reader objects are finalized, which happens when the
+|vcl.discard|_ command is used to unload VCL instances. When a new VCL
+instance is made active (with ``vcl.use``), the previously active
+instance enters the cold state after the period defined by the
+varnishd parameter |vcl_cooldown|_ elapses (10 minutes in recent
+Varnish versions), unless ``vcl.discard`` is invoked first. The cold
+transition always takes place on VCL discard, if the instance is not
+already cold.
+
+So if you need to release the resources held by objects of this VMOD
+in inactive VCL instances, consider shortening the ``vcl_cooldown``
+period and/or automating the removal of old instances with
+``vcl.discard``.  (Housekeeping with ``vcl.discard`` is a good
+practice for Varnish that is often neglected.)
+
+If the file unmappings and timer suspensions and deletions fail during
+the cold transition or object finalization, error messages are written
+to the Varnish log using the tag ``Error`` (visible with raw
+grouping). While these errors are unlikely, if they do happen, they
+may be indications of resource leaks. Consider monitoring the log for
+such errors.
 
 .. _VSL query: https://varnish-cache.org/docs/trunk/reference/vsl-query.html
 

src/vmod_file.vcc

@@ -114,13 +114,13 @@ transaction.
 
 .. |vcl.use| replace:: ``vcl.use``
 
-When a VCL instance transitions to the cold state, the file update
-checks for any of the instance's objects are suspended (see
-|vcl.state|_ in `varnish-cli(7)`_). When it transitions back to the
-warm state (which also happens during an invocation of |vcl.use|_ if
-the VCL had previously been cold), then the files are immediately
-checked for changes, updating the cached contents if necessary, and
-the update checks in the background resume at the TTL interval.
+When a VCL instance transitions to the cold state, the file cache is
+unmapped, and file update checks for any of the instance's objects are
+suspended (see |vcl.state|_ in `varnish-cli(7)`_). When it transitions
+back to the warm state (which also happens during an invocation of
+|vcl.use|_ if the VCL had previously been cold), then the files are
+immediately re-read and cached, and the update checks in the
+background resume at the TTL interval.
 
 File deletion and file updates
 ------------------------------
@@ -632,19 +632,33 @@ they are cached by many VMOD objects in many VCL instances.
 
 .. |vcl.discard| replace:: ``vcl.discard``
 
-File caches are unmapped, and timers are deleted, when the VMOD's
-reader objects are finalized. This happens when the |vcl.discard|_
-command is used to unload VCL instances. While it is not uncommon for
-Varnish admins to neglect ``vcl.discard``, it can become a resource
-leak if too many obsolete VCL instances that use VMOD file are allowed
-to accumulate. Consider implementing a housekeeping procedure to clean
-up old VCLs.
-
-If the file unmappings and timer deletions fail during object
-finalization, error messages are written to the Varnish log using the
-tag ``Error`` (visible with raw grouping). While these errors are
-unlikely, if they do happen, they may be indications of resource
-leaks. Consider monitoring the log for such errors.
+.. _vcl_cooldown: https://varnish-cache.org/docs/trunk/reference/varnishd.html#vcl-cooldown
+
+.. |vcl_cooldown| replace:: ``vcl_cooldown``
+
+File caches are unmapped and timers are suspended when the VCL
+instance transitions to the cold state. Timers are deleted when the
+VMOD's reader objects are finalized, which happens when the
+|vcl.discard|_ command is used to unload VCL instances. When a new VCL
+instance is made active (with ``vcl.use``), the previously active
+instance enters the cold state after the period defined by the
+varnishd parameter |vcl_cooldown|_ elapses (10 minutes in recent
+Varnish versions), unless ``vcl.discard`` is invoked first. The cold
+transition always takes place on VCL discard, if the instance is not
+already cold.
+
+So if you need to release the resources held by objects of this VMOD
+in inactive VCL instances, consider shortening the ``vcl_cooldown``
+period and/or automating the removal of old instances with
+``vcl.discard``.  (Housekeeping with ``vcl.discard`` is a good
+practice for Varnish that is often neglected.)
+
+If the file unmappings and timer suspensions and deletions fail during
+the cold transition or object finalization, error messages are written
+to the Varnish log using the tag ``Error`` (visible with raw
+grouping). While these errors are unlikely, if they do happen, they
+may be indications of resource leaks. Consider monitoring the log for
+such errors.
 
 .. _VSL query: https://varnish-cache.org/docs/trunk/reference/vsl-query.html