.get() fallback argument is now optional

Because we can not provide defaults for all types, .get() might trigger
VCL failure now.

Note that the interface is fully compatible with existing VCL, but while
previously a missing fallback argument would trigger a compile time
error, it will result in a VCL failure now.

The types without a default which might trigger a failure are:

* ACL: Trying to match a NULL ACL would trigger a failure in
  varnish-cache anyway

* BODY: Due to the lack of examples, it is unclear what a NULL body
  would look like

  A sensible default might be added later (maybe the empty body?)

* HEADER: A default makes no sense

src/tasktop.h

@@ -74,19 +74,19 @@
 									\
 	VCL_ ## TYPE							\
 	vmod_ ## type ## _get(VRT_CTX, struct vmodpfx_ ## type *va,	\
-	    VCL_ ## TYPE fallback)					\
+	    struct VARGS(type ## _get) *a)				\
 	{								\
 		const struct vmodpfx_ ## type *v = state_r(ctx, va);	\
 									\
-		if (v == NULL)						\
-			return (fallback);				\
+		if (v == NULL || ! v->defined) {			\
+			if (a->valid_fallback)				\
+				return (a->fallback);			\
+			return (DEF_ ## TYPE(ctx));			\
+		}							\
 									\
 		CHECK_OBJ(v, VMODPFX_ ## TYPE ## _MAGIC);		\
 									\
-		if (v->defined)						\
-			return (v->var);				\
-									\
-		return (fallback);					\
+		return (v->var);					\
 	}								\
 									\
 	VCL_VOID							\

src/tbl_types.h

 /* subset of tbl/vcc_types.h which we support */
 
 /* standard text for defaults doc */
-#define DEFDOC The default fallback is
+#define DEFDOC The default `fallback` is
+#define DEFFAIL(ctx, typ) VRT_fail(ctx, #typ "undefined and no fallback provided")
+#define DEFERR Using .get() on an undefined value without a fallback triggers a VCL error.
 
-#define DEF_ACL
-#define DEFDOC_ACL
+// NULL support needs https://github.com/varnishcache/varnish-cache/pull/3622
+#define DEF_ACL(ctx) DEFFAIL(ctx, acl), NULL
+#define DEFDOC_ACL DEFERR
 VCC_TYPE(ACL, acl)
 
-#define DEF_BACKEND = NULL
-#define DEFDOC_BACKEND DEFDOC no backend.
+#define DEF_BACKEND(ctx) NULL
+#define DEFDOC_BACKEND DEFDOC the ``None`` backend.
 VCC_TYPE(BACKEND, backend)
 
-#define DEF_BLOB
-#define DEFDOC_BLOB
+#define DEF_BLOB(ctx) vrt_null_blob
+#define DEFDOC_BLOB DEFDOC the null blob.
 VCC_TYPE(BLOB, blob)
 
-#define DEF_BODY
-#define DEFDOC_BODY
+// NULL OK? There is a lack of vmod examples taking NULL as an argument
+#define DEF_BODY(ctx) DEFFAIL(ctx, body), NULL
+#define DEFDOC_BODY DEFERR
 VCC_TYPE(BODY, body)
 
-#define DEF_BOOL
-#define DEFDOC_BOOL
+#define DEF_BOOL(ctx) 0
+#define DEFDOC_BOOL DEFDOC false
 VCC_TYPE(BOOL, bool)
 
-#define DEF_BYTES
-#define DEFDOC_BYTES
+#define DEF_BYTES(ctx) 0
+#define DEFDOC_BYTES DEFDOC 0 bytes.
 VCC_TYPE(BYTES, bytes)
 
-#define DEF_DURATION = 0
+#define DEF_DURATION(ctx) 0
 #define DEFDOC_DURATION DEFDOC 0s.
 VCC_TYPE(DURATION, duration)
 
 // VCC_TYPE(ENUM, enum)
 
-#define DEF_HEADER
-#define DEFDOC_HEADER
+#define DEF_HEADER(ctx) DEFFAIL(ctx, header), NULL
+#define DEFDOC_HEADER DEFERR
 VCC_TYPE(HEADER, header)
 
 // VCC_TYPE(HTTP, http)
 // VCC_TYPE(INSTANCE, instance)
 
-#define DEF_INT = 0
+#define DEF_INT(ctx) 0
 #define DEFDOC_INT DEFDOC 0.
 VCC_TYPE(INT, int)
 
-#define DEF_IP
-#define DEFDOC_IP
+#define DEF_IP(ctx) bogo_ip
+#define DEFDOC_IP DEFDOC IPv4 0.0.0.0.
 VCC_TYPE(IP, ip)
 
-#define DEF_PROBE
-#define DEFDOC_PROBE
+#define DEF_PROBE(ctx) NULL
+#define DEFDOC_PROBE DEFDOC no backend.
 VCC_TYPE(PROBE, probe)
 
-#define DEF_REAL = 0.0
+#define DEF_REAL(ctx) 0.0
 #define DEFDOC_REAL DEFDOC 0.0.
 VCC_TYPE(REAL, real)
 
-#define DEF_STEVEDORE
-#define DEFDOC_STEVEDORE
+#define DEF_STEVEDORE(ctx) NULL
+#define DEFDOC_STEVEDORE DEFDOC the default storage.
 VCC_TYPE(STEVEDORE, stevedore)
 
 // VCC_TYPE(STRANDS)
 
-#define DEF_STRING = 0
+#define DEF_STRING(ctx) ""
 #define DEFDOC_STRING DEFDOC the empty string.
 VCC_TYPE(STRING, string)
 #ifdef VCCTPL
@@ -79,7 +83,7 @@ Processing ends for a nonempty ``return()`` from ``sub``.
 // VCC_TYPE(STRING_LIST)
 // VCC_TYPE(SUB)
 
-#define DEF_TIME = 0
+#define DEF_TIME(ctx) 0
 #define DEFDOC_TIME DEFDOC the epoch (1970/1/1 0:00:00 GMT).
 VCC_TYPE(TIME, time)
 

src/vmod_constant.c

@@ -106,7 +106,7 @@
 									\
 	VCL_ ## TYPE							\
 	vmod_ ## type ## _get(VRT_CTX, struct vmodpfx_ ## type *v,	\
-	    VCL_ ## TYPE fallback)					\
+	    struct VARGS(type ## _get) *a)				\
 	{								\
 									\
 		(void) ctx;						\
@@ -116,7 +116,9 @@
 		if (v->defined)						\
 			return (v->var);				\
 									\
-		return (fallback);					\
+		if (a->valid_fallback)					\
+			return (a->fallback);				\
+		return (DEF_ ## TYPE(ctx));				\
 	}								\
 									\
 	VCL_BOOL							\

src/vmod_constant.rst

@@ -119,9 +119,12 @@ All vcl subroutines have the same view on constants.
 The value of a constant is the value assigned to it at construction
 time, if any.
 
-constants can be undefined. Attempts to ``.get`` an undefined value
-will return a the ``.get`` method`s `fallback` argument, which in turn
-may have a default for some cases.
+constants are undefined if no value is assigned in the constructor.
+
+Attempts to ``.get()`` an undefined value will return the ``.get()``
+method`s `fallback` argument. For most types, there is a default
+fallback; if there is none, using ``.get()`` on an undefined value
+triggers a VCL failure at runtime.
 
 Example::
 
@@ -159,11 +162,11 @@ will be undefined.
 
 .. _xacl.get():
 
-ACL xacl.get(ACL fallback)
---------------------------
+ACL xacl.get([ACL fallback])
+----------------------------
 
 Return the value of the constant or the `fallback` argument
-if it is undefined. 
+if it is undefined. Using .get() on an undefined value without a fallback triggers a VCL error.
 
 .. _xacl.defined():
 
@@ -183,11 +186,11 @@ will be undefined.
 
 .. _xbackend.get():
 
-BACKEND xbackend.get(BACKEND fallback=NULL)
--------------------------------------------
+BACKEND xbackend.get([BACKEND fallback])
+----------------------------------------
 
 Return the value of the constant or the `fallback` argument
-if it is undefined. The default fallback is no backend.
+if it is undefined. The default `fallback` is the ``None`` backend.
 
 .. _xbackend.defined():
 
@@ -207,11 +210,11 @@ will be undefined.
 
 .. _xblob.get():
 
-BLOB xblob.get(BLOB fallback)
------------------------------
+BLOB xblob.get([BLOB fallback])
+-------------------------------
 
 Return the value of the constant or the `fallback` argument
-if it is undefined. 
+if it is undefined. The default `fallback` is the null blob.
 
 .. _xblob.defined():
 
@@ -231,11 +234,11 @@ will be undefined.
 
 .. _xbody.get():
 
-BODY xbody.get(BODY fallback)
------------------------------
+BODY xbody.get([BODY fallback])
+-------------------------------
 
 Return the value of the constant or the `fallback` argument
-if it is undefined. 
+if it is undefined. Using .get() on an undefined value without a fallback triggers a VCL error.
 
 .. _xbody.defined():
 
@@ -255,11 +258,11 @@ will be undefined.
 
 .. _xbool.get():
 
-BOOL xbool.get(BOOL fallback)
------------------------------
+BOOL xbool.get([BOOL fallback])
+-------------------------------
 
 Return the value of the constant or the `fallback` argument
-if it is undefined. 
+if it is undefined. The default `fallback` is false
 
 .. _xbool.defined():
 
@@ -279,11 +282,11 @@ will be undefined.
 
 .. _xbytes.get():
 
-BYTES xbytes.get(BYTES fallback)
---------------------------------
+BYTES xbytes.get([BYTES fallback])
+----------------------------------
 
 Return the value of the constant or the `fallback` argument
-if it is undefined. 
+if it is undefined. The default `fallback` is 0 bytes.
 
 .. _xbytes.defined():
 
@@ -303,11 +306,11 @@ will be undefined.
 
 .. _xduration.get():
 
-DURATION xduration.get(DURATION fallback=0)
+DURATION xduration.get([DURATION fallback])
 -------------------------------------------
 
 Return the value of the constant or the `fallback` argument
-if it is undefined. The default fallback is 0s.
+if it is undefined. The default `fallback` is 0s.
 
 .. _xduration.defined():
 
@@ -327,11 +330,11 @@ will be undefined.
 
 .. _xheader.get():
 
-HEADER xheader.get(HEADER fallback)
------------------------------------
+HEADER xheader.get([HEADER fallback])
+-------------------------------------
 
 Return the value of the constant or the `fallback` argument
-if it is undefined. 
+if it is undefined. Using .get() on an undefined value without a fallback triggers a VCL error.
 
 .. _xheader.defined():
 
@@ -351,11 +354,11 @@ will be undefined.
 
 .. _xint.get():
 
-INT xint.get(INT fallback=0)
+INT xint.get([INT fallback])
 ----------------------------
 
 Return the value of the constant or the `fallback` argument
-if it is undefined. The default fallback is 0.
+if it is undefined. The default `fallback` is 0.
 
 .. _xint.defined():
 
@@ -375,11 +378,11 @@ will be undefined.
 
 .. _xip.get():
 
-IP xip.get(IP fallback)
------------------------
+IP xip.get([IP fallback])
+-------------------------
 
 Return the value of the constant or the `fallback` argument
-if it is undefined. 
+if it is undefined. The default `fallback` is IPv4 0.0.0.0.
 
 .. _xip.defined():
 
@@ -399,11 +402,11 @@ will be undefined.
 
 .. _xprobe.get():
 
-PROBE xprobe.get(PROBE fallback)
---------------------------------
+PROBE xprobe.get([PROBE fallback])
+----------------------------------
 
 Return the value of the constant or the `fallback` argument
-if it is undefined. 
+if it is undefined. The default `fallback` is no backend.
 
 .. _xprobe.defined():
 
@@ -423,11 +426,11 @@ will be undefined.
 
 .. _xreal.get():
 
-REAL xreal.get(REAL fallback=0.0)
----------------------------------
+REAL xreal.get([REAL fallback])
+-------------------------------
 
 Return the value of the constant or the `fallback` argument
-if it is undefined. The default fallback is 0.0.
+if it is undefined. The default `fallback` is 0.0.
 
 .. _xreal.defined():
 
@@ -447,11 +450,11 @@ will be undefined.
 
 .. _xstevedore.get():
 
-STEVEDORE xstevedore.get(STEVEDORE fallback)
---------------------------------------------
+STEVEDORE xstevedore.get([STEVEDORE fallback])
+----------------------------------------------
 
 Return the value of the constant or the `fallback` argument
-if it is undefined. 
+if it is undefined. The default `fallback` is the default storage.
 
 .. _xstevedore.defined():
 
@@ -471,11 +474,11 @@ will be undefined.
 
 .. _xstring.get():
 
-STRING xstring.get(STRING fallback=0)
+STRING xstring.get([STRING fallback])
 -------------------------------------
 
 Return the value of the constant or the `fallback` argument
-if it is undefined. The default fallback is the empty string.
+if it is undefined. The default `fallback` is the empty string.
 
 .. _xstring.defined():
 
@@ -495,11 +498,11 @@ will be undefined.
 
 .. _xtime.get():
 
-TIME xtime.get(TIME fallback=0)
+TIME xtime.get([TIME fallback])
 -------------------------------
 
 Return the value of the constant or the `fallback` argument
-if it is undefined. The default fallback is the epoch (1970/1/1 0:00:00 GMT).
+if it is undefined. The default `fallback` is the epoch (1970/1/1 0:00:00 GMT).
 
 .. _xtime.defined():
 

src/vmod_constant.vcctpl

@@ -9,9 +9,12 @@ All vcl subroutines have the same view on constants.
 The value of a constant is the value assigned to it at construction
 time, if any.
 
-constants can be undefined. Attempts to ``.get`` an undefined value
-will return a the ``.get`` method`s `fallback` argument, which in turn
-may have a default for some cases.
+constants are undefined if no value is assigned in the constructor.
+
+Attempts to ``.get()`` an undefined value will return the ``.get()``
+method`s `fallback` argument. For most types, there is a default
+fallback; if there is none, using ``.get()`` on an undefined value
+triggers a VCL failure at runtime.
 
 Example::
 
@@ -40,10 +43,10 @@ for the respective type names and the ``.get()`` fallback.
 
 #define VCC_TYPE(TYPE, type)					\
 $Object type([TYPE init])\n					\
-Construct a(n) TYPE constant with the value `init`,\n	\
+Construct a(n) TYPE constant with the value `init`,\n		\
 if provided. If no `init` value is provided, the constant\n	\
-will be undefined.\n					\
-$Method TYPE .get(TYPE fallback DEF_ ## TYPE)\n			\
+will be undefined.\n						\
+$Method TYPE .get([TYPE fallback])\n				\
 Return the value of the constant or the `fallback` argument\n	\
 if it is undefined. DEFDOC_ ## TYPE\n				\
 $Method BOOL .defined()\n					\

src/vmod_globalvar.c

@@ -187,10 +187,13 @@ task_ref_var(VRT_CTX, struct vmod_globalvar_var *v, unsigned magic) {
 									\
 	VCL_ ## TYPE							\
 	vmod_ ## type ## _get(VRT_CTX, struct vmodpfx_ ## type *v,	\
-	    VCL_ ## TYPE fallback)					\
+	    struct VARGS(type ## _get) *a)				\
 	{								\
-		if (! v->defined)					\
-			return (fallback);				\
+		if (! v->defined) {					\
+			if (a->valid_fallback)				\
+				return (a->fallback);			\
+			return (DEF_ ## TYPE(ctx));			\
+		}							\
 		VRMB();							\
 		return (v->var);					\
 	}
@@ -263,24 +266,31 @@ task_ref_var(VRT_CTX, struct vmod_globalvar_var *v, unsigned magic) {
 									\
 	VCL_ ## TYPE							\
 	vmod_ ## type ## _get(VRT_CTX, struct vmodpfx_ ## type *v,	\
-	    VCL_ ## TYPE fallback)					\
+	    struct VARGS(type ## _get) *a)				\
 	{								\
 		VCL_ ## TYPE	r;					\
 		const unsigned magic = VMOD_GLOBALVAR_VAR_MAGIC_BITS |	\
 		    VMODPFX_ ## TYPE ## _MAGIC;				\
+		int fallback = 0;					\
 									\
 		CHECK_OBJ_NOTNULL(v, VMODPFX_ ## TYPE ## _MAGIC);	\
 									\
 		if (! v->defined)					\
-			return (fallback);				\
+			goto def;					\
 									\
 		pthread_mutex_lock(&v->mtx);				\
 		if (! v->defined)					\
-			r = fallback;					\
+			fallback = 1;					\
 		else							\
 			r = task_ref_var(ctx, v->var, magic);		\
 		pthread_mutex_unlock(&v->mtx);				\
+		if (fallback)						\
+			goto def;					\
 		return (r);						\
+	  def:								\
+		if (a->valid_fallback)					\
+			return (a->fallback);				\
+		return (DEF_ ## TYPE(ctx));				\
 	}
 
 #define var_code(vmod_, VMODPFX_, vmodpfx_, TYPE, type)			\

src/vmod_globalvar.rst

@@ -177,13 +177,17 @@ This module implements globally (per vcl) scoped variables as objects:
 All vcl subroutines have the same view on variables, any change comes
 in effect immediately.
 
-The value of a globalvar is the value assigned to it by any vcl
-subroutine within each vcl or a default provided at construction time,
-if any.
+The value of a globalvar is the either the initial value from the
+constructor or the last value assigned by any task executing the
+respective vcl.
 
-globalvars can be undefined. Attempts to ``.get`` an undefined value
-will return a the ``.get`` method`s `fallback` argument, which in turn
-may have a default for some cases.
+If no value is set, it is undefined. A globalvar can also be undefined
+using the ``.undefine()`` method.
+
+Attempts to ``.get()`` an undefined value will return the ``.get()``
+method`s `fallback` argument. For most types, there is a default
+fallback; if there is none, using ``.get()`` on an undefined value
+triggers a VCL failure at runtime.
 
 Where necessary, read access to globalvar variables is reference
 counted using priv_task state, such that changed variables` storage is
@@ -227,11 +231,11 @@ will be initially undefined.
 
 .. _xacl.get():
 
-ACL xacl.get(ACL fallback)
---------------------------
+ACL xacl.get([ACL fallback])
+----------------------------
 
 Return the value of the globalvar or the `fallback` argument
-if it is undefined. 
+if it is undefined. Using .get() on an undefined value without a fallback triggers a VCL error.
 
 .. _xacl.set():
 
@@ -265,11 +269,11 @@ will be initially undefined.
 
 .. _xbackend.get():
 
-BACKEND xbackend.get(BACKEND fallback=NULL)
--------------------------------------------
+BACKEND xbackend.get([BACKEND fallback])
+----------------------------------------
 
 Return the value of the globalvar or the `fallback` argument
-if it is undefined. The default fallback is no backend.
+if it is undefined. The default `fallback` is the ``None`` backend.
 
 .. _xbackend.set():
 
@@ -303,11 +307,11 @@ will be initially undefined.
 
 .. _xblob.get():
 
-BLOB xblob.get(BLOB fallback)
------------------------------
+BLOB xblob.get([BLOB fallback])
+-------------------------------
 
 Return the value of the globalvar or the `fallback` argument
-if it is undefined. 
+if it is undefined. The default `fallback` is the null blob.
 
 .. _xblob.set():
 
@@ -341,11 +345,11 @@ will be initially undefined.
 
 .. _xbody.get():
 
-BODY xbody.get(BODY fallback)
------------------------------
+BODY xbody.get([BODY fallback])
+-------------------------------
 
 Return the value of the globalvar or the `fallback` argument
-if it is undefined. 
+if it is undefined. Using .get() on an undefined value without a fallback triggers a VCL error.
 
 .. _xbody.set():
 
@@ -379,11 +383,11 @@ will be initially undefined.
 
 .. _xbool.get():
 
-BOOL xbool.get(BOOL fallback)
------------------------------
+BOOL xbool.get([BOOL fallback])
+-------------------------------
 
 Return the value of the globalvar or the `fallback` argument
-if it is undefined. 
+if it is undefined. The default `fallback` is false
 
 .. _xbool.set():
 
@@ -417,11 +421,11 @@ will be initially undefined.
 
 .. _xbytes.get():
 
-BYTES xbytes.get(BYTES fallback)
---------------------------------
+BYTES xbytes.get([BYTES fallback])
+----------------------------------
 
 Return the value of the globalvar or the `fallback` argument
-if it is undefined. 
+if it is undefined. The default `fallback` is 0 bytes.
 
 .. _xbytes.set():
 
@@ -455,11 +459,11 @@ will be initially undefined.
 
 .. _xduration.get():
 
-DURATION xduration.get(DURATION fallback=0)
+DURATION xduration.get([DURATION fallback])
 -------------------------------------------
 
 Return the value of the globalvar or the `fallback` argument
-if it is undefined. The default fallback is 0s.
+if it is undefined. The default `fallback` is 0s.
 
 .. _xduration.set():
 
@@ -493,11 +497,11 @@ will be initially undefined.
 
 .. _xheader.get():
 
-HEADER xheader.get(HEADER fallback)
------------------------------------
+HEADER xheader.get([HEADER fallback])
+-------------------------------------
 
 Return the value of the globalvar or the `fallback` argument
-if it is undefined. 
+if it is undefined. Using .get() on an undefined value without a fallback triggers a VCL error.
 
 .. _xheader.set():
 
@@ -531,11 +535,11 @@ will be initially undefined.
 
 .. _xint.get():
 
-INT xint.get(INT fallback=0)
+INT xint.get([INT fallback])
 ----------------------------
 
 Return the value of the globalvar or the `fallback` argument
-if it is undefined. The default fallback is 0.
+if it is undefined. The default `fallback` is 0.
 
 .. _xint.set():
 
@@ -569,11 +573,11 @@ will be initially undefined.
 
 .. _xip.get():
 
-IP xip.get(IP fallback)
------------------------
+IP xip.get([IP fallback])
+-------------------------
 
 Return the value of the globalvar or the `fallback` argument
-if it is undefined. 
+if it is undefined. The default `fallback` is IPv4 0.0.0.0.
 
 .. _xip.set():
 
@@ -607,11 +611,11 @@ will be initially undefined.
 
 .. _xprobe.get():
 
-PROBE xprobe.get(PROBE fallback)
---------------------------------
+PROBE xprobe.get([PROBE fallback])
+----------------------------------
 
 Return the value of the globalvar or the `fallback` argument
-if it is undefined. 
+if it is undefined. The default `fallback` is no backend.
 
 .. _xprobe.set():
 
@@ -645,11 +649,11 @@ will be initially undefined.
 
 .. _xreal.get():
 
-REAL xreal.get(REAL fallback=0.0)
----------------------------------
+REAL xreal.get([REAL fallback])
+-------------------------------
 
 Return the value of the globalvar or the `fallback` argument
-if it is undefined. The default fallback is 0.0.
+if it is undefined. The default `fallback` is 0.0.
 
 .. _xreal.set():
 
@@ -683,11 +687,11 @@ will be initially undefined.
 
 .. _xstevedore.get():
 
-STEVEDORE xstevedore.get(STEVEDORE fallback)
---------------------------------------------
+STEVEDORE xstevedore.get([STEVEDORE fallback])
+----------------------------------------------
 
 Return the value of the globalvar or the `fallback` argument
-if it is undefined. 
+if it is undefined. The default `fallback` is the default storage.
 
 .. _xstevedore.set():
 
@@ -721,11 +725,11 @@ will be initially undefined.
 
 .. _xstring.get():
 
-STRING xstring.get(STRING fallback=0)
+STRING xstring.get([STRING fallback])
 -------------------------------------
 
 Return the value of the globalvar or the `fallback` argument
-if it is undefined. The default fallback is the empty string.
+if it is undefined. The default `fallback` is the empty string.
 
 .. _xstring.set():
 
@@ -759,11 +763,11 @@ will be initially undefined.
 
 .. _xtime.get():
 
-TIME xtime.get(TIME fallback=0)
+TIME xtime.get([TIME fallback])
 -------------------------------
 
 Return the value of the globalvar or the `fallback` argument
-if it is undefined. The default fallback is the epoch (1970/1/1 0:00:00 GMT).
+if it is undefined. The default `fallback` is the epoch (1970/1/1 0:00:00 GMT).
 
 .. _xtime.set():
 

src/vmod_globalvar.vcctpl

@@ -7,13 +7,17 @@ This module implements globally (per vcl) scoped variables as objects:
 All vcl subroutines have the same view on variables, any change comes
 in effect immediately.
 
-The value of a globalvar is the value assigned to it by any vcl
-subroutine within each vcl or a default provided at construction time,
-if any.
+The value of a globalvar is the either the initial value from the
+constructor or the last value assigned by any task executing the
+respective vcl.
 
-globalvars can be undefined. Attempts to ``.get`` an undefined value
-will return a the ``.get`` method`s `fallback` argument, which in turn
-may have a default for some cases.
+If no value is set, it is undefined. A globalvar can also be undefined
+using the ``.undefine()`` method.
+
+Attempts to ``.get()`` an undefined value will return the ``.get()``
+method`s `fallback` argument. For most types, there is a default
+fallback; if there is none, using ``.get()`` on an undefined value
+triggers a VCL failure at runtime.
 
 Where necessary, read access to globalvar variables is reference
 counted using priv_task state, such that changed variables` storage is
@@ -51,7 +55,7 @@ $Object type([TYPE init])\n					\
 Construct a(n) TYPE globalvar with the default value `init`,\n	\
 if provided. If no `init` value is provided, the variable\n	\
 will be initially undefined.\n					\
-$Method TYPE .get(TYPE fallback DEF_ ## TYPE)\n			\
+$Method TYPE .get([TYPE fallback])\n			\
 Return the value of the globalvar or the `fallback` argument\n	\
 if it is undefined. DEFDOC_ ## TYPE\n				\
 $Method VOID .set(TYPE)\n					\

src/vmod_taskvar.rst

@@ -238,15 +238,22 @@ DESCRIPTION
 This module implements `task` scoped variables as objects: Each client
 or backend request (`task`) has their own view of taskvar variables.
 
-The value of a taskvar is the value assigned to it within a `task` or
-a default provided at construction time, if any.
+A taskvar can be constructed with a default, which is used as the
+initial value at the beginning of each `task`.
 
-taskvars can be undefined. Attempts to ``.get`` an undefined value
-will return a the ``.get`` method`s `fallback` argument, which in turn
-may have a default for some cases.
+The value of a taskvar is the either the default or the last value
+assigned to it within a `task`. If neither a default nor previous
+value was set, then the value is undefined.
+
+A taskvar can also be undefined using the ``.undefine()`` method.
+
+Attempts to ``.get()`` an undefined value will return the ``.get()``
+method`s `fallback` argument. For most types, there is a default
+fallback; if there is none, using ``.get()`` on an undefined value
+triggers a VCL failure at runtime.
 
 taskvar variables can be protected against write access, in which case
-any attempt to set them triggers a VCL failure at runtime.
+any attempt to ``.set()`` them triggers a VCL failure at runtime.
 
 Example with an initially undefined variable::
 
@@ -306,11 +313,11 @@ will be initially undefined.
 
 .. _xacl.get():
 
-ACL xacl.get(ACL fallback)
---------------------------
+ACL xacl.get([ACL fallback])
+----------------------------
 
 Return the value of the taskvar or the `fallback` argument
-if it is undefined. 
+if it is undefined. Using .get() on an undefined value without a fallback triggers a VCL error.
 
 .. _xacl.set():
 
@@ -361,11 +368,11 @@ will be initially undefined.
 
 .. _xbackend.get():
 
-BACKEND xbackend.get(BACKEND fallback=NULL)
--------------------------------------------
+BACKEND xbackend.get([BACKEND fallback])
+----------------------------------------
 
 Return the value of the taskvar or the `fallback` argument
-if it is undefined. The default fallback is no backend.
+if it is undefined. The default `fallback` is the ``None`` backend.
 
 .. _xbackend.set():
 
@@ -416,11 +423,11 @@ will be initially undefined.
 
 .. _xblob.get():
 
-BLOB xblob.get(BLOB fallback)
------------------------------
+BLOB xblob.get([BLOB fallback])
+-------------------------------
 
 Return the value of the taskvar or the `fallback` argument
-if it is undefined. 
+if it is undefined. The default `fallback` is the null blob.
 
 .. _xblob.set():
 
@@ -471,11 +478,11 @@ will be initially undefined.
 
 .. _xbody.get():
 
-BODY xbody.get(BODY fallback)
------------------------------
+BODY xbody.get([BODY fallback])
+-------------------------------
 
 Return the value of the taskvar or the `fallback` argument
-if it is undefined. 
+if it is undefined. Using .get() on an undefined value without a fallback triggers a VCL error.
 
 .. _xbody.set():
 
@@ -526,11 +533,11 @@ will be initially undefined.
 
 .. _xbool.get():
 
-BOOL xbool.get(BOOL fallback)
------------------------------
+BOOL xbool.get([BOOL fallback])
+-------------------------------
 
 Return the value of the taskvar or the `fallback` argument
-if it is undefined. 
+if it is undefined. The default `fallback` is false
 
 .. _xbool.set():
 
@@ -581,11 +588,11 @@ will be initially undefined.
 
 .. _xbytes.get():
 
-BYTES xbytes.get(BYTES fallback)
---------------------------------
+BYTES xbytes.get([BYTES fallback])
+----------------------------------
 
 Return the value of the taskvar or the `fallback` argument
-if it is undefined. 
+if it is undefined. The default `fallback` is 0 bytes.
 
 .. _xbytes.set():
 
@@ -636,11 +643,11 @@ will be initially undefined.
 
 .. _xduration.get():
 
-DURATION xduration.get(DURATION fallback=0)
+DURATION xduration.get([DURATION fallback])
 -------------------------------------------
 
 Return the value of the taskvar or the `fallback` argument
-if it is undefined. The default fallback is 0s.
+if it is undefined. The default `fallback` is 0s.
 
 .. _xduration.set():
 
@@ -691,11 +698,11 @@ will be initially undefined.
 
 .. _xheader.get():
 
-HEADER xheader.get(HEADER fallback)
------------------------------------
+HEADER xheader.get([HEADER fallback])
+-------------------------------------
 
 Return the value of the taskvar or the `fallback` argument
-if it is undefined. 
+if it is undefined. Using .get() on an undefined value without a fallback triggers a VCL error.
 
 .. _xheader.set():
 
@@ -746,11 +753,11 @@ will be initially undefined.
 
 .. _xint.get():
 
-INT xint.get(INT fallback=0)
+INT xint.get([INT fallback])
 ----------------------------
 
 Return the value of the taskvar or the `fallback` argument
-if it is undefined. The default fallback is 0.
+if it is undefined. The default `fallback` is 0.
 
 .. _xint.set():
 
@@ -801,11 +808,11 @@ will be initially undefined.
 
 .. _xip.get():
 
-IP xip.get(IP fallback)
------------------------
+IP xip.get([IP fallback])
+-------------------------
 
 Return the value of the taskvar or the `fallback` argument
-if it is undefined. 
+if it is undefined. The default `fallback` is IPv4 0.0.0.0.
 
 .. _xip.set():
 
@@ -856,11 +863,11 @@ will be initially undefined.
 
 .. _xprobe.get():
 
-PROBE xprobe.get(PROBE fallback)
---------------------------------
+PROBE xprobe.get([PROBE fallback])
+----------------------------------
 
 Return the value of the taskvar or the `fallback` argument
-if it is undefined. 
+if it is undefined. The default `fallback` is no backend.
 
 .. _xprobe.set():
 
@@ -911,11 +918,11 @@ will be initially undefined.
 
 .. _xreal.get():
 
-REAL xreal.get(REAL fallback=0.0)
----------------------------------
+REAL xreal.get([REAL fallback])
+-------------------------------
 
 Return the value of the taskvar or the `fallback` argument
-if it is undefined. The default fallback is 0.0.
+if it is undefined. The default `fallback` is 0.0.
 
 .. _xreal.set():
 
@@ -966,11 +973,11 @@ will be initially undefined.
 
 .. _xstevedore.get():
 
-STEVEDORE xstevedore.get(STEVEDORE fallback)
---------------------------------------------
+STEVEDORE xstevedore.get([STEVEDORE fallback])
+----------------------------------------------
 
 Return the value of the taskvar or the `fallback` argument
-if it is undefined. 
+if it is undefined. The default `fallback` is the default storage.
 
 .. _xstevedore.set():
 
@@ -1021,11 +1028,11 @@ will be initially undefined.
 
 .. _xstring.get():
 
-STRING xstring.get(STRING fallback=0)
+STRING xstring.get([STRING fallback])
 -------------------------------------
 
 Return the value of the taskvar or the `fallback` argument
-if it is undefined. The default fallback is the empty string.
+if it is undefined. The default `fallback` is the empty string.
 
 .. _xstring.set():
 
@@ -1091,11 +1098,11 @@ will be initially undefined.
 
 .. _xtime.get():
 
-TIME xtime.get(TIME fallback=0)
+TIME xtime.get([TIME fallback])
 -------------------------------
 
 Return the value of the taskvar or the `fallback` argument
-if it is undefined. The default fallback is the epoch (1970/1/1 0:00:00 GMT).
+if it is undefined. The default `fallback` is the epoch (1970/1/1 0:00:00 GMT).
 
 .. _xtime.set():
 

src/vmod_taskvar.vcctpl

@@ -6,15 +6,22 @@ DESCRIPTION
 This module implements `task` scoped variables as objects: Each client
 or backend request (`task`) has their own view of taskvar variables.
 
-The value of a taskvar is the value assigned to it within a `task` or
-a default provided at construction time, if any.
+A taskvar can be constructed with a default, which is used as the
+initial value at the beginning of each `task`.
 
-taskvars can be undefined. Attempts to ``.get`` an undefined value
-will return a the ``.get`` method`s `fallback` argument, which in turn
-may have a default for some cases.
+The value of a taskvar is the either the default or the last value
+assigned to it within a `task`. If neither a default nor previous
+value was set, then the value is undefined.
+
+A taskvar can also be undefined using the ``.undefine()`` method.
+
+Attempts to ``.get()`` an undefined value will return the ``.get()``
+method`s `fallback` argument. For most types, there is a default
+fallback; if there is none, using ``.get()`` on an undefined value
+triggers a VCL failure at runtime.
 
 taskvar variables can be protected against write access, in which case
-any attempt to set them triggers a VCL failure at runtime.
+any attempt to ``.set()`` them triggers a VCL failure at runtime.
 
 Example with an initially undefined variable::
 
@@ -70,7 +77,7 @@ $Object type([TYPE init])\n					\
 Construct a(n) TYPE taskvar with the default value `init`,\n	\
 if provided. If no `init` value is provided, the variable\n	\
 will be initially undefined.\n					\
-$Method TYPE .get(TYPE fallback DEF_ ## TYPE)\n			\
+$Method TYPE .get([TYPE fallback])\n			\
 Return the value of the taskvar or the `fallback` argument\n	\
 if it is undefined. DEFDOC_ ## TYPE\n				\
 $Method VOID .set(TYPE)\n					\

src/vmod_topvar.rst

@@ -237,15 +237,22 @@ This module implements `top` scoped variables as objects: Each client
 request including all esi include levels (`top`) has its own view of
 topvar variables.
 
-The value of a topvar is the value assigned to it within any esi
-subrequest or a default provided at construction time, if any.
+A topvar can be constructed with a default, which is used as the
+initial value at the beginning of each request at esi level 0.
 
-topvars can be undefined. Attempts to ``.get`` an undefined value will
-return a the ``.get`` method`s `fallback` argument, which in turn may
-have a default for some cases.
+The value of a topvar is the either the default or the last value
+assigned to it within any esi subrequest. If neither a default nor
+previous value was set, then the value is undefined.
+
+A topvar can also be undefined using the ``.undefine()`` method.
+
+Attempts to ``.get()`` an undefined value will return the ``.get()``
+method`s `fallback` argument. For most types, there is a default
+fallback; if there is none, using ``.get()`` on an undefined value
+triggers a VCL failure at runtime.
 
 topvar variables can be protected against write access, in which case
-any attempt to set them triggers a VCL failure at runtime.
+any attempt to ``.set()`` them triggers a VCL failure at runtime.
 
 Example::
 
@@ -287,11 +294,11 @@ will be initially undefined.
 
 .. _xacl.get():
 
-ACL xacl.get(ACL fallback)
---------------------------
+ACL xacl.get([ACL fallback])
+----------------------------
 
 Return the value of the topvar or the `fallback` argument
-if it is undefined. 
+if it is undefined. Using .get() on an undefined value without a fallback triggers a VCL error.
 
 .. _xacl.set():
 
@@ -342,11 +349,11 @@ will be initially undefined.
 
 .. _xbackend.get():
 
-BACKEND xbackend.get(BACKEND fallback=NULL)
--------------------------------------------
+BACKEND xbackend.get([BACKEND fallback])
+----------------------------------------
 
 Return the value of the topvar or the `fallback` argument
-if it is undefined. The default fallback is no backend.
+if it is undefined. The default `fallback` is the ``None`` backend.
 
 .. _xbackend.set():
 
@@ -397,11 +404,11 @@ will be initially undefined.
 
 .. _xblob.get():
 
-BLOB xblob.get(BLOB fallback)
------------------------------
+BLOB xblob.get([BLOB fallback])
+-------------------------------
 
 Return the value of the topvar or the `fallback` argument
-if it is undefined. 
+if it is undefined. The default `fallback` is the null blob.
 
 .. _xblob.set():
 
@@ -452,11 +459,11 @@ will be initially undefined.
 
 .. _xbody.get():
 
-BODY xbody.get(BODY fallback)
------------------------------
+BODY xbody.get([BODY fallback])
+-------------------------------
 
 Return the value of the topvar or the `fallback` argument
-if it is undefined. 
+if it is undefined. Using .get() on an undefined value without a fallback triggers a VCL error.
 
 .. _xbody.set():
 
@@ -507,11 +514,11 @@ will be initially undefined.
 
 .. _xbool.get():
 
-BOOL xbool.get(BOOL fallback)
------------------------------
+BOOL xbool.get([BOOL fallback])
+-------------------------------
 
 Return the value of the topvar or the `fallback` argument
-if it is undefined. 
+if it is undefined. The default `fallback` is false
 
 .. _xbool.set():
 
@@ -562,11 +569,11 @@ will be initially undefined.
 
 .. _xbytes.get():
 
-BYTES xbytes.get(BYTES fallback)
---------------------------------
+BYTES xbytes.get([BYTES fallback])
+----------------------------------
 
 Return the value of the topvar or the `fallback` argument
-if it is undefined. 
+if it is undefined. The default `fallback` is 0 bytes.
 
 .. _xbytes.set():
 
@@ -617,11 +624,11 @@ will be initially undefined.
 
 .. _xduration.get():
 
-DURATION xduration.get(DURATION fallback=0)
+DURATION xduration.get([DURATION fallback])
 -------------------------------------------
 
 Return the value of the topvar or the `fallback` argument
-if it is undefined. The default fallback is 0s.
+if it is undefined. The default `fallback` is 0s.
 
 .. _xduration.set():
 
@@ -672,11 +679,11 @@ will be initially undefined.
 
 .. _xheader.get():
 
-HEADER xheader.get(HEADER fallback)
------------------------------------
+HEADER xheader.get([HEADER fallback])
+-------------------------------------
 
 Return the value of the topvar or the `fallback` argument
-if it is undefined. 
+if it is undefined. Using .get() on an undefined value without a fallback triggers a VCL error.
 
 .. _xheader.set():
 
@@ -727,11 +734,11 @@ will be initially undefined.
 
 .. _xint.get():
 
-INT xint.get(INT fallback=0)
+INT xint.get([INT fallback])
 ----------------------------
 
 Return the value of the topvar or the `fallback` argument
-if it is undefined. The default fallback is 0.
+if it is undefined. The default `fallback` is 0.
 
 .. _xint.set():
 
@@ -782,11 +789,11 @@ will be initially undefined.
 
 .. _xip.get():
 
-IP xip.get(IP fallback)
------------------------
+IP xip.get([IP fallback])
+-------------------------
 
 Return the value of the topvar or the `fallback` argument
-if it is undefined. 
+if it is undefined. The default `fallback` is IPv4 0.0.0.0.
 
 .. _xip.set():
 
@@ -837,11 +844,11 @@ will be initially undefined.
 
 .. _xprobe.get():
 
-PROBE xprobe.get(PROBE fallback)
---------------------------------
+PROBE xprobe.get([PROBE fallback])
+----------------------------------
 
 Return the value of the topvar or the `fallback` argument
-if it is undefined. 
+if it is undefined. The default `fallback` is no backend.
 
 .. _xprobe.set():
 
@@ -892,11 +899,11 @@ will be initially undefined.
 
 .. _xreal.get():
 
-REAL xreal.get(REAL fallback=0.0)
----------------------------------
+REAL xreal.get([REAL fallback])
+-------------------------------
 
 Return the value of the topvar or the `fallback` argument
-if it is undefined. The default fallback is 0.0.
+if it is undefined. The default `fallback` is 0.0.
 
 .. _xreal.set():
 
@@ -947,11 +954,11 @@ will be initially undefined.
 
 .. _xstevedore.get():
 
-STEVEDORE xstevedore.get(STEVEDORE fallback)
---------------------------------------------
+STEVEDORE xstevedore.get([STEVEDORE fallback])
+----------------------------------------------
 
 Return the value of the topvar or the `fallback` argument
-if it is undefined. 
+if it is undefined. The default `fallback` is the default storage.
 
 .. _xstevedore.set():
 
@@ -1002,11 +1009,11 @@ will be initially undefined.
 
 .. _xstring.get():
 
-STRING xstring.get(STRING fallback=0)
+STRING xstring.get([STRING fallback])
 -------------------------------------
 
 Return the value of the topvar or the `fallback` argument
-if it is undefined. The default fallback is the empty string.
+if it is undefined. The default `fallback` is the empty string.
 
 .. _xstring.set():
 
@@ -1057,11 +1064,11 @@ will be initially undefined.
 
 .. _xtime.get():
 
-TIME xtime.get(TIME fallback=0)
+TIME xtime.get([TIME fallback])
 -------------------------------
 
 Return the value of the topvar or the `fallback` argument
-if it is undefined. The default fallback is the epoch (1970/1/1 0:00:00 GMT).
+if it is undefined. The default `fallback` is the epoch (1970/1/1 0:00:00 GMT).
 
 .. _xtime.set():
 

src/vmod_topvar.vcctpl

@@ -7,15 +7,22 @@ This module implements `top` scoped variables as objects: Each client
 request including all esi include levels (`top`) has its own view of
 topvar variables.
 
-The value of a topvar is the value assigned to it within any esi
-subrequest or a default provided at construction time, if any.
+A topvar can be constructed with a default, which is used as the
+initial value at the beginning of each request at esi level 0.
 
-topvars can be undefined. Attempts to ``.get`` an undefined value will
-return a the ``.get`` method`s `fallback` argument, which in turn may
-have a default for some cases.
+The value of a topvar is the either the default or the last value
+assigned to it within any esi subrequest. If neither a default nor
+previous value was set, then the value is undefined.
+
+A topvar can also be undefined using the ``.undefine()`` method.
+
+Attempts to ``.get()`` an undefined value will return the ``.get()``
+method`s `fallback` argument. For most types, there is a default
+fallback; if there is none, using ``.get()`` on an undefined value
+triggers a VCL failure at runtime.
 
 topvar variables can be protected against write access, in which case
-any attempt to set them triggers a VCL failure at runtime.
+any attempt to ``.set()`` them triggers a VCL failure at runtime.
 
 Example::
 
@@ -51,7 +58,7 @@ $Object type([TYPE init])\n					\
 Construct a(n) TYPE topvar with the default value `init`,\n	\
 if provided. If no `init` value is provided, the variable\n	\
 will be initially undefined.\n					\
-$Method TYPE .get(TYPE fallback DEF_ ## TYPE)\n			\
+$Method TYPE .get([TYPE fallback])\n				\
 Return the value of the topvar or the `fallback` argument\n	\
 if it is undefined. DEFDOC_ ## TYPE\n				\
 $Method VOID .set(TYPE)\n					\