[PATCH] add documentation about backend naming for VMOD authors

[Poul-Henning Kamp]

--------
In message <CABoVN9AW6FcgjVke=mV9F=A97yH6MsucgvKu=FfyqPtPxNnT+g at mail.gmail.com>, Dridi Bouke
lmoune writes:

>If you use the vcl_name of a VMOD object, you have the guarantee that
>this name won't conflict with an existing backend:
>
>**** v1    0.1 CLI RX| Message from VCC-compiler:\n
>**** v1    0.1 CLI RX| Object name 's1' already used.\n
>**** v1    0.1 CLI RX| First usage:\n
>**** v1    0.1 CLI RX| ('input' Line 2 Pos 9)\n
>**** v1    0.1 CLI RX| backend s1 { .host = "127.0.0.1"; .port = "41338"; }\n
>**** v1    0.1 CLI RX| --------##------------------------------------------\n
>**** v1    0.1 CLI RX| \n
>**** v1    0.1 CLI RX| Redefinition:\n
>**** v1    0.1 CLI RX| ('input' Line 8 Pos 21)\n
>**** v1    0.1 CLI RX|                 new s1 = named.director("localhost", "...
>**** v1    0.1 CLI RX| --------------------##--------------------------------

That is almost entirely without relevance to the present discussion.

When you do "new something = vmod.constructor()" you don't get a
backend, you get a VMOD object.

This VMOD object may or may not have a member function which returns
a backend, and depending on how you call it, you may get the same
or different backends each time you call it.

That/those backends has no name in the VCL namespace and thus the
VCC cannot see them.

>Backends can only be named using [0-9a-zA-Z_] so a director creating
>an unknown number of backends (like vmod-named by the way) should
>implement its own suffix starting with an "illegal" character (so that you
>don't accidentally end up with the name of another backend).

And what happens if vmod-named and vmod-ldap just happen to pick
the same "unique" name ?

One of them decides to ignore it, the other panics ?

Nope...

I think Geoff's last email is on the right track:

	Backends can be named or unnamed.

	Only named backends appear in CLI and VSM

	Backends defined in VCL are always named.

	VMOD created backends can be named by calling a VRT function.

	That VRT function will make sure the name is globally unique over CLI/VSM

(I have some questions related to lifetime and cleanup, but we'll tackle those later)

-- 
Poul-Henning Kamp       | UNIX since Zilog Zeus 3.20
phk at FreeBSD.ORG         | TCP/IP since RFC 956
FreeBSD committer       | BSD since 4.3-tahoe    
Never attribute to malice what can adequately be explained by incompetence.