Skip to content

Commit bb40271

Browse files
authored
Merge pull request #11392 from zerothi/11340-2-beautification
Continuation of the beautifaction process
2 parents da6cb6b + 9f7c9bb commit bb40271

File tree

86 files changed

+583
-1230
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

86 files changed

+583
-1230
lines changed

docs/Makefile.am

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -415,6 +415,7 @@ OMPI_MAN3 = \
415415
MPI_Status_set_cancelled.3 \
416416
MPI_Status_set_elements.3 \
417417
MPI_Status_set_elements_x.3 \
418+
MPI_T.3 \
418419
MPI_T_category_changed.3 \
419420
MPI_T_category_get_categories.3 \
420421
MPI_T_category_get_cvars.3 \
@@ -542,9 +543,8 @@ OMPI_MAN3 = \
542543
MPIX_Query_rocm_support.3 \
543544
OMPI_Affinity_str.3
544545

545-
OMPI_MAN5 = \
546-
MPI_T.5 \
547-
Open-MPI.5
546+
OMPI_MAN7 = \
547+
Open-MPI.7
548548

549549
OSHMEM_MAN1 = \
550550
oshmem-wrapper-compiler.1 \
@@ -779,8 +779,8 @@ OMPI_MAN1_BUILT = $(OMPI_MAN1:%.1=$(MAN_OUTDIR)/%.1)
779779
OMPI_MAN3_RST = $(OMPI_MAN3:%.3=man-openmpi/man3/%.3.rst)
780780
OMPI_MAN3_BUILT = $(OMPI_MAN3:%.3=$(MAN_OUTDIR)/%.3)
781781

782-
OMPI_MAN5_RST = $(OMPI_MAN5:%.5=man-openmpi/man5/%.5.rst)
783-
OMPI_MAN5_BUILT = $(OMPI_MAN5:%.5=$(MAN_OUTDIR)/%.5)
782+
OMPI_MAN7_RST = $(OMPI_MAN7:%.7=man-openmpi/man7/%.7.rst)
783+
OMPI_MAN7_BUILT = $(OMPI_MAN7:%.7=$(MAN_OUTDIR)/%.7)
784784

785785
OSHMEM_MAN1_RST = $(OSHMEM_MAN1:%.1=man-oshmem/man1/%.1.rst)
786786
OSHMEM_MAN1_BUILT = $(OSHMEM_MAN1:%.1=$(MAN_OUTDIR)/%.1)
@@ -791,7 +791,7 @@ OSHMEM_MAN3_BUILT = $(OSHMEM_MAN3:%.3=$(MAN_OUTDIR)/%.3)
791791
EXTRA_DIST += \
792792
$(OMPI_MAN1_BUILT) \
793793
$(OMPI_MAN3_BUILT) \
794-
$(OMPI_MAN5_BUILT) \
794+
$(OMPI_MAN7_BUILT) \
795795
$(OSHMEM_MAN1_BUILT) \
796796
$(OSHMEM_MAN3_BUILT)
797797

@@ -852,7 +852,7 @@ EXTRA_DIST += \
852852
$(OUTDIR)/man
853853

854854
ALL_MAN_BUILT = \
855-
$(OMPI_MAN1_BUILT) $(OMPI_MAN3_BUILT) $(OMPI_MAN5_BUILT) \
855+
$(OMPI_MAN1_BUILT) $(OMPI_MAN3_BUILT) $(OMPI_MAN7_BUILT) \
856856
$(OSHMEM_MAN1_BUILT) $(OSHMEM_MAN_3_BUILT)
857857
$(ALL_MAN_BUILT): $(RST_SOURCE_FILES) $(IMAGE_SOURCE_FILES)
858858
$(ALL_MAN_BUILT): $(TEXT_SOURCE_FILES) $(SPHINX_CONFIG)
@@ -903,7 +903,7 @@ man1_MANS += $(OMPI_MAN1_JAVA_REDIRECTS)
903903
endif
904904

905905
man3_MANS = $(OMPI_MAN3_BUILT)
906-
man5_MANS = $(OMPI_MAN5_BUILT)
906+
man7_MANS = $(OMPI_MAN7_BUILT)
907907

908908
if PROJECT_OSHMEM
909909
man1_MANS += \

docs/conf.py

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -131,6 +131,15 @@
131131
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'venv', 'py*/**']
132132

133133

