From: David Wells <wellsd2@rpi.edu>
Date: Thu, 13 Apr 2017 01:27:06 +0000 (-0400)
Subject: Clarify Subscriptor's documentation.
X-Git-Tag: v9.0.0-rc1~1693^2
X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=2d198e8bb40d1f5bf4089d7389b2d64a8c0cc301;p=dealii.git

Clarify Subscriptor's documentation.

We no longer use volatile variables, so just state that some features
of Subscriptor are disabled when we enable threads.
---

diff --git a/include/deal.II/base/subscriptor.h b/include/deal.II/base/subscriptor.h
index 37f3b1acad..e46874e91b 100644
--- a/include/deal.II/base/subscriptor.h
+++ b/include/deal.II/base/subscriptor.h
@@ -42,14 +42,17 @@ DEAL_II_NAMESPACE_OPEN
  * The utility of this class is even enhanced by providing identifying strings
  * to the functions subscribe() and unsubscribe(). In case of a hanging
  * subscription during destruction, this string will be listed in the
- * exception's message. For reasons of efficiency, these strings are handled
- * as <tt>const char*</tt>. Therefore, the pointers provided to subscribe()
- * and to unsubscribe() must be the same. Strings with equal contents will not
- * be recognized to be the same. The handling in SmartPointer will take care
- * of this.
+ * exception's message. These strings are represented as <code>const char
+ * *</code> pointers since the underlying buffer comes from (and is managed
+ * by) the run-time type information system: more exactly, these pointers are
+ * the result the function call <code>typeid(x).name()<code> where
+ * <code>x</code> is some object. Therefore, the pointers provided to
+ * subscribe() and to unsubscribe() must be the same. Strings with equal
+ * contents will not be recognized to be the same. The handling in
+ * SmartPointer will take care of this.
  *
- * @note Due to a problem with <tt>volatile</tt> declarations, this additional
- * feature is switched off if multithreading is used.
+ * @note This feature is switched off if multithreading is used (i.e., if
+ * <code>DEAL_II_WITH_THREADS</code> is on).
  *
  * @ingroup memory
  * @author Guido Kanschat, 1998 - 2005
diff --git a/source/base/subscriptor.cc b/source/base/subscriptor.cc
index ce05a88509..5b460a6629 100644
--- a/source/base/subscriptor.cc
+++ b/source/base/subscriptor.cc
@@ -152,6 +152,8 @@ Subscriptor::subscribe(const char *id) const
     object_info = &typeid(*this);
   ++counter;
 
+  // This feature is disabled when we compile with threads: see the
+  // documentation of this class.
 #  ifndef DEAL_II_WITH_THREADS
   const char *const name = (id != 0) ? id : unknown_subscriber;
 
@@ -183,6 +185,8 @@ Subscriptor::unsubscribe(const char *id) const
 
   --counter;
 
+  // This feature is disabled when we compile with threads: see the
+  // documentation of this class.
 #  ifndef DEAL_II_WITH_THREADS
   map_iterator it = counter_map.find(name);
   AssertNothrow (it != counter_map.end(), ExcNoSubscriber(object_info->name(), name));