Changes the pidhash to be an internal reference
[akaros.git] / Documentation / process-internals.txt
index 3e6bcb8..57358c1 100644 (file)
@@ -26,8 +26,8 @@ to Linux's kref:
   already a reference to it.  It is a bug to try to incref on something that has
   no references, so always make sure you incref something that you know has a
   reference.  If you don't know, you need to get it from pid2proc (which is a
-  careful way of doing this).  pid2proc kref_get()s on the reference that is
-  stored inside it.  If you incref and there are 0 references, the kernel will
+  careful way of doing this - pid2proc kref_get_not_zero()s on the reference that is
+  stored inside it).  If you incref and there are 0 references, the kernel will
   panic.  Fix your bug / don't incref random pointers.
 - Can always decref.
 - When the decref returns 0, perform some operation.  This does some final
@@ -59,11 +59,14 @@ protected by a refcnt.
 +1 for existing.
 - The fact that the process is supposed to exist is worth +1.  When it is time
   to die, we decref, and it will eventually be cleaned up.  This existence is
-  based on it's presence in the hash table, which is a stored reference.
-- The hash table is a bit tricky.  We need to kref_get() when it is locked, so
-  we know we have a valid kref to get.  We don't need to lock the list to
-  kref_put the process, since once it is removed from the hash, we now own that
-  reference.  
+  explicitly kref_put()d in proc_destroy().
+- The hash table is a bit tricky.  We need to kref_get_not_zero() when it is
+  locked, so we know we aren't racing with proc_free freeing the proc and
+  removing it from the list.  After removing it from the hash, we don't need to
+  kref_put it, since it was an internal ref.  The kref (i.e. external) isn't for
+  being on the hash list, it's for existing.  This separation allows us to
+  remove the proc from the hash list in the "release" function.  See kref.txt
+  for more details.
 
 +1 for someone using it or planning to use it.
 - This includes simply having a pointer to the proc, since presumably you will