VRT_delete_backend() sets be->cooled to non-zero as the only place where
that is done. Assert that it is zero on entry as a check that
VRT_delete_backend isn't called multiple times.

Several functions (VBE_Poll and vbe_destroy) tests be->cooled == 0 to
determine which of the two lists backends and cool_backends a specific
instance currently lives on. If the flag is in the process of being
changed, then the wrong list head may be used and will result in strange
bugs.

We don't need randomness where we could have determinism.

Except in r02275.vtc until the code it refers to stops referring to
subroutines as methods. While I was searching for relevant tests cases
I also broke some long lines.

Refs 17457b48

Refs 17457b48

While, in most of the code, we now use SA_*_ADDR and format the
address/port when needed, for the client ip and port, there still exist
formatted strings as session attributes.

I recently came across this in a different context and wondered if we
should remove these string session attributes, but as we use them multiple
times for each request, that would only imply additional overhead for
repeated string formatting.  So I think we should keep them for now,
but we might want to consider to add to struct suckaddr optional
formatted strings to avoid the duplicated formatting which already
happens.

This commit adds a regression test.

Motivated by #3173

Martin entrusted me with those changes after I pointed out that [core]
was not a great prefix considering that VSL records already have the
notion of a prefix.

I opted for:

- an actionable "vsl:" prefix for core notice messages
- a prefix naming scheme mapping to manual pages

As a result I changed the documentation a bit.

Better diff with --word-diff --ignore-all-space options.

Log a notice message when delaying a conditional fetch and the stale
template object is still streaming.

This VSL tag will be used for informational messages related to
exceptional handling of requests.

Wait for the stale object to become fully fetched, so that we can catch
fetch errors, before we unbusy the new object. This serves two
purposes. First it helps with request coalescing, and stops long chains of
IMS-updated short-TTL objects all streaming from a single slow body
fetch. Second it makes sure that all the object attributes are complete
when we copy them (this would be an issue for ie OA_GZIPBITS).

This patch OBE's r01646.vtc, and slightly patches r01648.vtc to expect a
503 instead of a 200 and a broken connection on the failing client.

Fixes: #3089

The code base and documentation refer to ``sub`` symbols as:

- subroutines
- functions
- methods
- procedures
- callbacks

This change focuses on always referring to them as subroutines in the
documentation. During this documentation sweep, there were a lot of
false positives since VCL, VMODs and HTTP also share that vocabulary
and I may have missed false negatives, especially for generated bits
of documentation.

Some parts of the documentation were not touched on purpose: upgrade
notes and changelogs of past releases, PHK random outbursts, etc.

Now that the documentation is hopefully taken care of the same needs
to happen in the code base, starting with user-facing error messages
and then data structures names, function names etc.

There will be however one exception. Anything referring to the scope
of a subroutine, but being worded as if it referred to the subroutine
itself will use scope instead.

As this will touch a lot of code, it will be done incrementally, much
like this change focused on non-generated documentation (and VCC files
don't count as generated in this context).

I also fixed RST formatting issues I noticed during my sweep.

Better diff with the --word-diff --ignore-all-space options.

as promised in #3161

Notice: The boolean expression does not lack parantheses, the test for
generate.py is only to be and'ed with the test for .git

Fixes #3165

Before:

    ...called from "foo"
    ('<vcl.inline>' Line 5 Pos 27)
            sub bar { call foo; }
    --------------------------#--

After:

    ...called from "bar"
    ('<vcl.inline>' Line 5 Pos 24)
            sub bar { call foo; }
    -----------------------###---

This fixes the "called from" part of the message to refer to the caller
instead of the callee, and underlines the symbol token instead of the
semi-colon.

We had two places where we documented common actions, and one of them
was outdated.

...even after ~11 years of experience with varnish.

today: return without an action from a custom subroutine.

it is not before we have parsed parameters

Fixes #3160

Spotted via vtest: l1 timed out despite varnishd logging what was
expected next. This is tightening l1's expectation in the hope that
r2339 will no longer flake.

I wasn't able to reproduce this even on my vtest box where it failed.

we already check for unused subs in vcc_checkref()

Fixes #3159

$ nslookup dns-canary.freebsd.dk

Non-authoritative answer:
*** Can't find dns-canary.freebsd.dk: No answer

if anyone has a more reliable server to test, please just change it
again.

Ref #2575