A lot of commenting and some minor cleanups

bin/varnishd/cache/cache_obj.c

@@ -25,18 +25,60 @@
  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  * SUCH DAMAGE.
  *
- * Primary API:
- *	ObjNew		Associate stevedore with oc
- *	ObjGetSpace	Add space
- *	ObjExtend	Commit space
- *	ObjDone		Object completed
- *	ObjGetLen	Len of committed space
- *	ObjIterate	Iterate over committed space
- *	ObjReserveAttr	Attr will be set later
- *	ObjSetAttr	Set attr now
- *	ObjGetAttr	Get attr no
- *	ObjRelease	Done with attr ptr
- *	ObjTouch	Object was used
+ * Lifetime of an objcore:
+ *	phase 0	- nonexistent
+ *	phase 1	- created, but no stevedore associated
+ *	phase 2	- stevedore associated, being filled out
+ *	phase 3	- stable, no changes happening
+ *	phase 4	- unavailable, being dismantled
+ *	phase 5	- stevedore disassociated
+ *	phase 6	- nonexistent
+ *
+ * 0->1	ObjNew()	creates objcore
+ *
+ * 1->2	STV_NewObject()	associates a stevedore
+ *
+ * 2	ObjSetState()	sets state
+ * 2	ObjWaitState()	waits for particular state
+ *			INVALID->REQ_DONE->STREAM->FINISHED->FAILED
+ *
+ * 2	ObjGetSpace()	allocates space
+ * 2	ObjExtend()	commits content
+ * 2	ObjWaitExtend()	waits for content - used to implement ObjIterate())
+ * 2	ObjTrimStore()	signals end of content addition
+ *
+ * 2	ObjSetAttr()
+ * 2	  ObjCopyAttr()
+ * 2	  ObjSetFlag()
+ * 2	  ObjSetDouble()
+ * 2	  ObjSetU32()
+ * 2	  ObjSetU64()
+ *
+ * 2->3	ObjStable()	Will no longer be modified
+ *
+ * 23	ObjHasAttr()
+ * 23	ObjGetAttr()
+ * 23	  ObjCheckFlag()
+ * 23	  ObjGetDouble()
+ * 23	  ObjGetU32()
+ * 23	  ObjGetU64()
+ * 23	  ObjGetLen()
+ * 23	  ObjGetXID()
+ *
+ * 23	ObjIterate()	... over body
+ *
+ * 23	ObjTouch()	Signal to LRU(-like) facilities
+ *
+ * 23	ObjUpdateMeta()	ban/ttl/grace/keep changed
+ *
+ * 3->4	ObjSnipe()	kill if not in use
+ * 3->4	ObjKill()	make unavailable
+ *
+ * 234	ObjSlim()	Release body storage (but retain attribute storage)
+ *
+ * 4->5	ObjFreeObj()	disassociates stevedore
+ *
+ * 5->6 FREE_OBJ()	...in HSH_DerefObjCore()
  */
 
 #include "config.h"

bin/varnishd/storage/mgt_stevedore.c

