From 7a9fb5103e052150232b64cb5d99374cda3f1234 Mon Sep 17 00:00:00 2001
From: =?utf8?q?Jos=C3=A9=20Fonseca?= <jfonseca@vmware.com>
Date: Wed, 27 Mar 2013 10:16:03 +0000
Subject: [PATCH] common: Add more comments.

---
 common/trace_writer_local.hpp | 32 ++++++++++++++++++++++++++++----
 1 file changed, 28 insertions(+), 4 deletions(-)

diff --git a/common/trace_writer_local.hpp b/common/trace_writer_local.hpp
index c00818b..cc5dda0 100644
--- a/common/trace_writer_local.hpp
+++ b/common/trace_writer_local.hpp
@@ -1,6 +1,6 @@
 /**************************************************************************
  *
- * Copyright 2007-2010 VMware, Inc.
+ * Copyright 2007-2013 VMware, Inc.
  * All Rights Reserved.
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
@@ -24,7 +24,7 @@
  **************************************************************************/
 
 /*
- * Trace writing functions.
+ * Trace writing functions, used to trace calls in the current process.
  */
 
 #ifndef _TRACE_WRITER_LOCAL_HPP_
@@ -56,24 +56,48 @@ namespace trace {
     class LocalWriter : public Writer {
     protected:
         /**
-         * We need a recursive mutex so that it doesn't dead lock when a segfault happens when the mutex is held.
+         * This mutex guarantees that only one thread writes to the trace file
+         * at one given instance.
+         *
+         * We need a recursive mutex so that we dont't dead lock in the event
+         * of a segfault happens while the mutex is held.
+         *
+         * To prevent deadlocks, the call for the real function (the one being
+         * traced) should not be done with the mutex held. That is, it should
+         * be done outside the beginEnter/endEnter and beginLeave/endLeave
+         * pairs. Preferably between these two pairs.
          */
         os::recursive_mutex mutex;
         int acquired;
 
     public:
         /**
-         * Should never called directly -- use localWriter singleton below instead.
+         * Should never called directly -- use localWriter singleton below
+         * instead.
          */
         LocalWriter();
         ~LocalWriter();
 
         void open(void);
 
+        /**
+         * It will acquire the mutex.
+         */
         unsigned beginEnter(const FunctionSig *sig);
+        
+        /**
+         * It will release the mutex.
+         */
         void endEnter(void);
 
+        /**
+         * It will acquire the mutex.
+         */
         void beginLeave(unsigned call);
+
+        /**
+         * It will release the mutex.
+         */
         void endLeave(void);
 
         void flush(void);
-- 
2.43.0