Document VSC api

git-svn-id: http://www.varnish-cache.org/svn/trunk/varnish-cache@4938 d4fa192b-c00b-0410-8231-f00ffab90ce4

include/varnishapi.h

@@ -113,23 +113,58 @@ struct vsm_head *VSM_Head(struct VSM_data *vd);
 
 void *VSM_Find_Chunk(struct VSM_data *vd, const char *class, const char *type,
     const char *ident, unsigned *lenp);
+	/*
+	 * Find a given chunk in the shared memory.
+	 * Returns pointer or NULL.
+	 * Lenp, if non-NULL, is set to length of chunk.
+	 */
+
 void VSM_Close(struct VSM_data *vd);
+	/*
+	 * Unmap shared memory
+	 * Deallocate all storage (including VSC and VSL allocations)
+	 */
 
 struct vsm_chunk *vsm_iter0(const struct VSM_data *vd);
 void vsm_itern(const struct VSM_data *vd, struct vsm_chunk **pp);
 
 #define VSM_FOREACH(var, vd) \
-	for((var) = vsm_iter0((vd)); (var) != NULL; vsm_itern((vd), &(var)))
+    for((var) = vsm_iter0((vd)); (var) != NULL; vsm_itern((vd), &(var)))
+
+	/*
+	 * Iterate over all chunks in shared memory
+	 * var = "struct vsm_chunk *"
+	 * vd = "struct VSM_data"
+	 */
 
 /*---------------------------------------------------------------------
  * VSC level access functions
  */
 
 void VSC_Setup(struct VSM_data *vd);
+	/*
+	 * Setup vd for use with VSC functions.
+	 */
+
 int VSC_Arg(struct VSM_data *vd, int arg, const char *opt);
+	/*
+	 * Handle standard stat-presenter arguments 
+	 * Return:
+	 *	-1 error
+	 *	 0 not handled
+	 *	 1 Handled.
+	 */
+
 int VSC_Open(struct VSM_data *vd, int diag);
+	/*
+	 * Open shared memory for VSC processing.
+	 * args and returns as VSM_Open()
+	 */
 
 struct vsc_main *VSC_Main(struct VSM_data *vd);
+	/*
+	 * return Main stats structure
+	 */
 
 struct vsc_point {
 	const char *class;		/* stat struct type		*/
@@ -144,6 +179,10 @@ struct vsc_point {
 typedef int vsc_iter_f(void *priv, const struct vsc_point *const pt);
 
 int VSC_Iter(const struct VSM_data *vd, vsc_iter_f *func, void *priv);
+	/*
+	 * Iterate over all statistics counters, calling "func" for
+	 * each counter not suppressed by any "-f" arguments.
+	 */
 
 /*---------------------------------------------------------------------
  * VSL level access functions

lib/libvarnishapi/vsc.c

@@ -35,7 +35,6 @@ SVNID("$Id$")
 #include <sys/types.h>
 #include <sys/stat.h>
 #include <string.h>
-#include <stdio.h>
 #include <stdlib.h>
 
 #include "vas.h"
@@ -107,12 +106,15 @@ vsc_delete(struct VSM_data *vd)
 /*--------------------------------------------------------------------*/
 
 static int
-vsc_sf_arg(struct vsc *vsc, const char *opt)
+vsc_sf_arg(struct VSM_data *vd, const char *opt)
 {
+	struct vsc *vsc;
 	struct vsc_sf *sf;
 	char **av, *q, *p;
 	int i;
 
+	CHECK_OBJ_NOTNULL(vd, VSM_MAGIC);
+	vsc = vd->vsc;
 	CHECK_OBJ_NOTNULL(vsc, VSC_MAGIC);
 
 	if (VTAILQ_EMPTY(&vsc->sf_list)) {
@@ -123,8 +125,8 @@ vsc_sf_arg(struct vsc *vsc, const char *opt)
 	av = ParseArgv(opt, ARGV_COMMA);
 	AN(av);
 	if (av[0] != NULL) {
-		fprintf(stderr, "Parse error: %s", av[0]);
-		exit (1);
+		vd->diag(vd->priv, "Parse error: %s", av[0]);
+		return (-1);
 	}
 	for (i = 1; av[i] != NULL; i++) {
 		ALLOC_OBJ(sf, VSL_SF_MAGIC);
@@ -189,13 +191,11 @@ vsc_sf_arg(struct vsc *vsc, const char *opt)
 int
 VSC_Arg(struct VSM_data *vd, int arg, const char *opt)
 {
-	struct vsc *vsc;
 
 	CHECK_OBJ_NOTNULL(vd, VSM_MAGIC);
-	vsc = vd->vsc;
-	CHECK_OBJ_NOTNULL(vsc, VSC_MAGIC);
+	AN(vd->vsc);
 	switch (arg) {
-	case 'f': return (vsc_sf_arg(vsc, opt));
+	case 'f': return (vsc_sf_arg(vd, opt));
 	case 'n': return (VSM_n_Arg(vd, opt));
 	default:
 		return (0);