Drop the VSL_{Main|Mgt|Iter}Valid functions.

Let the functions returning counters take an optional fantom pointer,
that can subsequently be used with VSM_StillValid to check for
changes.

Improve the VSC api documentation.

Add missing VSM_StillValid funciton to the .map file.

bin/varnishstat/varnishstat.c

@@ -82,7 +82,7 @@ do_xml(struct VSM_data *vd)
 	now = time(NULL);
 	(void)strftime(time_stamp, 20, "%Y-%m-%dT%H:%M:%S", localtime(&now));
 	printf("<varnishstat timestamp=\"%s\">\n", time_stamp);
-	(void)VSC_Iter(vd, do_xml_cb, NULL);
+	(void)VSC_Iter(vd, NULL, do_xml_cb, NULL);
 	printf("</varnishstat>\n");
 }
 
@@ -143,7 +143,7 @@ do_json(struct VSM_data *vd)
 
 	(void)strftime(time_stamp, 20, "%Y-%m-%dT%H:%M:%S", localtime(&now));
 	printf("\t\"timestamp\": \"%s\",\n", time_stamp);
-	(void)VSC_Iter(vd, do_json_cb, &jp);
+	(void)VSC_Iter(vd, NULL, do_json_cb, &jp);
 	printf("\n}\n");
 	fflush(stdout);
 }
@@ -196,7 +196,7 @@ do_once(struct VSM_data *vd, const struct VSC_C_main *VSC_C_main)
 		op.up = VSC_C_main->uptime;
 	op.pad = 18;
 
-	(void)VSC_Iter(vd, do_once_cb, &op);
+	(void)VSC_Iter(vd, NULL, do_once_cb, &op);
 }
 
 /*--------------------------------------------------------------------*/
@@ -228,7 +228,7 @@ list_fields(struct VSM_data *vd)
 	fprintf(stderr, "Field name                     Description\n");
 	fprintf(stderr, "----------                     -----------\n");
 
-	(void)VSC_Iter(vd, do_list_cb, NULL);
+	(void)VSC_Iter(vd, NULL, do_list_cb, NULL);
 }
 
 /*--------------------------------------------------------------------*/
@@ -315,7 +315,7 @@ main(int argc, char * const *argv)
 		else if (json)
 			do_json(vd);
 		else if (once)
-			do_once(vd, VSC_Main(vd));
+			do_once(vd, VSC_Main(vd, NULL));
 		else {
 			assert(0);
 		}

bin/varnishstat/varnishstat_curses.c

@@ -318,7 +318,7 @@ build_pt_list_cb(void *priv, const struct VSC_point *vpt)
 }
 
 static void
