After yet another round of discussions about why these classes are

split between OMPI and ORTE, added a lengthy comment to ompi_bitmap.h
explaining the reason why (and how it would be fine to re-merge them
-- if someone has the time) and references to it from all the other
relevant .h files.

This commit was SVN r5876.

src/class/ompi_bitmap.h

@@ -30,6 +30,80 @@
  * MPI defines to be int's), it is assumed that we can never have more
  * than OMPI_FORTRAN_HANDLE_MAX (which is min(INT_MAX, fortran
  * INTEGER max)).
+ *
+ * --------------------------------------------------------------------
+ *
+ * There are several classes that have forked between their OMPI and
+ * ORTE implementations.  As of this writing:
+ *
+ * - ompi_bitmap and orte_bitmap
+ * - ompi_pointer_array and orte_pointer_array
+ * - ompi_value_array and orte_value_array
+ *
+ * Short version: 
+ *
+ * They were split to accomodate a few differences between
+ * requirements (e.g., "size" parameters being int vs. size_t).  It
+ * would be nice to re-merge them someday; there's a few technical
+ * issues that would need to be solved, but nothing impossible.  But
+ * there's no pressing *need* to re-merge these, so they have fallen
+ * somewhat low on the priority list of things to do.
+ *
+ * Longer version:
+ *
+ * Although these are generic functionality classes, the ORTE versions
+ * split from the OMPI (soon to be OPAL) versions because of
+ * restrictions imposed by the OMPI versions.  Specifically, the OMPI
+ * versions specifically limit size arguments to "int" (in multiple
+ * different ways, e.g.: types of "size" parameters to functions,
+ * maximum allowable values of size parameters, etc.).  The ORTE
+ * functions need most size parameters to be of type size_t, not int.
+ * This is the most fundamental difference.  In C++, we could have
+ * templated these functions, but we unfortunately can't easily do
+ * that in C (in hindsight, perhaps some preprocessor macros might
+ * have been sufficient, but...).
+ *
+ * Another, more subtle, reason why these were split because of the
+ * scary word "FORTRAN" that appears in some of the upper value limit
+ * checks in the OMPI versions.  That is, we always check for max size
+ * against OMPI_FORTRAN_HANDLE_MAX.  This value is simply min(INT_MAX,
+ * max value of Fortran INTEGER) -- it's the minimum of the maximum
+ * values of integers in C and Fortran.  Usually, it's the same value
+ * (2^32), but the macro is there to ensure that even if it's
+ * different, we end up with a value that can be represented in both
+ * languages.
+ *
+ * This is because the primary purpose of these classes is to serve as
+ * an interface to the Fortran language bindings -- fortran handles
+ * may be directly represented as indices into arrays or bitmaps.
+ * Hence, the size has to be representable in both C and Fortran.
+ *
+ * Regardless, we need to check for *some* max value for the size of
+ * these entites.  Perhaps the name "FORTRAN" in the macro is
+ * scary/misleading -- it can certainly be changed in the future if it
+ * would be more clear.  So it's ok to have a max -- but perhaps
+ * changing the name would make it more palatable to both layers
+ * (remebering that the max value is still going to be enormous --
+ * usually 2^32; even if the size is of type size_t, you're going to
+ * run out of memory long before you have 2^32 entries).  Or perhaps
+ * the max value can be parameterized to depend on whether the size
+ * type is int or size_t -- I'm sure something can be worked out.
+ *
+ * As mentioned above, if these really are the only two differences
+ * (int vs. size_t and the max sentinel value) -- and I'm pretty sure
+ * that they are -- then these classes can be re-merged someday,
+ * resulting in less code to maintain.  This would be good for
+ * long-term maintenance.  However, it's kinda low on the priority
+ * list.  So it hasn't been done [yet].  If someone wants to do this,
+ * please feel free!  :-)
+ *
+ * Given the fact that we just had yet another round of discussions
+ * about the splitting / re-merging of these classes (26 May 2005), it
+ * was decided to put this big comment in the hopes of:
+ *
+ * - someday motivating someone to re-merge the classes
+ * - prevent yet-another round of these discussions by documenting the
+ *   issues once and for all :-)
  */
 
 #ifndef OMPI_BITMAP_H

src/class/ompi_pointer_array.h

@@ -14,6 +14,9 @@
  * $HEADER$
  */
 /** @file
+ *
+ * See ompi_bitmap.h for an explanation of why there is a split
+ * between OMPI and ORTE for this generic class.
  *
  * Utility functions to manage fortran <-> c opaque object
  * translation.  Note that since MPI defines fortran handles as

src/class/ompi_value_array.h

@@ -28,6 +28,9 @@
 
 /*
  *  @file  Array of elements maintained by value.
+ *
+ * See ompi_bitmap.h for an explanation of why there is a split
+ * between OMPI and ORTE for this generic class.
  */
 #if defined(c_plusplus) || defined(__cplusplus)
 extern "C" {

src/class/orte_bitmap.h

@@ -16,6 +16,9 @@
  */
 
 /** @file
+ *
+ * See ompi_bitmap.h for an explanation of why there is a split
+ * between OMPI and ORTE for this generic class.
  *
  *  A bitmap implementation. The bits start off with 0, so this bitmap
  *  has bits numbered as bit 0, bit 1, bit 2 and so on. This bitmap

src/class/orte_pointer_array.h

@@ -15,12 +15,8 @@
  */
 /** @file
  *
- * Utility functions to manage fortran <-> c opaque object
- * translation.  Note that since MPI defines fortran handles as
- * [signed] int's, we use int everywhere in here where you would
- * normally expect int.  There's some code that makes sure indices
- * don't go above FORTRAN_HANDLE_MAX (which is min(INT_MAX, fortran
- * INTEGER max)), just to be sure.
+ * See ompi_bitmap.h for an explanation of why there is a split
+ * between OMPI and ORTE for this generic class.
  */
 
 #ifndef ORTE_POINTER_ARRAY_H

src/class/orte_value_array.h

@@ -28,6 +28,9 @@
 
 /*
  *  @file  Array of elements maintained by value.
+ *
+ * See ompi_bitmap.h for an explanation of why there is a split
+ * between OMPI and ORTE for this generic class.
  */
 #if defined(c_plusplus) || defined(__cplusplus)
 extern "C" {