[master] e52a2cb Docs update on VCL temperature with fact checking
Dridi Boukelmoune
dridi.boukelmoune at gmail.com
Thu Aug 27 12:47:26 CEST 2015
commit e52a2cbc4b83df42b7fc2ec686be5328aa61883c
Author: Dridi Boukelmoune <dridi.boukelmoune at gmail.com>
Date: Wed Aug 26 23:45:41 2015 +0200
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`.
diff --git a/bin/varnishtest/tests/v00044.vtc b/bin/varnishtest/tests/v00044.vtc
index 6f44d82..c3fd107 100644
--- a/bin/varnishtest/tests/v00044.vtc
+++ b/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
diff --git a/doc/sphinx/reference/directors.rst b/doc/sphinx/reference/directors.rst
index de321b2..9f1381c 100644
--- a/doc/sphinx/reference/directors.rst
+++ b/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:
diff --git a/doc/sphinx/reference/varnish-cli.rst b/doc/sphinx/reference/varnish-cli.rst
index e400408..4098afd 100644
--- a/doc/sphinx/reference/varnish-cli.rst
+++ b/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
---------
diff --git a/doc/sphinx/reference/vmod.rst b/doc/sphinx/reference/vmod.rst
index 0446e83..b3ccefa 100644
--- a/doc/sphinx/reference/vmod.rst
+++ b/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:
diff --git a/doc/sphinx/whats-new/changes.rst b/doc/sphinx/whats-new/changes.rst
index b7fd4da..4a948ca 100644
--- a/doc/sphinx/whats-new/changes.rst
+++ b/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
diff --git a/lib/libvmod_debug/vmod_debug.c b/lib/libvmod_debug/vmod_debug.c
index 3dddbac..c9b1028 100644
--- a/lib/libvmod_debug/vmod_debug.c
+++ b/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);
More information about the varnish-commit
mailing list