doc: added new example to Type_create_struct

A new example using MPI_UB and an actual struct
should make new users more accustomed to its use.

Signed-off-by: Nick Papior <nickpapior@gmail.com>

Author: zerothi

docs/man-openmpi/man3/MPI_Type_create_struct.3.rst

@@ -73,8 +73,115 @@ DESCRIPTION
 :ref:`MPI_Type_create_struct` creates a structured data type. This routine
 replaces :ref:`MPI_Type_struct`, which is now deprecated.
 
-NOTE - This routine replaces :ref:`MPI_Type_struct`, which is deprecated. See
-the man page :ref:`MPI_Type_struct` for information about that routine.
+
+:ref:`MPI_Type_create_struct` is the most general type constructor. It further
+generalizes :ref:`MPI_Type_create_hindexed` in that it allows each block to consist of
+replications of different datatypes.
+
+**Example 1:**
+Let ``type1`` have type map
+
+::
+
+
+       {(double, 0), (char, 8)}
+
+with extent 16. Let ``B = (2, 1, 3)``, ``D = (0, 16, 26)``, and ``T = (MPI_FLOAT, type1, MPI_CHAR)``.
+Then a call to ``MPI_Type_create_struct(3, B, D, T, newtype)``
+returns a datatype with type map
+
+::
+
+
+       {
+        (float, 0), (float,4),             // 2 float
+        (double, 16), (char, 24),          // 1 type1
+        (char, 26), (char, 27), (char, 28) // 3 char
+       }
+
+That is, two copies of ``MPI_FLOAT`` starting at 0, followed by one copy of
+``type1`` starting at 16, followed by three copies of ``MPI_CHAR``, starting at
+26. (We assume that a float occupies 4 bytes.)
+
+
+**Example 2:**
+
+An example of a struct with only some components part of the type
+
+.. code-block:: c
+
+   struct MyStruct {
+       double x[2], y;
+       char a;
+       int n;
+   };
+
+   // create a new type where we only send x, y and n
+   int B[] = {
+       2, // 2 double's
+       1, // 1 double
+       1, // 1 int
+       1  // alignment padding
+   };
+   MPI_Aint D[] = {
+       offsetof(struct MyStruct, x),
+       offsetof(struct MyStruct, y),
+       offsetof(struct MyStruct, n),
+       sizeof(struct MyStruct)
+   };
+   MPI_Datatype T[] = {
+       MPI_DOUBLE,
+       MPI_DOUBLE,
+       MPI_INT,
+       MPI_UB
+   };
+
+   MPI_Datatype mpi_dt_mystruct;
+   MPI_Type_create_struct(4, B, D, T, &mpi_dt_mystruct);
+   MPI_Type_commit(&mpi_dt_mystruct);
+
+   // We can now send a struct (omitting a)
+
+   struct MyStruct values[3];
+
+   if ( rank == 0 ) {
+       // ... initialize values
+       MPI_Send(values, 3, mpi_dt_mystruct, 1, 0, MPI_COMM_WORLD);
+   } else if ( rank == 1 )
+       MPI_Recv(values, 3, mpi_dt_mystruct, 0, 0, MPI_COMM_WORLD, MPI_STATUS_IGNORE);
+
+
+For more information, see section 3.12.1 of the MPI-1.1 Standard.
+
+
+NOTES
+-----
+
+If an upperbound is set explicitly by using the MPI datatype MPI_UB, the
+corresponding index must be positive.
+
+The MPI-1 Standard originally made vague statements about padding and
+alignment; this was intended to allow the simple definition of
+structures that could be sent with a count greater than one. For
+example,
+
+.. code-block:: c
+
+       struct {int a; char b;} foo;
+
+may have
+
+.. code-block:: c
+
+       sizeof(foo) = sizeof(int) + sizeof(char);
+
+defining the extent of a datatype as including an epsilon, which would
+have allowed an implementation to make the extent an MPI datatype for
+this structure equal to ``2*sizeof(int)``. However, since different systems
+might define different paddings, a clarification to the standard made
+epsilon zero. Thus, if you define a structure datatype and wish to send
+or receive multiple items, you should explicitly include an MPI_UB entry
+as the last member of the structure. See the above example.
 
 
 FORTRAN 77 NOTES