@@ -186,7 +186,6 @@ STV_Config(const char *spec)
 	AN(stv->methods);
 
 	if (!strcmp(stv->ident, TRANSIENT_STORAGE)) {
-		stv->transient = 1;
 		AZ(stv_transient);
 		stv_transient = stv;
 	} else {

bin/varnishd/storage/storage.h

@@ -68,9 +68,9 @@ typedef int storage_baninfo_f(const struct stevedore *, enum baninfo event,
 typedef void storage_banexport_f(const struct stevedore *, const uint8_t *bans,
     unsigned len);
 
-typedef struct object *storage_getobj_f(struct worker *, struct objcore *);
-typedef struct storage *storage_alloc_f(const struct stevedore *, size_t size);
-typedef void storage_free_f(struct storage *);
+typedef struct object *sml_getobj_f(struct worker *, struct objcore *);
+typedef struct storage *sml_alloc_f(const struct stevedore *, size_t size);
+typedef void sml_free_f(struct storage *);
 
 /* Prototypes for VCL variable responders */
 #define VRTSTVTYPE(ct) typedef ct storage_var_##ct(const struct stevedore *);
@@ -83,22 +83,28 @@ struct stevedore {
 	unsigned		magic;
 #define STEVEDORE_MAGIC		0x4baf43db
 	const char		*name;
-	unsigned		transient;
-	storage_init_f		*init;		/* called by mgt process */
-	storage_open_f		*open;		/* called by cache process */
-	storage_alloc_f		*sml_alloc;	/* --//-- only if SML */
-	storage_free_f		*sml_free;	/* --//-- only if SML */
-	storage_getobj_f	*sml_getobj;	/* --//-- only if SML */
-	storage_close_f		*close;		/* --//-- */
-	storage_allocobj_f	*allocobj;	/* --//-- */
-	storage_signal_close_f	*signal_close;	/* --//-- */
-	storage_baninfo_f	*baninfo;	/* --//-- */
-	storage_banexport_f	*banexport;	/* --//-- */
+
+	/* Called in MGT process */
+	storage_init_f		*init;
+
+	/* Called in cache process */
+	storage_open_f		*open;
+	storage_close_f		*close;
+	storage_allocobj_f	*allocobj;
+	storage_signal_close_f	*signal_close;
+	storage_baninfo_f	*baninfo;
+	storage_banexport_f	*banexport;
+
+	/* Only if SML is used */
+	sml_alloc_f		*sml_alloc;
+	sml_free_f		*sml_free;
+	sml_getobj_f		*sml_getobj;
 
 	const struct obj_methods
 				*methods;
 
-	struct lru		*lru;		/* For storage_lru.c */
+	/* Only if LRU is used */
+	struct lru		*lru;
 
 #define VRTSTVVAR(nm, vtype, ctype, dval) storage_var_##ctype *var_##nm;
 #include "tbl/vrt_stv_var.h"

bin/varnishd/storage/storage_file.c

@@ -415,7 +415,7 @@ smf_open(struct stevedore *st)
 
 /*--------------------------------------------------------------------*/
 
-static struct storage *
+static struct storage * __match_proto__(sml_alloc_f)
 smf_alloc(const struct stevedore *st, size_t size)
 {
 	struct smf *smf;
@@ -451,7 +451,7 @@ smf_alloc(const struct stevedore *st, size_t size)
 
 /*--------------------------------------------------------------------*/
 
-static void __match_proto__(storage_free_f)
+static void __match_proto__(sml_free_f)
 smf_free(struct storage *s)
 {
 	struct smf *smf;

bin/varnishd/storage/storage_malloc.c

@@ -59,7 +59,7 @@ struct sma {
 
 static struct VSC_C_lck *lck_sma;
 
-static struct storage *
+static struct storage * __match_proto__(sml_alloc_f)
 sma_alloc(const struct stevedore *st, size_t size)
 {
 	struct sma_sc *sma_sc;
@@ -125,7 +125,7 @@ sma_alloc(const struct stevedore *st, size_t size)
 	return (&sma->s);
 }
 
-static void __match_proto__(storage_free_f)
+static void __match_proto__(sml_free_f)
 sma_free(struct storage *s)
 {
 	struct sma_sc *sma_sc;

bin/varnishd/storage/storage_persistent.c

@@ -577,7 +577,7 @@ smp_allocobj(struct worker *wrk, const struct stevedore *stv,
  * Allocate a bite
  */
 
-static struct storage *
+static struct storage * __match_proto__(sml_alloc_f)
 smp_alloc(const struct stevedore *st, size_t size)
 {
 

bin/varnishd/storage/storage_persistent.h

@@ -307,7 +307,7 @@ void smp_new_seg(struct smp_sc *sc);
 void smp_close_seg(struct smp_sc *sc, struct smp_seg *sg);
 void smp_init_oc(struct objcore *oc, struct smp_seg *sg, unsigned objidx);
 void smp_save_segs(struct smp_sc *sc);
-storage_getobj_f smp_sml_getobj;
+sml_getobj_f smp_sml_getobj;
 void smp_oc_objupdatemeta(struct worker *, struct objcore *);
 void smp_oc_objfree(struct worker *, struct objcore *);