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
From 7af9af36f3c10810a8218888ab71ae4d1096e721 Mon Sep 17 00:00:00 2001 From: Geoff Simmons <[email protected]> Date: Sun, 30 Mar 2014 14:43:16 +0200 Subject: [PATCH 1/1] clarify elements of the public VSL API --- include/vapi/vsl.h | 37 +++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) diff --git a/include/vapi/vsl.h b/include/vapi/vsl.h index d9a513c..a6e0839 100644 --- a/include/vapi/vsl.h +++ b/include/vapi/vsl.h @@ -39,6 +39,13 @@ #include "vapi/vsm.h" #include "vapi/vsl_int.h" +/* + * enum VSL_tag_e enumerates the SHM log tags, where the identifiers are + * "SLT_" + XML tag, as defined in tbl/vsl_tags.h. Use the macro SLT__MAX + * for the highest possible value of the enum. + * (VSL_tag_e and SLT__MAX included from vsl_int.h) + */ + struct VSL_data; struct VSLQ; @@ -46,6 +53,28 @@ struct VSLC_ptr { const uint32_t *ptr; /* Record pointer */ unsigned priv; }; + /* + * Use these macros to access fields of a VSLC_ptr record + * (included from vsl_int.h): + * + * VSL_TAG(ptr) + * SLT tag (enum VSL_tag_e) + * + * VSL_ID(ptr) + * VXID + * + * VSL_CDATA(ptr) + * Payload (as const char *) + * + * VSL_LEN(ptr) + * Length of the payload in bytes + * + * VSL_CLIENT(ptr) + * Non-zero if this is a client transaction + * + * VSL_BACKEND(ptr) + * Non-zero if this is a backend transaction + */ struct VSL_cursor { /* The record this cursor points to */ @@ -127,6 +156,14 @@ extern const char * const VSL_tags[SLT__MAX]; extern const unsigned VSL_tagflags[SLT__MAX]; /* * Tag flags array. + * Use these macros with VSL_tagflags (included from vsl_int.h): + * + * VSL_tagflags[tag] & SLT_F_BINARY + * Non-zero if the payload with this tag may include + * non-printable characters + * + * VSL_tagflags[tag] & SLT_F_UNUSED + * Non-zero if this tag is reserved for future use */ int VSL_Name2Tag(const char *name, int l); -- 1.7.10.4
signature.asc
Description: OpenPGP digital signature
_______________________________________________ varnish-dev mailing list [email protected] https://www.varnish-cache.org/lists/mailman/listinfo/varnish-dev
