From 7bccded24df0efd9200f44be111b8eacd486e5de Mon Sep 17 00:00:00 2001
From: Nils Goroll <nils.goroll@uplex.de>
Date: Tue, 21 May 2024 14:27:03 +0200
Subject: [PATCH] Document a pitfall with ObjWaitExtend()

Maybe it should gain a boc_state_e * argument to return a consistent
state value?
---
 bin/varnishd/storage/storage_simple.c | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/bin/varnishd/storage/storage_simple.c b/bin/varnishd/storage/storage_simple.c
index ba658a8f7e4..6626d3a0d6c 100644
--- a/bin/varnishd/storage/storage_simple.c
+++ b/bin/varnishd/storage/storage_simple.c
@@ -368,6 +368,13 @@ sml_iterator(struct worker *wrk, struct objcore *oc,
 			break;
 		}
 		if (nl == ol) {
+			/*
+			 * note: the unguarded boc->state read could be
+			 * outdated, in which case we call ObjWaitExtend() again
+			 * for error handling but otherwise cause no harm. When
+			 * using this code as an example, DO NOT rely on
+			 * boc->state to be consistent
+			 */
 			if (boc->state == BOS_FINISHED)
 				break;
 			continue;