[src/trunk]: src/sys/kern Summarize lifetime of cache entries.

[riastradh <riastradh%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/4df1a94dfc74
branches:  trunk
changeset: 822414:4df1a94dfc74
user:      riastradh <riastradh%NetBSD.org@localhost>
date:      Sat Mar 18 22:36:56 2017 +0000

description:
Summarize lifetime of cache entries.

diffstat:

 sys/kern/vfs_cache.c |  46 ++++++++++++++++++++++++++++++++++++++++++++--
 1 files changed, 44 insertions(+), 2 deletions(-)

diffs (67 lines):

diff -r 537591059e16 -r 4df1a94dfc74 sys/kern/vfs_cache.c
--- a/sys/kern/vfs_cache.c      Sat Mar 18 22:04:52 2017 +0000
+++ b/sys/kern/vfs_cache.c      Sat Mar 18 22:36:56 2017 +0000
@@ -1,4 +1,4 @@
-/*     $NetBSD: vfs_cache.c,v 1.119 2017/03/18 22:04:52 riastradh Exp $        */
+/*     $NetBSD: vfs_cache.c,v 1.120 2017/03/18 22:36:56 riastradh Exp $        */
 
 /*-
  * Copyright (c) 2008 The NetBSD Foundation, Inc.
@@ -58,7 +58,7 @@
  */
 
 #include <sys/cdefs.h>
-__KERNEL_RCSID(0, "$NetBSD: vfs_cache.c,v 1.119 2017/03/18 22:04:52 riastradh Exp $");
+__KERNEL_RCSID(0, "$NetBSD: vfs_cache.c,v 1.120 2017/03/18 22:36:56 riastradh Exp $");
 
 #ifdef _KERNEL_OPT
 #include "opt_ddb.h"
@@ -103,6 +103,48 @@
  */
 
 /*
+ * Cache entry lifetime:
+ *
+ *     nonexistent
+ *     ---create---> active
+ *     ---invalidate---> queued
+ *     ---reclaim---> nonexistent.
+ *
+ * States:
+ * - Nonexistent.  Cache entry does not exist.
+ *
+ * - Active.  cache_lookup, cache_lookup_raw, cache_revlookup can look
+ *   up, acquire references, and hand off references to vnodes,
+ *   e.g. via v_interlock.  Marked by nonnull ncp->nc_dvp.
+ *
+ * - Queued.  Pending desstruction by cache_reclaim.  Cannot be used by
+ *   cache_lookup, cache_lookup_raw, or cache_revlookup.  May still be
+ *   on lists.  Marked by null ncp->nc_dvp.
+ *
+ * Transitions:
+ *
+ * - Create: nonexistent--->active
+ *
+ *   Done by cache_enter(dvp, vp, name, namelen, cnflags), called by
+ *   VOP_LOOKUP after the answer is found.  Allocates a struct
+ *   namecache object, initializes it with the above fields, and
+ *   activates it by inserting it into the forward and reverse tables.
+ *
+ * - Invalidate: active--->queued
+ *
+ *   Done by cache_invalidate.  If not already invalidated, nullify
+ *   ncp->nc_dvp and ncp->nc_vp, and add to cache_gcqueue.  Called,
+ *   among various other places, in cache_lookup(dvp, name, namelen,
+ *   nameiop, cnflags, &iswht, &vp) when MAKEENTRY is missing from
+ *   cnflags.
+ *
+ * - Reclaim: queued--->nonexistent
+ *
+ *   Done by cache_reclaim.  Disassociate ncp from any lists it is on
+ *   and free memory.
+ */
+
+/*
  * Locking.
  *
  * L namecache_lock            Global lock for namecache table and queues.