... and minor touch up of the file.

No, this does not imply me checking all our RST files for adherence with
this standard.

Ref 0d663a5e

The [be]req.task_deadline should eventually be generalized to all
subroutines with read-write access to [be]req. When that happens,
bereq.task_deadline will inherit req.task_deadline during the pipe
transition.

Related tasks should otherwise have independent deadlines, except
sub-request tasks like ESI where there is a hierarchical dependency.

This takes care of documenting the meaning of a zero timeout value in
a central location, since none of the timeout parameters have a mention
for the effect it produces.

This is written as if there was a separate varnish-param(7) manual,
which should eventually be enacted. This manual extraction was initially
implemented in the adjacent #3817 timeout nomenclature draft.

in VRT_AddDirector, we create the new vcldir with an initial
reference, which we need to drop if we can not add it.

Compare:

	VRT_AddDirector()
		...
		vdir->refcnt++;

	vcldir_free()
		...
		AZ(vdir->refcnt);

Noticed when testing other experimental changes while working on
https://github.com/nigoroll/libvmod-dynamic/issues/110

 #5  0x000055820c8cb845 in VAS_Fail (func=0x55820c904559 "vcldir_free", file=0x55820c903a47 "cache/cache_vrt_vcl.c",
     line=150, cond=0x55820c90459a "(vdir->refcnt) == 0", kind=VAS_ASSERT) at vas.c:67
 #6  0x000055820c83a442 in vcldir_free (vdir=0x7f662aa53140) at cache/cache_vrt_vcl.c:150
 #7  0x000055820c839fe1 in VRT_AddDirector (ctx=0x7f662befe250, m=0x55820c965260 <vbe_methods_noprobe>,
     priv=0x7f662aa20780, fmt=0x55820c900f7f "%s") at cache/cache_vrt_vcl.c:219
 #8  0x000055820c7c7c4d in VRT_new_backend_clustered (ctx=0x7f662befe250, vc=0x0, vrt=0x7f662befdd10, via=0x0)
    at cache/cache_backend.c:737
 #9  0x000055820c7c8632 in VRT_new_backend (ctx=0x7f662befe250, vrt=0x7f662befdd10, via=0x0)
     at cache/cache_backend.c:755

Motivated by #4042

So the n_expired, n_purges and n_obj_purged counters should reflect
that. Likewise, it shouldn't be logged as "EXP_Expired".

And while at it document it.

It is generally useful to know when an object leaves the cache and while
it may sometimes be logged by call sites (like bans) it is more helpful
centralize it in ExpKill records to get a (more) complete view of what
goes in and out of (durable) storage.

The hits attribute is especially useful, as it can give an indication of
the popularity of objects being removed before they expire.

This makes it easier to estimate the popularity of expired objects.

vcldir_retire() only sends a VCL_EVENT_COLD when the vcl is warm. In
other words, it (rightly) asserts that a COLD event (if any) has
alrady been posted when a director is deleted on a COLD vcl.

Yet, when the director is deleted upon a COLD vmod event, this assertion
was wrong, because the COLD events for directors were only posted after
vmod events.

Given that vmods do things like deleting directors, it appears (more)
correct to post VDI COLD events before VMOD COLD events.

https://github.com/vtest/VTest/pull/32

This should be a no-op on all contemporary UNIX implementations, but
let's see what vtest tells us...

It's amazing how long time it takes to find a delay of half a second...

or rather, has been for some time now.

and document the default of the other methods.

Ref #4036

There is a default value when the property is not implemented and has no
callback.

Fixes #4036

of 08350519

Rawhide is not stable and we already have a job for the latest stable
branch.

The objiterate_f interface requires that OBJ_ITER_END be sent,
preferrably with the last chunk of data, but at least after it.

It was not documented explicitly anywhere, but the len/wsl argument to
STV_NewObject() is the amount of space to allocate for all
OBJ_VARATTRs combined which are going to be written to this
object. For now, these are OA_HEADERS and OA_VARY only (see
include/tbl/obj_attr.h).

So for one, there is no reason to force this argument be greater than
zero when we know that no OBJ_VARATTRs are going to be set.

Secondly, this might actually represent a minor shortcoming of the
stevedore API, because the amount of space which a stevedore
implementation actually needs might be larger than what the simple
stevedores use. So for now, the semantics of this argument are, more
specifically, "the equivalent of space for OBJ_VARATTRs as for simple
storage". In practice, this probably does not matter much...

But even before this clarification, the API was not used consistently:

For the call from vrb_pull(), the maximum request body size (to cache)
was used as the wsl argument, yet it has nothing to do with the object
body size, it specifies the amount of space to allocate for variable
sized object attributes (see above).

For the call from cnt_synth(), a somehow arbitrary value of 1KB was
used.

In both cases, the amount of space actually required is zero, because
the only attribute used on the objects created is OA_LEN, which is
fixed and thus always present.