[PATCH] clarify elements of the public VSL API

[Geoff Simmons]

Hello all,

As discussed with Martin today on IRC, this patch just adds some
comments to include/vapi/vsl.h.

vsl.h includes vsl_int.h, and the latter defines some things that are
essential for an API client to do useful work. But vsl.h identifies
itself as the "public API for VSL access", while vsl_int.h says that it
is "NOT!", with capital letters and an exclamation point. And there are
places in vsl_int.h where an API client really shouldn't mess around.

So the idea here is that a client developer can read vsl.h to know
what's safe to use.

@Martin, to draw your attention to some of the details: the comments now
mention VSL_tag_e, SLT__MAX, some of the VSL_* macros, and macros for
using VSL_tagflags.

The VSL_* macros are only for accessing the same fields that were
available in VSL_Dispatch in Varnish <= 3. I'm assuming that a client
doesn't need to know about the rest -- VSL_BATCH*, for example, can be
left out because IIUC VSLQ_Dispatch takes care of all that.

VSL_CDATA is mentioned but not VSL_DATA, the idea being that clients
should use a const char* and not a char* for log payloads. No promises
if you go writing into the SHM log, rather than just read from it.

Please make sure you're comfortable with this, because the implication
will be that clients can rely on these things, so it might be painful to
change them in the future.


Thanks,
Geoff
-- 
** * * UPLEX - Nils Goroll Systemoptimierung

Scheffelstraße 32
22301 Hamburg

Tel +49 40 2880 5731
Mob +49 176 636 90917
Fax +49 40 42949753

http://uplex.de
-------------- next part --------------
A non-text attachment was scrubbed...
Name: clarify-public-VSL-API.patch
Type: text/x-patch
Size: 1943 bytes
Desc: not available
URL: <https://www.varnish-cache.org/lists/pipermail/varnish-dev/attachments/20140330/1401670c/attachment.bin>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 897 bytes
Desc: OpenPGP digital signature
URL: <https://www.varnish-cache.org/lists/pipermail/varnish-dev/attachments/20140330/1401670c/attachment.pgp>