ChangeLogTag:Tue Oct 20 16:20:33 UTC 2009 Steve Huston <shuston@riverace.com>

3 files changed, 57 insertions, 32 deletions

diff --git a/ChangeLog b/ChangeLog
index 0ba457400f7..c0bb08e5daf 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,15 @@
+Tue Oct 20 16:20:33 UTC 2009  Steve Huston  <shuston@riverace.com>
+
+        * ace/Message_Queue_T.cpp (enqueue_*): Move the notify() call outside
+          the lock scope; holding the lock across a call that may block (or
+          do anything else we don't know about) is dangerous. It resulted in
+          deadlock at a customer site.
+
+          See Bugzilla #3250 for any follow-up issues.
+
+        * ace/Process_Mutex.h: Fix doxygen stuff and clarify the behavior
+          when based on semaphores vs. mutexes where there's a choice.
+
 Tue Sep  8 20:27:14 UTC 2009  Steve Huston  <shuston@riverace.com>
 
         * include/makeinclude/rules.local.GNU: Strip CLEANUP_INSTALL before
diff --git a/ace/Message_Queue_T.cpp b/ace/Message_Queue_T.cpp
index 5f6b990d426..f099632f8ac 100644
--- a/ace/Message_Queue_T.cpp
+++ b/ace/Message_Queue_T.cpp
@@ -1781,9 +1781,8 @@ ACE_Message_Queue<ACE_SYNCH_USE>::enqueue_head (ACE_Message_Block *new_item,
 
     if (queue_count == -1)
       return -1;
-
-    this->notify ();
   }
+  this->notify ();
   return queue_count;
 }
 
@@ -1813,9 +1812,8 @@ ACE_Message_Queue<ACE_SYNCH_USE>::enqueue_prio (ACE_Message_Block *new_item,
 
     if (queue_count == -1)
       return -1;
-
-    this->notify ();
   }
+  this->notify ();
   return queue_count;
 }
 
@@ -1845,9 +1843,8 @@ ACE_Message_Queue<ACE_SYNCH_USE>::enqueue_deadline (ACE_Message_Block *new_item,
 
     if (queue_count == -1)
       return -1;
-
-    this->notify ();
   }
+  this->notify ();
   return queue_count;
 }
 
@@ -1884,9 +1881,8 @@ ACE_Message_Queue<ACE_SYNCH_USE>::enqueue_tail (ACE_Message_Block *new_item,
 
     if (queue_count == -1)
       return -1;
-
-    this->notify ();
   }
+  this->notify ();
   return queue_count;
 }
 
diff --git a/ace/Process_Mutex.h b/ace/Process_Mutex.h
index c2fb3c702da..97666f91201 100644
--- a/ace/Process_Mutex.h
+++ b/ace/Process_Mutex.h
@@ -46,36 +46,48 @@ class ACE_Time_Value;
  * @class ACE_Process_Mutex
  *
  * @brief A wrapper for mutexes that can be used across processes on
- * the same host machine, as well as within a process, of
- * course.
+ * the same host machine, as well as within a process, of course.
  *
  * @attention The mechanism upon which @c ACE_Process_Mutex is based
  * can be configured at build time to be either @c ACE_SV_Semaphore_Complex
- * (on platforms that support it) or @c ACE_Mutex. On platforms that
- * require interprocess mutexes be allocated from shared memory (Pthreads
- * and UI Threads are examples), @c ACE_SV_Semaphore_Complex provides a
- * more reliable mechanism for implementing inter-process mutex than
- * @c ACE_Mutex. However, at least on some platforms,
- * @c ACE_SV_Semaphore_Complex is limited to a small number of
- * objects by the underlying System V IPC kernel parameters. If you
- * want to force use of @c ACE_Mutex as the underlying mechanism, set
- * @c ACE_USES_MUTEX_FOR_PROCESS_MUTEX in your @c config.h file.
- * Also, if you require the ability to do a timed @c acquire(), you must
- * set @c ACE_USES_MUTEX_FOR_PROCESS_MUTEX, as timed acquire does not
- * work with System V semaphores.
- * @attention Currently there is also the operational difference between
- * pthreads and semaphores based @c. For semaphore base @c the semaphore
- * is destroyed after the last instance of @c in OS. In contrary, pthread based
- * @c is destroyed when the owner, namely the process which created the
- * first instance of @c destroys the mutex. For protable applications it is better
- * to always ensure that the owner of the mutex destroys it after the
- * other processes.
+ * (on platforms that support it) or @c ACE_Mutex. On platforms that offer
+ * System V IPC (the @c ACE_HAS_SYSV_IPC config macro is defined)
+ * @c ACE_SV_Semaphore_Complex is the default because it is more convenient
+ * and easy to use. @c ACE_Mutex is the default on all other platforms.
+ * On platforms where ACE_SV_Semaphore_Complex is used by default, the
+ * mechanism can be changed to ACE_Mutex when ACE is built by adding
+ * @code
+ *   #define ACE_USES_MUTEX_FOR_PROCESS_MUTEX
+ * @endcode
+ * to your @c config.h file.
+ * @par
+ * Consider these tradeoffs when evaluating whether or not to change
+ * the default:
+ *   - Some platforms (e.g., Pthreads and UI Threads) require interprocess
+ *     mutexes to be allocated from shared memory. On these platforms, using
+ *     ACE_Mutex as the underlying mechanism requires that ACE_Process_Mutex
+ *     objects be allocated in shared memory. Using ACE_SV_Semaphore_Complex
+ *     avoids this restriction.
+ *   - System V IPC kernel parameters have a low default limit on some
+ *     platforms. This would restrict the number of ACE_Process_Mutex objects
+ *     that can be in use simultaneously when using ACE_SV_Semaphore_Complex.
+ *   - If you require the ability to do a timed @c acquire(), you must
+ *     use ACE_Mutex as the underlying mechanism because timed acquire does not
+ *     work with System V semaphores.
+ *   - When using ACE_Mutex on a Pthreads-based platform, an ACE_Process_Mutex
+ *     object is deleted when the process which created the object destroys
+ *     it, regardless of whether or not there are other processes still
+ *     accessing the ACE_Process_Mutex. Using ACE_SV_Semaphore_Complex avoids
+ *     this problem; the semaphore is destroyed when the last use of the
+ *     object ends. For portable applications it is better to always ensure
+ *     that the owner of the mutex destroys it after all other processes have
+ *     stopped using it.
  */
 class ACE_Export ACE_Process_Mutex
 {
 public:
   /**
-   * Create a Process_Mutex, passing in the optional @c name.
+   * Create an ACE_Process_Mutex.
    *
    * @param name optional, null-terminated string containing the name of
    * the object. Multiple users of the same @c ACE_Process_Mutex must use
@@ -93,8 +105,7 @@ public:
 
 #if defined (ACE_HAS_WCHAR)
   /**
-   * Create a Process_Mutex, passing in the optional @c name. (@c wchar_t
-   * version)
+   * Create an ACE_Process_Mutex (@c wchar_t version)
    *
    * @param name optional, null-terminated string containing the name of
    * the object. Multiple users of the same @c ACE_Process_Mutex must use
@@ -111,6 +122,12 @@ public:
                      mode_t mode = ACE_DEFAULT_FILE_PERMS);
 #endif /* ACE_HAS_WCHAR */
 
+  /**
+   * Destructor.
+   *
+   * @note The destructor will not release an acquired mutex except
+   * on Windows.
+   */
   ~ACE_Process_Mutex (void);
 
   /**