Docs update on VCL temperature with fact checking

The Varnish CLI documentation was advertising an optional temperature
parameter for `vcl.use`, and overall the test coverage wasn't deep
enough. There is still room for improvement.

The debug VMOD now logs some of the VCL events to help cover more
behavior in `v00044.vtc`.

bin/varnishtest/tests/v00044.vtc

@@ -7,7 +7,9 @@ server s1 -repeat 20 {
 	close
 } -start
 
+# The debug vmod logs some vcl events
 varnish v1 -arg "-p vcl_cooldown=1" -vcl {
+	import ${vmod_debug};
 	backend default {
 		.host = "${s1_addr}";
 		.probe = { .interval = 1s; .initial = 1;}
@@ -51,8 +53,34 @@ varnish v1 -expect VBE.vcl2.default.happy >= 0
 delay 4
 varnish v1 -expect !VBE.vcl2.default.happy
 
-# Mark the used warm and use it the other
+# Mark the used warm and use the other
 varnish v1 -cliok "vcl.state vcl1 warm"
 varnish v1 -cliok "vcl.use vcl2"
+
+# It will stay warm even after the cooldown period
 delay 4
+varnish v1 -expect VBE.vcl1.default.happy >= 0
 varnish v1 -expect VBE.vcl2.default.happy >= 0
+
+# You can't freeze the active VCL
+varnish v1 -clierr 106 "vcl.state vcl2 cold"
+
+# However a warm event is guaranteed...
+logexpect l1 -v v1 -g raw {
+	expect * 0 Debug "vcl1: VCL_EVENT_COLD"
+	expect * 0 Debug "vcl1: VCL_EVENT_WARM"
+	expect * 0 Debug "vcl1: VCL_EVENT_USE"
+} -start
+
+# ...when you use a cold VCL
+varnish v1 -cliok "vcl.state vcl1 cold"
+varnish v1 -cliok "vcl.use vcl1"
+
+logexpect l1 -wait
+
+# It will apply the cooldown period once inactive
+varnish v1 -cliok "vcl.use vcl2"
+delay .4
+varnish v1 -expect VBE.vcl1.default.happy >= 0
+delay 4
+varnish v1 -expect !VBE.vcl1.default.happy

doc/sphinx/reference/directors.rst

@@ -116,9 +116,10 @@ backends.
 
 Finally, Varnish will take care of event propagation for *all* native backends,
 but dynamic backends can only be created when the VCL is warm. If your backends
-are created by an independant thread (basically outside of VCL scope) you must
+are created by an independent thread (basically outside of VCL scope) you must
 subscribe to VCL events and watch for VCL state (see
-:ref:`ref-vmod-event-functions`).
+:ref:`ref-vmod-event-functions`). You are also encouraged to comply with the
+:ref:`ref_vcl_temperature` in general.
 
 
 .. _ref-writing-a-director-cluster:

doc/sphinx/reference/varnish-cli.rst

@@ -107,7 +107,7 @@ vcl.load <configname> <filename> [auto|cold|warm]
 vcl.inline <configname> <quoted_VCLstring> [auto|cold|warm]
   Compile and load the VCL data under the name provided.
 
-vcl.use <configname> [auto|cold|warm]
+vcl.use <configname>
   Switch to the named configuration immediately.
 
 vcl.discard <configname>
@@ -174,6 +174,28 @@ Integers can have "KB", "MB", "GB" or "TB" appended for size related
 fields.
 
 
+.. _ref_vcl_temperature:
+
+VCL Temperature
+---------------
+
+A VCL program goes through several states related to the different commands: it
+can be loaded, used, and later discarded. You can load several VCL programs and
+switch at any time from one to another. There is only one active VCL, but the
+previous active VCL will be maintained active until all its transactions are
+over.
+
+Over time, if you often refresh your VCL and keep the previous versions around,
+resource consumption will increase, you can't escape that. However, most of the
+time you want only one to pay the price only for the active VCL and keep older
+VCLs in case you'd need to rollback to a previous version.
+
+The VCL temperature allows you to minimize the footprint of inactive VCLs. Once
+a VCL becomes cold, Varnish will release all the resources that can be be later
+reacquired. You can manually set the temperature of a VCL or let varnish
+automatically handle it.
+
+
 Scripting
 ---------
 

doc/sphinx/reference/vmod.rst

@@ -355,14 +355,14 @@ The per-call vmod_privs are freed before the per-vcl vmod_priv.
 Event functions
 ===============
 
-VMODs can have an "event" function which is called when a VCL which
-imports the VMOD is loaded, made active, or discarded.  This corresponds
-to the VCL_EVENT_LOAD, VCL_EVENT_USE, and VCL_EVENT_DISCARD events,
-respectively.  In addition, this function will be called when the VCL
-state is changed to cold or warm, corresponding to the VCL_EVENT_COLD
-and VCL_EVENT_WARM events.
+VMODs can have an "event" function which is called when a VCL which imports
+the VMOD is loaded, made active, or discarded.  This corresponds to the
+``VCL_EVENT_LOAD``, ``VCL_EVENT_USE``, and ``VCL_EVENT_DISCARD`` events,
+respectively.  In addition, this function will be called when the VCL state is
+changed to cold or warm, corresponding to the ``VCL_EVENT_COLD`` and
+``VCL_EVENT_WARM`` events.
 
-The first argument to the event function is the VRT context.
+The first argument to the event function is a VRT context.
 
 The second argument is the vmod_priv specific to this particular VCL,
 and if necessary, a VCL specific VMOD "fini" function can be attached
@@ -371,9 +371,16 @@ to its "free" hook.
 The third argument is the event.
 
 If the VMOD has private global state, which includes any sockets or files
-opened, any memory allocated to global or private variables in the C-code
-etc, it is the VMODs own responsibility to track how many VCLs have called
-init (& fini) and free this global state when the count reaches zero
+opened, any memory allocated to global or private variables in the C-code etc,
+it is the VMODs own responsibility to track how many VCLs were loaded or
+discarded and free this global state when the count reaches zero.
+
+VMOD writers are *strongly* encouraged to release all per-VCL resources for a
+given VCL when it emits a ``VCL_EVENT_COLD`` event. You will get a chance to
+reacquire the resources before the VCL becomes active again and be notified
+first with a ``VCL_EVENT_WARM`` event, and then a ``VCL_EVENT_USE`` event.
+Unless a user decides that a given VCL should always be warm, an inactive VMOD
+will eventually become cold and should manage resources accordingly.
 
 .. _ref-vmod-objects:
 

doc/sphinx/whats-new/changes.rst

@@ -61,7 +61,7 @@ Example::
 
 
 VMOD writers should read up on the new vcl_event system to release unnecessary
-state when a VCL is transitioned to cold.
+state when a VCL is transitioned to cold (see ref:`ref-vmod-event-functions`).
 
 
 PROXY protocol support

lib/libvmod_debug/vmod_debug.c

@@ -253,6 +253,17 @@ int __match_proto__(vmod_event_f)
 event_function(VRT_CTX, struct vmod_priv *priv, enum vcl_event_e e)
 {
 	struct priv_vcl *priv_vcl;
+	const char *ev;
+
+	switch (e) {
+		case VCL_EVENT_COLD: ev = "VCL_EVENT_COLD"; break;
+		case VCL_EVENT_WARM: ev = "VCL_EVENT_WARM"; break;
+		case VCL_EVENT_USE:  ev = "VCL_EVENT_USE";  break;
+		default: ev = NULL;
+	}
+
+	if (ev != NULL)
+		VSL(SLT_Debug, 0, "%s: %s", VCL_Name(ctx->vcl), ev);
 
 	if (e != VCL_EVENT_LOAD)
 		return (0);