[master] ba19e06 Documentation updates
Martin Blix Grydeland
martin at varnish-cache.org
Wed May 15 14:46:15 CEST 2013
commit ba19e06a10f95672415905627f813c0a26ddbae1
Author: Martin Blix Grydeland <martin at varnish-software.com>
Date: Wed May 15 14:41:16 2013 +0200
Documentation updates
diff --git a/include/vapi/vsc.h b/include/vapi/vsc.h
index 550ca55..e77ef64 100644
--- a/include/vapi/vsc.h
+++ b/include/vapi/vsc.h
@@ -60,30 +60,12 @@ int VSC_Arg(struct VSM_data *vd, int arg, const char *opt);
*/
struct VSC_C_mgt *VSC_Mgt(struct VSM_data *vd, struct VSM_fantom *fantom);
- /*
- * Looks up and returns the management stats structure. If fantom
- * is non-NULL, it can if successful later be used with
- * VSM_StillValid. Returns NULL until the management process has
- * finished initialization.
- *
- * The returned structure is valid for at most 60 seconds after
- * VSM_StillValid(,fantom) starts returning VSM_invalid. Using the
- * pointer after this event gives undefined behavior.
- *
- * Arguments:
- * vd: The VSM_data context
- * fantom: Pointer to a fantom. Can be NULL.
- *
- * Return values:
- * NULL: Failure
- * non-NULL: Success
- */
-
struct VSC_C_main *VSC_Main(struct VSM_data *vd, struct VSM_fantom *fantom);
/*
- * Looks up and returns the main stats structure. If fantom is
- * non-NULL, it can if successful later be used with
- * VSM_StillValid. Returns NULL until child has been started.
+ * Looks up and returns the management stats and the child main
+ * stats structure. If fantom is non-NULL, it can later be used
+ * with VSM_StillValid. Returns NULL until the management process
+ * has finished initialization or the child has been started.
*
* The returned structure is valid for at most 60 seconds after
* VSM_StillValid(,fantom) starts returning VSM_invalid. Using the
diff --git a/include/vapi/vsm.h b/include/vapi/vsm.h
index 42d6e8d..aa58835 100644
--- a/include/vapi/vsm.h
+++ b/include/vapi/vsm.h
@@ -151,9 +151,28 @@ enum VSM_valid_e {
enum VSM_valid_e VSM_StillValid(const struct VSM_data *vd,
struct VSM_fantom *vf);
/*
- * This is a cheap syscall-less check to see if the fantom is still
- * valid. Further checking with VSM_Abandoned() may be a good
- * idea.
+ * Check the validity of a previously looked up VSM_fantom.
+ *
+ * VSM_invalid means that the SHM chunk this fantom points to does
+ * not exist in the log file any longer. Using the fantom's
+ * pointer gives undefined results. Further checking with
+ * VSM_Abandoned() may be a good idea.
+ *
+ * VSM_valid means that the SHM structure has not changed since
+ * the fantom was looked up or since the last call to
+ * VSM_StillValid().
+ *
+ * VSM_similar means that the SHM structure has changed, but there
+ * is still a valid chunk present with the same the same type and
+ * identifier. The fantom's pointers and dimensions haven't
+ * changed. The next call to VSM_StillValid() on this fantom will
+ * return VSM_valid.
+ *
+ * Applications using the fantom to monitor a single chunk can
+ * treat VSM_similar as equal to VSM_valid. Applications using a
+ * fantom to monitor the SHM file for new or removed chunks,
+ * should reiterate over the chunks on VSM_similar as the
+ * structure has changed.
*
* Return:
* VSM_invalid: fantom is not valid any more.
More information about the varnish-commit
mailing list