Clean up locking.

native_client_sdk/src/libraries/nacl_io/kernel_proxy.h

Index: native_client_sdk/src/libraries/nacl_io/kernel_proxy.h
diff --git a/native_client_sdk/src/libraries/nacl_io/kernel_proxy.h b/native_client_sdk/src/libraries/nacl_io/kernel_proxy.h
index 554a75ca4cee35b9cbf1c02fa382cbe60b9050bb..2bbf15bf38193d1a0a0614f6c060113707d3abfe 100644
--- a/native_client_sdk/src/libraries/nacl_io/kernel_proxy.h
+++ b/native_client_sdk/src/libraries/nacl_io/kernel_proxy.h
@@ -18,6 +18,14 @@ class PepperInterface;
 // KernelProxy provide one-to-one mapping for libc kernel calls.  Calls to the
 // proxy will result in IO access to the provided Mount and MountNode objects.
 //
+// NOTE: The KernelProxy does not directly take any kernel locks, all locking
+// is done by the parent class KernelObject.  Instead, KernelProxy is
+// responsible for taking the locks of the KernelHandle, and MountNode objects.
+// For this reason, a KernelObject call should not be done while holding
+// a handle or node lock.  In addition, to ensure locking order,
+// a KernelHandle lock must never be taken after taking the associated
+// MountNode's lock.

[binji, 2013/07/10 21:24:34]

Might be nice to have a quick diagram of the locking order here:

KernelObject -> KernelHandle -> MountNode

[noelallen1, 2013/07/10 22:11:07]

There is only the one legal lock chain:
   KernelHandle -> MountNode

No other lock multiple lock conditions are legal.   Is the text above confusing?

+//
 // NOTE: The KernelProxy is the only class that should be setting errno. All
 // other classes should return Error (as defined by nacl_io/error.h).
 class KernelProxy : protected KernelObject {
@@ -26,22 +34,29 @@ class KernelProxy : protected KernelObject {
 
   KernelProxy();
   virtual ~KernelProxy();
+
   // Takes ownership of |ppapi|.
   // |ppapi| may be NULL. If so, no mount that uses pepper calls can be mounted.
   virtual void Init(PepperInterface* ppapi);
 
+  // NaCl-only function to read resources specified in the NMF file.
+  virtual int open_resource(const char* file);
+
   // KernelHandle and FD allocation and manipulation functions.
   virtual int open(const char* path, int oflag);
   virtual int close(int fd);
   virtual int dup(int fd);
   virtual int dup2(int fd, int newfd);
 
-  // System calls handled by KernelProxy (not mount-specific)
+  // Path related System calls handled by KernelProxy (not mount-specific)
   virtual int chdir(const char* path);
   virtual char* getcwd(char* buf, size_t size);
   virtual char* getwd(char* buf);
-  virtual int mount(const char *source, const char *target,
-      const char *filesystemtype, unsigned long mountflags, const void *data);
+  virtual int mount(const char *source,
+                    const char *target,
+                    const char *filesystemtype,
+                    unsigned long mountflags,
+                    const void *data);
   virtual int umount(const char *path);
 
   // Stub system calls that don't do anything (yet), handled by KernelProxy.
@@ -99,14 +114,11 @@ class KernelProxy : protected KernelObject {
                      size_t offset);
   virtual int munmap(void* addr, size_t length);
 
-  // NaCl-only function to read resources specified in the NMF file.
-  virtual int open_resource(const char* file);
-
 protected:
   MountFactoryMap_t factories_;
+
   int dev_;
   PepperInterface* ppapi_;
-
   static KernelProxy *s_instance_;
 
   DISALLOW_COPY_AND_ASSIGN(KernelProxy);