ChangeLogTag:Sun

3 files changed, 38 insertions, 11 deletions

diff --git a/ACE/ChangeLog b/ACE/ChangeLog
index 49e5906fffa..ae8908157b1 100644
--- a/ACE/ChangeLog
+++ b/ACE/ChangeLog
@@ -1,3 +1,9 @@
+Sun Apr  7 00:20:49 UTC 2013  Douglas C. Schmidt  <schmidt@dre.vanderbilt.edu>
+
+        * ace/Global_Macros.h: Added documentation for the arguments to
+          the ACE_GUARD_XXX macros.  Thanks to Neil Youngman <ny at
+          youngman dot org dot uk> for contributing this.
+
 Thu Apr  4 16:29:07 UTC 2013  Douglas C. Schmidt  <schmidt@dre.vanderbilt.edu>
 
         * examples/Connection/non_blocking/CPP-acceptor.{h,cpp},
diff --git a/ACE/THANKS b/ACE/THANKS
index 03a5b7145c8..0193e0fbce7 100644
--- a/ACE/THANKS
+++ b/ACE/THANKS
@@ -2377,6 +2377,7 @@ Phillip LaBanca <labancap at ociweb dot com>
 <pkow88776 at onet dot pl>
 Journeyer J. Joh <oosaprogrammer at gmail dot com>
 Rudy Pot <rpot at aweta dot nl>
+Neil Youngman <ny at youngman dot org dot uk>
 
 I would particularly like to thank Paul Stephenson, who worked with me
 at Ericsson in the early 1990's.  Paul devised the recursive Makefile
diff --git a/ACE/ace/Global_Macros.h b/ACE/ace/Global_Macros.h
index 74c6d8c3e6b..cf24327650b 100644
--- a/ACE/ace/Global_Macros.h
+++ b/ACE/ace/Global_Macros.h
@@ -108,17 +108,37 @@ ACE_END_VERSIONED_NAMESPACE_DECL
 
 // FUZZ: disable check_for_ACE_Guard
 
-// Convenient macro for testing for deadlock, as well as for detecting
-// when mutexes fail.
-/* @warning
- *   Use of ACE_GUARD() is rarely correct.  ACE_GUARD() causes the current
- *   function to return if the lock is not acquired.  Since merely returning
- *   (no value) almost certainly fails to handle the acquisition failure
- *   and almost certainly fails to communicate the failure to the caller
- *   for the caller to handle, ACE_GUARD() is almost always the wrong
- *   thing to do.  The same goes for ACE_WRITE_GUARD() and ACE_READ_GUARD() .
- *   ACE_GUARD_REACTION() is better because it lets you specify error
- *   handling code.
+/* Convenient macro for testing for deadlock, as well as for detecting
+ * when mutexes fail.
+ *
+ * The parameters to the ACE_GUARD_XXX macros are used as follows:
+ *
+ * MUTEX - This is the type used as the template parameter for ACE_Guard
+ *
+ * OBJ - Name for the guard object. This name should not be declared
+ *       outside the macro.
+ *
+ * LOCK - The actual lock (mutex) variable. This should be a variable
+ *        of type MUTEX, see above.
+ *
+ * ACTION - Code segment to be run, if and only if the lock is
+ *          acquired.
+ *
+ * REACTION - Code segment to be run, if and only if the lock is not
+ *            acquired.
+ *
+ * RETURN - A value to be returned from the calling function, if and
+ *          only if the lock is not acquired.
+ *
+ * @warning
+ *   Use of ACE_GUARD() is rarely correct.  ACE_GUARD() causes the
+ *   current function to return if the lock is not acquired.  Since
+ *   merely returning (no value) almost certainly fails to handle the
+ *   acquisition failure and almost certainly fails to communicate the
+ *   failure to the caller for the caller to handle, ACE_GUARD() is
+ *   almost always the wrong thing to do.  The same goes for
+ *   ACE_WRITE_GUARD() and ACE_READ_GUARD() .  ACE_GUARD_REACTION() is
+ *   better because it lets you specify error handling code.
  */
 #if !defined (ACE_GUARD_ACTION)
 #define ACE_GUARD_ACTION(MUTEX, OBJ, LOCK, ACTION, REACTION) \