-build_pt_list(struct VSM_data *vd)
+build_pt_list(struct VSM_data *vd, struct VSM_fantom *fantom)
 {
 	struct pt_priv pt_priv;
 	int i;
@@ -334,7 +334,7 @@ build_pt_list(struct VSM_data *vd)
 	VTAILQ_INIT(&pt_priv.ptlist);
 	pt_priv.n_ptlist = 0;
 
-	(void)VSC_Iter(vd, build_pt_list_cb, &pt_priv);
+	(void)VSC_Iter(vd, fantom, build_pt_list_cb, &pt_priv);
 	delete_pt_list();
 	AN(VTAILQ_EMPTY(&ptlist));
 	AZ(n_ptlist);
@@ -841,6 +841,7 @@ do_curses(struct VSM_data *vd, int delay)
 	long timeout;
 	int ch;
 	double now;
+	struct VSM_fantom f_main, f_mgt, f_iter;
 
 	AN(freopen("errlog", "w", stderr));
 	setbuf(stderr, NULL);
@@ -859,8 +860,8 @@ do_curses(struct VSM_data *vd, int delay)
 	make_windows();
 	doupdate();
 
-	VSC_C_mgt = VSC_Mgt(vd);
-	VSC_C_main = VSC_Main(vd);
+	VSC_C_mgt = VSC_Mgt(vd, &f_mgt);
+	VSC_C_main = VSC_Main(vd, &f_main);
 	while (keep_running) {
 		if (VSM_Abandoned(vd)) {
 			fprintf(stderr, "abandoned\n");
@@ -870,13 +871,10 @@ do_curses(struct VSM_data *vd, int delay)
 				fprintf(stderr, "VSM_Open failed: %s\n",
 				    VSM_Error(vd));
 		}
-		VSC_C_mgt = VSC_Mgt(vd);
-		VSC_C_main = VSC_Main(vd);
-		if (!VSC_IterValid(vd)) {
-			fprintf(stderr, "iter not valid\n");
-			build_pt_list(vd);
-		} else
-			fprintf(stderr, "iter valid\n");
+		VSC_C_mgt = VSC_Mgt(vd, &f_mgt);
+		VSC_C_main = VSC_Main(vd, &f_main);
+		if (VSM_StillValid(vd, &f_iter) != 1)
+			build_pt_list(vd, &f_iter);
 
 		now = VTIM_mono();
 		if (now - t_sample > interval)

bin/varnishtest/vtc_varnish.c

@@ -774,7 +774,7 @@ varnish_expect(const struct varnish *v, char * const *av) {
 		if (good < 0)
 			continue;
 
-		good = VSC_Iter(v->vd, do_stat_cb, &sp);
+		good = VSC_Iter(v->vd, NULL, do_stat_cb, &sp);
 		if (!good) {
 			good = -2;
 			continue;

include/vapi/vsc.h

@@ -59,16 +59,61 @@ int VSC_Arg(struct VSM_data *vd, int arg, const char *opt);
 	 *	 1 Handled.
 	 */
 
-struct VSC_C_mgt *VSC_Mgt(struct VSM_data *vd);
+struct VSC_C_mgt *VSC_Mgt(struct VSM_data *vd, struct VSM_fantom *fantom);
 	/*
-	 * return Management stats structure
-	 * returns NULL until management process has finished initialization.
+	 * 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 VSC_C_main *VSC_Main(struct VSM_data *vd, struct VSM_fantom *fantom);
 	/*
-	 * return Main stats structure
-	 * returns NULL until child has been started.
+	 * 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.
+	 *
+	 * 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
+	 */
+
+void *VSC_Get(struct VSM_data *vd, struct VSM_fantom *fantom, const char *type,
+    const char *ident);
+	/*
+	 * Looks up the given VSC type and identifier. If fantom is
+	 * non-NULL, it can if successful later be used with
+	 * VSM_StillValid.
+	 *
+	 * Arguments:
+	 *	vd:	The VSM_data context
+	 *	fantom: Pointer to a fantom. Can be NULL.
+	 *	type:	The type of the counter segment
+	 *	ident:	The identifier of the counter segment
+	 *
+	 * Return values:
+	 *  NULL:	Failure
+	 *  non-NULL:	A void pointer to the stats structure.
 	 */
 
 struct VSC_level_desc;
@@ -114,51 +159,36 @@ struct VSC_point {
 
 typedef int VSC_iter_f(void *priv, const struct VSC_point *const pt);
 
-int VSC_Iter(struct VSM_data *vd, VSC_iter_f *func, void *priv);
+int VSC_Iter(struct VSM_data *vd, struct VSM_fantom *fantom, VSC_iter_f *func,
+    void *priv);
 	/*
 	 * Iterate over all statistics counters, calling "func" for
 	 * each counter not suppressed by any "-f" arguments.
 	 *
+	 * fantom points to a struct VSM_fantom. If non-NULL, it can be
+	 * used with VSM_StillValid to check the validity of the points
+	 * returned.
+	 *
+	 * The returned points are valid for at most 60 seconds after
+	 * VSM_StillValid(,fantom) starts returning anything but
+	 * VSM_valid, or until the next call to VSC_Iter. Using the point
+	 * values after any of these events gives undefined behavior.
+	 *
 	 * Func is called with pt == NULL, whenever VSM allocations
 	 * change (child restart, allocations/deallocations)
 	 *
+	 * Arguments:
+	 *	    vd: The VSM_data context
+	 *	fantom: Pointer to a fantom. Can be NULL.
+	 *	  func: The callback function
+	 *	  priv: Passed as argument to func
+	 *
 	 * Returns:
 	 *	!=0:	func returned non-zero
 	 *	-1:	No VSC's available
 	 *	0:	Done
 	 */
 
-int VSC_MgtValid(struct VSM_data *vd);
-	/*
-	 * Call VSM_StillValid on the fantom used to find the management
-	 * counters
-	 *
-	 * Returns:
-	 *	0: fantom is not valid any more
-	 *	1: fantom is still the same.
-	 *	2: a fantom with same dimensions exist.
-	 */
-
-int VSC_MainValid(struct VSM_data *vd);
-	/*
-	 * Call VSM_StillValid on the fantom used to find the main counters.
-	 *
-	 * Returns:
-	 *	0: fantom is not valid any more
-	 *	1: fantom is still the same.
-	 *	2: a fantom with same dimensions exist.
-	 */
-
-int VSC_IterValid(struct VSM_data *vd);
-	/*
-	 * Call VSM_StillValid on the fantom used to produce the last
-	 * VSC_Iter results.
-	 *
-	 * Returns:
-	 *	0: fantom is not valid any more
-	 *	1: fantom is still the same.
-	 */
-
 const struct VSC_level_desc *VSC_LevelDesc(unsigned level);
 
 /**********************************************************************

lib/libvarnishapi/libvarnishapi.map

@@ -90,10 +90,8 @@ LIBVARNISHAPI_1.3 {
 	# Functions:
 	VSM_Abandoned;
 	VSM_ResetError;
+	VSM_StillValid;
 	VSC_Mgt;
-	VSC_MgtValid;
-	VSC_MainValid;
-	VSC_IterValid;
 	VSC_LevelDesc;
 	VSL_New;
 	VSL_Delete;

lib/libvarnishapi/vsc.c

@@ -92,8 +92,6 @@ struct vsc {
 	VTAILQ_HEAD(, vsc_vf)	vf_list;
 	VTAILQ_HEAD(, vsc_pt)	pt_list;
 	VTAILQ_HEAD(, vsc_sf)	sf_list;
-	struct VSM_fantom	mgt_fantom;
-	struct VSM_fantom	main_fantom;
 	struct VSM_fantom	iter_fantom;
 };
 
@@ -263,32 +261,40 @@ VSC_Arg(struct VSM_data *vd, int arg, const char *opt)
 /*--------------------------------------------------------------------*/
 
 struct VSC_C_mgt *
-VSC_Mgt(struct VSM_data *vd)
+VSC_Mgt(struct VSM_data *vd, struct VSM_fantom *fantom)
 {
-	struct vsc *vsc = vsc_setup(vd);
 
-	if (!VSM_StillValid(vd, &vsc->mgt_fantom) &&
-	    !VSM_Get(vd, &vsc->mgt_fantom, VSC_CLASS, VSC_type_mgt, ""))
-		return (NULL);
-	return ((void*)vsc->mgt_fantom.b);
+	return (VSC_Get(vd, fantom, VSC_type_mgt, ""));
 }
 
 /*--------------------------------------------------------------------*/
 
 struct VSC_C_main *
-VSC_Main(struct VSM_data *vd)
+VSC_Main(struct VSM_data *vd, struct VSM_fantom *fantom)
 {
-	struct vsc *vsc = vsc_setup(vd);
 
-	if (!VSM_StillValid(vd, &vsc->main_fantom) &&
-	    !VSM_Get(vd, &vsc->main_fantom, VSC_CLASS, VSC_type_main, ""))
-		return (NULL);
-	return ((void*)vsc->main_fantom.b);
+	return (VSC_Get(vd, fantom, VSC_type_main, ""));
 }
 
 /*--------------------------------------------------------------------
  */
 
+void *
+VSC_Get(struct VSM_data *vd, struct VSM_fantom *fantom, const char *type,
+    const char *ident)
+{
+	struct VSM_fantom f2;
+
+	if (fantom == NULL)
+		fantom = &f2;
+	if (!VSM_StillValid(vd, fantom) &&
+	    !VSM_Get(vd, fantom, VSC_CLASS, type, ident))
+		return (NULL);
+	return ((void*)fantom->b);
+}
+
+/*--------------------------------------------------------------------*/
+
 static void
 vsc_add_vf(struct vsc *vsc, const struct VSM_fantom *fantom,
     const struct VSC_type_desc *desc, int order)
@@ -457,7 +463,8 @@ vsc_filter_pt_list(struct VSM_data *vd)
  */
 
 int
-VSC_Iter(struct VSM_data *vd, VSC_iter_f *func, void *priv)
+VSC_Iter(struct VSM_data *vd, struct VSM_fantom *fantom, VSC_iter_f *func,
+    void *priv)
 {
 	struct vsc *vsc = vsc_setup(vd);
 	struct vsc_pt *pt;
@@ -470,6 +477,8 @@ VSC_Iter(struct VSM_data *vd, VSC_iter_f *func, void *priv)
 		vsc_build_pt_list(vd);
 		vsc_filter_pt_list(vd);
 	}
+	if (fantom != NULL)
+		*fantom = vsc->iter_fantom;
 	VTAILQ_FOREACH(pt, &vsc->pt_list, list) {
 		i = func(priv, &pt->point);
 		if (i)
@@ -481,44 +490,6 @@ VSC_Iter(struct VSM_data *vd, VSC_iter_f *func, void *priv)
 /*--------------------------------------------------------------------
  */
 
-int
-VSC_MgtValid(struct VSM_data *vd)
-{
-	struct vsc *vsc = vsc_setup(vd);
-	fprintf(stderr, "VSC_MgtValid called priv=%ju\n",
-		vsc->mgt_fantom.priv);
-	return (VSM_StillValid(vd, &vsc->mgt_fantom));
-}
-
-int
-VSC_MainValid(struct VSM_data *vd)
-{
-	struct vsc *vsc = vsc_setup(vd);
-	fprintf(stderr, "VSC_MainValid called priv=%ju\n",
-		vsc->main_fantom.priv);
-	return (VSM_StillValid(vd, &vsc->main_fantom));
-}
-
-int
-VSC_IterValid(struct VSM_data *vd)
-{
-	struct vsc *vsc = vsc_setup(vd);
-	int v;
-	fprintf(stderr, "VSC_IterValid called priv=%ju\n",
-		vsc->iter_fantom.priv);
-	v = VSM_StillValid(vd, &vsc->iter_fantom);
-	if (v == 2) {
-		/* There's been changes, reiteration needed. Clear fantom
-		   so subsequent calls will also fail */
-		memset(&vsc->iter_fantom, 0, sizeof vsc->iter_fantom);
-		v = 0;
-	}
-	fprintf(stderr, "VSC_IterValid returns %d priv=%ju\n", v,
-		vsc->iter_fantom.priv);
-
-	return (v);
-}
-
 const struct VSC_level_desc *
 VSC_LevelDesc(unsigned level)
 {