134+
# Clarify the language for verbatim blocks (::)
135+
# Never change this to anything else. Lots of verbatim code blocks
136+
# exists across the documentation pages.
137+
# The default value is actually "default" which is something like Python3
138+
# and on fail it reverts to "none". We just go directly to none for clarity.
139+
highlight_language = "none"
140+
141+
142+
134143
# -- Options for HTML output -------------------------------------------------
135144

136145
# The theme to use for HTML and HTML Help pages. See the documentation for
@@ -212,5 +221,6 @@ def _doit(topdir):
212221
.. |flex_min_version| replace:: {flex_min_version}
213222
.. |mpi_standard_version| replace:: {mpi_standard_version}
214223
.. |mpi_standard_subversion| replace:: {mpi_standard_subversion}
224+
.. |deprecated_favor| replace:: this routine is deprecated in favor of
215225
216226
"""

docs/man-openmpi/index.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,4 +19,4 @@ Open MPI man pages, by section:
1919

2020
man1/index
2121
man3/index
22-
man5/index
22+
man7/index

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

Lines changed: 2 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -33,8 +33,8 @@ C Syntax
3333
MPI_Request *request)
3434
3535
36-
Fortran Syntax (see FORTRAN 77 NOTES)
37-
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
36+
Fortran Syntax
37+
^^^^^^^^^^^^^^
3838

3939
.. code-block:: fortran
4040
@@ -138,21 +138,6 @@ indicates that the *origin_addr* buffer is free to be updated. It does
138138
not indicate that the operation has completed at the target window.
139139

140140

141-
FORTRAN 77 NOTES
142-
----------------
143-
144-
The MPI standard prescribes portable Fortran syntax for the
145-
*TARGET_DISP* argument only for Fortran 90. FORTRAN 77 users may use the
146-
non-portable syntax
147-
148-
.. code-block:: fortran
149-
150-
INTEGER*MPI_ADDRESS_KIND TARGET_DISP
151-
152-
where ``MPI_ADDRESS_KIND`` is a constant defined in ``mpif.h`` and gives the
153-
length of the declared integer in bytes.
154-
155-
156141
NOTES
157142
-----
158143

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

Lines changed: 4 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -6,8 +6,7 @@ MPI_Address
66

77
.. include_body
88
9-
:ref:`MPI_Address` - Gets the address of a location in memory -- use of
10-
this routine is deprecated.
9+
:ref:`MPI_Address` - Gets the address of a location in memory -- |deprecated_favor| :ref:`MPI_Get_address`.
1110

1211

1312
SYNTAX
@@ -29,7 +28,9 @@ Fortran Syntax
2928

3029
.. code-block:: fortran
3130
32-
INCLUDE 'mpif.h'
31+
USE MPI
32+
! or the older form: INCLUDE 'mpif.h'
33+
3334
MPI_ADDRESS(LOCATION, ADDRESS, IERROR)
3435
<type> LOCATION (*)
3536
INTEGER ADDRESS, IERROR
@@ -50,40 +51,6 @@ DESCRIPTION
5051
Note that use of this routine is *deprecated* as of MPI-2. Please use
5152
:ref:`MPI_Get_address` instead.
5253

53-
The address of a location in memory can be found by invoking this
54-
function. Returns the (byte) address of location.
55-
56-
Example: Using :ref:`MPI_Address` for an array.
57-
58-
.. code-block:: fortran
59-
60-
REAL A(100,100)
61-
62-
INTEGER I1, I2, DIFF
63-
CALL MPI_ADDRESS(A(1,1), I1, IERROR)
64-
CALL MPI_ADDRESS(A(10,10), I2, IERROR)
65-
DIFF = I2 - I1
66-
! The value of DIFF is 909*sizeof(real)
67-
!the values of I1 and I2 are implementation dependent.
68-
69-
70-
NOTES
71-
-----
72-
73-
This routine is provided for both Fortran and C programmers and may be
74-
useful when writing portable code. In the current release, the address
75-
returned by this routine will be the same as that produced by the C ``&``
76-
operator.
77-
78-
C users may be tempted to avoid using :ref:`MPI_Address` and rely on the
79-
availability of the address operator &. Note, however, that &
80-
cast-expression is a pointer, not an address. ANSI C does not require
81-
that the value of a pointer (or the pointer cast to int) be the absolute
82-
address of the object pointed at although this is commonly the case.
83-
Furthermore, referencing may not have a unique definition on machines
84-
with a segmented address space. The use of :ref:`MPI_Address` to "reference" C
85-
variables guarantees portability to such machines as well.
86-
8754

8855
ERRORS
8956
------

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

Lines changed: 17 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -23,8 +23,8 @@ C Syntax
2323
int MPI_Alloc_mem(MPI_Aint size, MPI_Info info, void *baseptr)
2424
2525
26-
Fortran Syntax (see FORTRAN NOTES)
27-
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
26+
Fortran Syntax
27+
^^^^^^^^^^^^^^
2828

2929
.. code-block:: fortran
3030
@@ -74,40 +74,31 @@ pointer object for this parameter. The provided argument should be a
7474
pointer to a pointer of arbitrary type (e.g., ``void **``).
7575

7676

77-
FORTRAN NOTES
77+
Fortran NOTES
7878
-------------
7979

80-
There is no portable FORTRAN 77 syntax for using :ref:`MPI_Alloc_mem`. There is
81-
no portable Fortran syntax for using pointers returned from
82-
:ref:`MPI_Alloc_mem`. However, :ref:`MPI_Alloc_mem` can be used with Sun Fortran
83-
compilers.
84-
85-
From FORTRAN 77, you can use the following non-standard declarations for
86-
the SIZE and BASEPTR arguments:
80+
The :ref:`MPI_Alloc_mem` calls require the use of the ``iso_c_binding`` module
81+
for due to the use of ``TYPE(C_PTR)``.
8782

8883
.. code-block:: fortran
8984
90-
INCLUDE "mpif.h"
91-
INTEGER*MPI_ADDRESS_KIND SIZE, BASEPTR
92-
93-
94-
From either FORTRAN 77 or Fortran 90, you can use "Cray pointers" for
95-
the BASEPTR argument. Cray pointers are described further in the Fortran
96-
User's Guide and are supported by many Fortran compilers. For example,
85+
use iso_c_binding
9786
98-
.. code-block:: fortran
87+
type(c_ptr) :: alloc_ptr
88+
integer :: size, ierr
89+
double precision, pointer :: array(:,:)
9990
100-
INCLUDE "mpif.h"
101-
REAL*4 A(100,100)
102-
POINTER (BASEPTR, A)
103-
INTEGER*MPI_ADDRESS_KIND SIZE
91+
! A 2D array of 100 elements
92+
size = 10 * 10
93+
call MPI_Alloc_Mem(size * 8, MPI_INFO_NULL, alloc_ptr, ierr)
10494
105-
SIZE = 4 * 100 * 100
106-
CALL MPI_ALLOC_MEM(SIZE,MPI_INFO_NULL,BASEPTR,IERR)
95+
! Point to the array
96+
call c_f_pointer(alloc_ptr, array, [10, 10])
10797
108-
! use A
98+
! ... use the array ...
10999
110-
CALL MPI_FREE_MEM(A, IERR)
100+
! Free the memory, no need for the alloc_ptr
101+
call MPI_Free_mem(array, ierr)
111102
112103
113104
ERRORS

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

Lines changed: 4 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -6,8 +6,7 @@ MPI_Attr_delete
66

77
.. include_body
88
9-
:ref:`MPI_Attr_delete` - Deletes attribute value associated with a key --
10-
use of this routine is deprecated.
9+
:ref:`MPI_Attr_delete` - Deletes attribute value associated with a key -- |deprecated_favor| :ref:`MPI_Comm_delete_attr`.
1110

1211

1312
SYNTAX
@@ -29,7 +28,9 @@ Fortran Syntax
2928

3029
.. code-block:: fortran
3130
32-
INCLUDE 'mpif.h'
31+
USE MPI
32+
! or the older form: INCLUDE 'mpif.h'
33+
3334
MPI_ATTR_DELETE(COMM, KEYVAL, IERROR)
3435
INTEGER COMM, KEYVAL, IERROR
3536
@@ -50,27 +51,6 @@ Note that use of this routine is *deprecated* as of MPI-2, and was
5051
*deleted* in MPI-3. Please use :ref:`MPI_Comm_delete_attr`. This function does
5152
not have a mpi_f08 binding.
5253

53-
Delete attribute from cache by key. This function invokes the attribute
54-
delete function delete_fn specified when the keyval was created. The
55-
call will fail if the delete_fn function returns an error code other
56-
than MPI_SUCCESS.
57-
58-
Whenever a communicator is replicated using the function :ref:`MPI_Comm_dup`,
59-
all callback copy functions for attributes that are currently set are
60-
invoked (in arbitrary order). Whenever a communicator is deleted using
61-
the function :ref:`MPI_Comm_free`, all callback delete functions for attributes
62-
that are currently set are invoked.
63-
64-
65-
NOTES
66-
-----
67-
68-
Note that it is not defined by the MPI standard what happens if the
69-
delete_fn callback invokes other MPI functions. In Open MPI, it is not
70-
valid for delete_fn callbacks (or any of their children) to add or
71-
delete attributes on the same object on which the delete_fn callback is
72-
being invoked.
73-
7454

7555
ERRORS
7656
------

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

Lines changed: 4 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -6,8 +6,7 @@ MPI_Attr_get
66

77
.. include_body
88
9-
:ref:`MPI_Attr_get` - Retrieves attribute value by key -- use of this
10-
routine is deprecated.
9+
:ref:`MPI_Attr_get` - Retrieves attribute value by key -- |deprecated_favor| :ref:`MPI_Comm_get_attr`.
1110

1211

1312
SYNTAX
@@ -30,7 +29,9 @@ Fortran Syntax
3029

3130
.. code-block:: fortran
3231
33-
INCLUDE 'mpif.h'
32+
USE MPI
33+
! or the older form: INCLUDE 'mpif.h'
34+
3435
MPI_ATTR_GET(COMM, KEYVAL, ATTRIBUTE_VAL, FLAG, IERROR)
3536
INTEGER COMM, KEYVAL, ATTRIBUTE_VAL, IERROR
3637
LOGICAL FLAG
@@ -54,12 +55,6 @@ Note that use of this routine is *deprecated* as of MPI-2, and was
5455
*deleted* in MPI-3. Please use :ref:`MPI_Comm_get_attr`. This function does not
5556
have a mpi_f08 binding.
5657

57-
Retrieves attribute value by key. The call is erroneous if there is no
58-
key with value keyval. On the other hand, the call is correct if the key
59-
value exists, but no attribute is attached on comm for that key; in such
60-
case, the call returns flag = false. In particular MPI_KEYVAL_INVALID is
61-
an erroneous key value.
62-
6358

6459
ERRORS
6560
------

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

Lines changed: 5 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -6,8 +6,8 @@ MPI_Attr_put
66

77
.. include_body
88
9-
:ref:`MPI_Attr_put` - Stores attribute value associated with a key -- use
10-
of this routine is deprecated.
9+
:ref:`MPI_Attr_put` - Stores attribute value associated with a key -- |deprecated_favor| :ref:`MPI_Comm_set_attr`.
10+
1111

1212

1313
SYNTAX
@@ -29,7 +29,9 @@ Fortran Syntax
2929

3030
.. code-block:: fortran
3131
32-
INCLUDE 'mpif.h'
32+
USE MPI
33+
! or the older form: INCLUDE 'mpif.h'
34+
3335
MPI_ATTR_PUT(COMM, KEYVAL, ATTRIBUTE_VAL, IERROR)
3436
INTEGER COMM, KEYVAL, ATTRIBUTE_VAL, IERROR
3537
@@ -51,31 +53,6 @@ Note that use of this routine is *deprecated as of MPI-2, and* was
5153
deleted in MPI-3. Please use :ref:`MPI_Comm_set_attr`. This function does not
5254
have a mpi_f08 binding.
5355

54-
:ref:`MPI_Attr_put` stores the stipulated attribute value attribute_val for
55-
subsequent retrieval by :ref:`MPI_Attr_get`. If the value is already present,
56-
then the outcome is as if :ref:`MPI_Attr_delete` was first called to delete the
57-
previous value (and the callback function delete_fn was executed), and a
58-
new value was next stored. The call is erroneous if there is no key with
59-
value keyval; in particular MPI_KEYVAL_INVALID is an erroneous key
60-
value. The call will fail if the delete_fn function returned an error
61-
code other than MPI_SUCCESS.
62-
63-
64-
NOTES
65-
-----
66-
67-
Values of the permanent attributes MPI_TAG_UB, MPI_HOST, MPI_IO, and
68-
MPI_WTIME_IS_GLOBAL may not be changed.
69-
70-
The type of the attribute value depends on whether C or Fortran is being
71-
used. In C, an attribute value is a pointer (``void *``); in Fortran, it is
72-
a single integer (not a pointer, since Fortran has no pointers and there
73-
are systems for which a pointer does not fit in an integer, e.g., any
74-
32-bit address system that uses 64 bits for Fortran DOUBLE PRECISION).
75-
76-
If an attribute is already present, the delete function (specified when
77-
the corresponding keyval was created) will be called.
78-
7956

8057
ERRORS
8158
------

0 commit comments

Comments
 (0)