API tools faq
paste
Advertisement
Guest User

Untitled

a guest
Mar 31st, 2015
259
0
Never
Add comment
Not a member of Pastebin yet? Sign Up, it unlocks many cool features!
text 51.84 KB | None | 0 0
raw download clone embed print report
  1. Index: chap-binding/binding-2.tex
  2. ===================================================================
  3. --- chap-binding/binding-2.tex (revision 1802)
  4. +++ chap-binding/binding-2.tex (revision 1948)
  5. @@ -100,7 +100,7 @@
  6. Section~\ref{f90:mpif08} through~\ref{f90:basic} define the Fortran support methods.
  7. The Fortran interfaces of each \MPI/ routine are shorthands.
  8. Section~\ref{sec:f90:linker-names} defines the corresponding full
  9. -interface specification together with the used linker names and implications
  10. +interface specification together with the specific procedure names and implications
  11. for the profiling interface.
  12. Section~\ref{sec:f90:different-fortran-versions} the implementation
  13. of the \MPI/ routines for different versions of the Fortran standard.
  14. @@ -154,7 +154,7 @@
  15. \code{mpi\_f08} module.
  16. \end{users}
  17. \end{itemize}
  18. -\item Define all \MPI/ handles with uniquely named handle types
  19. +\item Define the derived type \ftype{MPI\_Status}, and define all \MPI/ handles with uniquely named handle types
  20. (instead of \ftype{INTEGER} handles, as in the \code{mpi} module).
  21. This is reflected in the first Fortran
  22. binding in each \MPI/ function definition throughout this document
  23. @@ -220,7 +220,7 @@
  24. assumed-size array and the actual argument is a strided array,
  25. the call may be implemented with copy-in and copy-out
  26. of the argument. In the case of \ftype{INTENT(OUT)} the copy-in may
  27. -be suppressed by the optimization and the routine is starts execution using
  28. +be suppressed by the optimization and the routine starts execution using
  29. an array of undefined values. If the routine stores fewer
  30. elements into the dummy argument than is provided in the actual
  31. argument, then the remaining locations are overwritten with these
  32. @@ -278,11 +278,6 @@
  33. can be used in an implementation with assumed-type and assumed-rank
  34. argument in an explicit interface (e.g., with the \ftype{mpi\_f08} module).
  35.  
  36. -The \ftype{INTERFACE} construct in combination with \ftype{BIND(C)}
  37. -allows the implementation of the Fortran \code{mpi\_f08} interface with a single set of portable
  38. -wrapper routines written in C, which supports all desired features in the \code{mpi\_f08} interface.
  39. -TS 29113 also has a provision for \ftype{OPTIONAL} arguments in \ftype{BIND(C)} interfaces.
  40. -
  41. A further feature useful for \MPI/ is the extension of the
  42. semantics of the \ftype{ASYNCHRONOUS} attribute:
  43. In F2003 and F2008, this attribute could be used only to
  44. @@ -308,6 +303,14 @@
  45. \item Provide explicit interfaces according to the Fortran routine interface specifications.
  46. This module therefore guarantees compile-time argument checking
  47. and allows positional and keyword-based argument lists.
  48. + If an implementation is paired with a compiler that either does
  49. + not support \code{TYPE(*), DIMENSION(..)} from TS 29113, or is
  50. + otherwise unable to ignore the types of choice buffers, then the
  51. + implementation must provide explicit interfaces only for MPI
  52. + routines with no choice buffer arguments. See
  53. + Section \sectionref{sec:f90:different-fortran-versions} on
  54. + page \pageref{sec:f90:different-fortran-versions} for more
  55. + details.
  56. \item Define all \MPI/ handles as type \ftype{INTEGER}.
  57. \item Define the derived type \const{MPI\_Status}
  58. and all named handle types that are used in the \code{mpi\_f08} module.
  59. @@ -514,381 +517,228 @@
  60. of the \MPI/ routines can be used.
  61. \end{rationale}
  62.  
  63. -\begin{implementors}
  64. -To make \code{mpif.h} compatible with both fixed- and free-source
  65. -forms, to allow automatic inclusion by preprocessors, and to allow
  66. -extended fixed-form line length, it is recommended that
  67. -the requirement of usability in free and fixed source form applications
  68. -be met by constructing \code{mpif.h} without any continuation lines. This
  69. -should be possible because \code{mpif.h}
  70. -may contain
  71. -only declarations,
  72. -and because common block declarations can be split among several
  73. -lines.
  74. -The argument names may need to be shortened to keep the
  75. -\ftype{SUBROUTINE} statement within the allowed $72-6=66$ characters, e.g.,
  76. -
  77. -%%HEADER
  78. -%%SKIP
  79. -%%ENDHEADER
  80. -\begin{verbatim}
  81. - INTERFACE
  82. - SUBROUTINE PMPI_DIST_GRAPH_CREATE_ADJACENT(a,b,c,d,e,f,g,h,i,j,k)
  83. - ... ! dummy argument declarations
  84. -\end{verbatim}
  85. -This line has 65 characters and is the longest in \MPIIIIDOTO/.
  86. -
  87. -As long as the \MPI/ standard contains routines
  88. -with choice buffers and a name length and argument
  89. -count that implies that a \ftype{BIND(C)} implementation
  90. -would need to shorten their linker names in \code{mpif.h},
  91. -the \code{mpif.h} cannot set \const{MPI\_SUBARRAYS\_SUPPORTED} and
  92. -\const{MPI\_ASYNC\_PROTECTS\_NONBLOCKING} equals
  93. -\ftype{.TRUE.}, because such shortening is invalid.
  94. -For example,
  95. -\mpifunc{MPI\_FILE\_WRITE\_AT\_ALL\_BEGIN} with 6 arguments,
  96. -may be defined:
  97. -
  98. -%%HEADER
  99. -%%SKIP
  100. -%%ENDHEADER
  101. -\begin{verbatim}
  102. - INTERFACE MPI_FILE_WRITE_AT_ALL_BEGIN
  103. - SUBROUTINE MPI_X(a,b,c,d,e,f)BIND(C,NAME='MPI_File_write_at_all_begin_f')
  104. - ... ! dummy argument declarations
  105. -\end{verbatim}
  106. -This would need a line length of 73 characters, i.e., the C routine name
  107. -would need to
  108. -be shortened by 7 characters to stay within the available 66 characters.
  109. -Note that the name \ftype{MPI\_X} has
  110. -no meaning for the compilation, and that
  111. -this problem occurs only with routines with choice buffers
  112. -implemented with the assumed-type and assumed-rank facility of TS 29113.
  113. -To support Fortran 77 as well as Fortran 90 and later, it may be
  114. -necessary to eliminate all comments from \code{mpif.h}.
  115. -\end{implementors}
  116. -
  117. -\subsection{Interface Specifications, Linker Names and the Profiling Interface}
  118. +\subsection{Interface Specifications, Procedure Names, and the Profiling Interface}
  119. \label{sec:f90:linker-names}
  120.  
  121. -The Fortran interface specifications of each \MPI/ routine
  122. +The Fortran interface specification of each \MPI/ routine
  123. specifies the routine name that must be called by the application program,
  124. and the names and types of the dummy arguments together with
  125. -additional attribbutes. The rules for the linker names and
  126. +additional attributes.
  127. +The Fortran standard allows
  128. +a given Fortran interface to be implemented
  129. +with several methods, e.g., within or outside of a module,
  130. +with or without \ftype{BIND(C)}, or the buffers with or without TS 29113.
  131. +Such implementation decisions imply different binary interfaces
  132. +and different specific procedure names.
  133. +The requirements for
  134. +several implementation schemes together with the
  135. +rules for the specific procedure names and
  136. its implications for the profiling interface are specified
  137. -within this section.
  138. -The linker name of a Fortran routine is defined as the name
  139. -that a C routine would have if both routines would
  140. -have the same name visible for the linker.
  141. -A typical linker name of the Fortran routine \ffunc{FOOfoo}
  142. -is \code{foofoo\_\_}.
  143. -In the case of \ftype{BIND(C,NAME='...')},
  144. -the linker name is directly defined through the external name given by
  145. -the string.
  146. -
  147. -The following rules for linker names apply:
  148. +within this section, but not the implementation details.
  149. +
  150. +\begin{rationale}
  151. +This section was introduced in \MPIIIIDOTO/ on Sep.~21, 2012.
  152. +The major goals for implementing the three
  153. +Fortran support methods have been:
  154. \begin{itemize}
  155. -\item
  156. - With the Fortran \code{mpi\_f08} module,
  157. - if \const{MPI\_SUBARRAYS\_SUPPORTED} equals \ftype{.TRUE.}:
  158. + \item
  159. + Portable implementation of the wrappers
  160. + from the \MPI/ Fortran interfaces to the \MPI/ routines in C.
  161. +\vspace*{-2pt}
  162. + \item
  163. + Binary backward compatible implementation path when switching
  164. + \const{MPI\_SUBARRAYS\_SUPPORTED} from \ftype{.FALSE.} to \ftype{.TRUE.}.
  165. +\vspace*{-2pt}
  166. + \item
  167. + The Fortran \textsf{PMPI} interface need not be backward compatible,
  168. + but a method must be included that a tools layer can use to examine the
  169. + \MPI/ library about the specific procedure names and interfaces used.
  170. +\vspace*{-2pt}
  171. + \item
  172. + No performance drawbacks.
  173. +\vspace*{-2pt}
  174. + \item
  175. + Consistency between all three Fortran support methods.
  176. +\vspace*{-2pt}
  177. + \item
  178. + Consistent with Fortran 2008 + TS 29113.
  179. +\end{itemize}
  180. +The design expected that all dummy arguments in the
  181. +\MPI/ Fortran interfaces are interoperable with C according
  182. +to Fortran 2008 + TS 29113.
  183. +This expectation was not fulfilled.
  184. +The \ftype{LOGICAL} arguments are not interoperable with C,
  185. +mainly because the internal representations for \ftype{.FALSE.} and
  186. +\ftype{.TRUE.} are compiler dependent.
  187. +The provided interface was mainly based on \ftype{BIND(C)} interfaces
  188. +and therefore inconsistent with Fortran.
  189. +To be consistent with Fortran, the \ftype{BIND(C)} had to be
  190. +removed from the callback procedure interfaces and the predefined callbacks,
  191. +e.g., \mpifunc{MPI\_COMM\_DUP\_FN}.
  192. +Non-\ftype{BIND(C)} procedures are also not interoperable with C,
  193. +and therefore the \ftype{BIND(C)} had to be removed from all routines
  194. +with \ftype{PROCEDURE} arguments,
  195. +e.g., from \mpifunc{MPI\_OP\_CREATE}.
  196. +
  197. +Therefore, this section was rewritten as an erratum to \MPIIIIDOTO/.
  198. +\end{rationale}
  199.  
  200. - The Fortran binding must use \ftype{BIND(C)} interfaces with
  201. - an interface name identical to the language independent name,
  202. - e.g., \mpifunc{MPI\_SEND}.
  203. - The linker name is a combination of the C name and an
  204. - \code{\_f08} suffix, e.g., \code{MPI\_Send\_f08}.
  205. - Prototype example:
  206. +A Fortran call to an \MPI/ routine shall result in a call to a procedure
  207. +with one of the specific procedure names and calling conventions, as described in
  208. +Table~\ref{tab:specific-fortran-proc-names} on page~\pageref{tab:specific-fortran-proc-names}.
  209. +Case is not significant in the names.
  210.  
  211. -%%HEADER
  212. -%%SKIP
  213. -%%ENDHEADER
  214. -\begin{verbatim}
  215. - INTERFACE
  216. - SUBROUTINE MPI_Send(...) BIND(C,NAME='MPI_Send_f08')
  217. -\end{verbatim}
  218. +\begin{table}[htbp]
  219. +\begin{center}
  220. +\begin{tabular}{llp{10cm}}
  221. +\hline
  222. +No. & Specific pro- & Calling convention \\
  223. + & cedure name & \\
  224. +\hline
  225. +1A & \ffunc{MPI\_Isend\_f08}
  226. + & Fortran interface and arguments, as in Annex~\ref{sec:lang:fortran-mpi-f08-module}, except that
  227. + in routines with a choice buffer dummy argument, this
  228. + dummy argument is implemented with non-standard
  229. + extensions like \texttt{!\$PRAGMA IGNORE\_TKR}, which
  230. + provides a call-by-reference argument without type, kind,
  231. + and dimension checking.
  232. +\\[2pt]
  233. +1B & \ffunc{MPI\_Isend\_f08ts}
  234. + & Fortran interface and arguments, as in Annex~\ref{sec:lang:fortran-mpi-f08-module},
  235. + but only for routines with one or more choice buffer dummy arguments;
  236. + these dummy arguments are implemented
  237. + with \texttt{TYPE(*), DIMENSION(..)}.
  238. +\\[2pt]
  239. +2A & \ffunc{MPI\_ISEND}
  240. + & Fortran interface and arguments, as in Annex~\ref{sec:lang:fortran-mpifh-and-mpi-module}, except that
  241. + in routines with a choice buffer dummy argument, this
  242. + dummy argument is implemented with non-standard
  243. + extensions like \texttt{!\$PRAGMA IGNORE\_TKR}, which
  244. + provides a call-by-reference argument without type, kind,
  245. + and dimension checking.
  246. +\\[2pt]
  247. +2B & \ffunc{MPI\_ISEND\_FTS}
  248. + & Fortran interface and arguments, as in Annex~\ref{sec:lang:fortran-mpifh-and-mpi-module},
  249. + but only for routines with one or more choice buffer dummy arguments;
  250. + these dummy arguments are implemented
  251. + with \texttt{TYPE(*), DIMENSION(..)}.
  252. +\\
  253. +\hline
  254. +\end{tabular}
  255. +\vspace*{-5mm}
  256. +\end{center}
  257. +\caption{Specific Fortran procedure names and related calling conventions.
  258. +\mpifunc{MPI\_ISEND} is used as an example.
  259. +For routines without choice buffers, only 1A and 2A apply.}
  260. +\label{tab:specific-fortran-proc-names}
  261. +\end{table}
  262.  
  263. - \item
  264. - With the Fortran \code{mpi\_f08} module,
  265. - if \const{MPI\_SUBARRAYS\_SUPPORTED} equals \ftype{.FALSE.}
  266. - (i.e., with a preliminary implementation of this module without TS 29113):
  267. +Note that for the deprecated routines in
  268. +Section~\ref{sec:deprecated:since20} on page~\pageref{sec:deprecated:since20},
  269. +which are reported only in
  270. +Annex~\ref{sec:lang:fortran-mpifh-and-mpi-module},
  271. +scheme 2A is utilized in the \texttt{mpi} module and \texttt{mpif.h},
  272. +and also in the \texttt{mpi\_f08} module.
  273.  
  274. - The linker name of each routine is defined through the
  275. - linker name mapping of the Fortran compiler for the name
  276. - defined when subarrays are supported. For example,
  277. - \code{MPI\_Send\_f08} may be mapped to \code{mpi\_send\_f08\_\_}.
  278. - Example:
  279. -
  280. -%%HEADER
  281. -%%SKIP
  282. -%%ENDHEADER
  283. -\begin{verbatim}
  284. - INTERFACE MPI_Send
  285. - SUBROUTINE MPI_Send_f08(...)
  286. -\end{verbatim}
  287. -
  288. -\item
  289. - With the Fortran \code{mpi} module or \code{mpif.h} include file,
  290. - if \const{MPI\_SUBARRAYS\_SUPPORTED} equals \ftype{.FALSE.}:
  291. +To set \const{MPI\_SUBARRAYS\_SUPPORTED} to \ftype{.TRUE.}
  292. +within a Fortran support method, it is required that
  293. +all non-blocking and split-collective routines with buffer arguments
  294. +are implemented according to 1B and 2B, i.e.,
  295. +with \ffunc{MPI\_Xxxx\_f08ts} in the \texttt{mpi\_f08} module,
  296. +and with \ffunc{MPI\_XXXX\_FTS} in the \texttt{mpi} module
  297. +and the \texttt{mpif.h} include file.
  298.  
  299. - The linker name of each routine is defined through the
  300. - linker-name mapping of the Fortran compiler.
  301. - For example,
  302. - \mpifunc{MPI\_SEND} may be mapped to \code{mpi\_send\_\_}.
  303. - Example:
  304. +The \texttt{mpi} and \texttt{mpi\_f08} modules and the \texttt{mpif.h}
  305. +include file
  306. +will each correspond to exactly one implementation scheme from
  307. +Table~\ref{tab:specific-fortran-proc-names} on page~\pageref{tab:specific-fortran-proc-names}.
  308. +However, the \MPI/ library may contain multiple implementation schemes from
  309. +Table~\ref{tab:specific-fortran-proc-names}.
  310. +\begin{implementors}
  311. +This may be desirable for backwards binary compatibility
  312. +in the scope of a single \MPI/ implementation, for example.
  313. +\end{implementors}
  314.  
  315. -%%HEADER
  316. -%%SKIP
  317. -%%ENDHEADER
  318. -\begin{verbatim}
  319. - INTERFACE
  320. - SUBROUTINE MPI_SEND(...)
  321. -\end{verbatim}
  322. -
  323. -\item
  324. - With the Fortran \code{mpi} module or \code{mpif.h} include file,
  325. - if \const{MPI\_SUBARRAYS\_SUPPORTED} equals \ftype{.TRUE.}:
  326. -
  327. - The Fortran binding must use BIND(C) interfaces with
  328. - an interface name identical to the language independent name,
  329. - e.g., \mpifunc{MPI\_SEND}.
  330. - The linker name is a combination of the C name and an
  331. - \code{\_f} suffix, e.g., \code{MPI\_Send\_f}.
  332. - Prototype example:
  333. -
  334. -%%HEADER
  335. -%%SKIP
  336. -%%ENDHEADER
  337. -\begin{verbatim}
  338. - INTERFACE
  339. - SUBROUTINE MPI_SEND(...) BIND(C,NAME='MPI_Send\_f')
  340. -\end{verbatim}
  341. -\end{itemize}
  342. -If the support of subarrays is different for
  343. -the \code{mpi} module and the \code{mpif.h} include file,
  344. -then both linker-name methods can be used in the same application.
  345. -If the application also uses the \code{mpi\_f08} module
  346. -and was compiled with this module
  347. -partially before and after the subarrays were supported,
  348. -then all four interfaces are used within the same application.
  349. -
  350. \begin{rationale}
  351. After a compiler provides the facilities from TS 29113, i.e.,
  352. -\code{TYPE(*), DIMENSION(..)},
  353. +\texttt{TYPE(*), DIMENSION(..)},
  354. it is possible to change the bindings within a Fortran support method
  355. to support subarrays
  356. -without recompiling the complete application.
  357. +without recompiling the complete application
  358. +provided that the previous interfaces
  359. +with their specific procedure names are still included in the library.
  360. Of course, only recompiled routines can benefit from the
  361. added facilities.
  362. There is no binary compatibility conflict
  363. -because each interface uses its own linker names and
  364. -all interfaces use the same constants and type definitions.
  365. +because each interface uses its own
  366. +specific procedure names and
  367. +all interfaces use the same constants
  368. +(except the value of \const{MPI\_SUBARRAYS\_SUPPORTED} and \const{MPI\_ASYNC\_PROTECTS\_NONBLOCKING})
  369. +and type definitions.
  370. +After a compiler also ensures that buffer arguments of nonblocking \MPI/ operations
  371. +can be protected through the \ftype{ASYNCHRONOUS} attribute,
  372. +and the procedure declarations in the \texttt{mpi\_f08} and \texttt{mpi} module
  373. +and the \texttt{mpif.h} include file declare choice buffers
  374. +with the \ftype{ASYNCHRONOUS} attribute, then
  375. +the value of \const{MPI\_ASYNC\_PROTECTS\_NONBLOCKING} can be switched to \ftype{.TRUE.}
  376. +in the module definition and include file.
  377. \end{rationale}
  378.  
  379. -A user-written or middleware profiling routine that
  380. -is written according to the same binding rules
  381. -will have the same linker name, and therefore,
  382. +\begin{users}
  383. +Partial recompilation of user applications when upgrading \MPI/ implementations
  384. +is a highly complex and subtle topic.
  385. +Users are strongly advised to consult their \MPI/ implementation's documentation
  386. +to see exactly what is --- and what is not --- supported.
  387. +\end{users}
  388. +
  389. +Within the \texttt{mpi\_f08} and \texttt{mpi} modules and \texttt{mpif.h},
  390. +for all \MPI/ procedures, a second
  391. +procedure with the same calling conventions shall be
  392. +supplied, except that the name is modified by prefixing with the
  393. +letter ``P'', e.g., \ffunc{PMPI\_Isend}\mpifuncindex{PMPI\_ISEND}.
  394. +The specific procedure names
  395. +for these \mpifunc{PMPI\_}\mpiskipfunc{Xxxx} procedures must be different from the
  396. +specific procedure names for the \mpiskipfunc{MPI\_Xxxx} procedures
  397. +and are not specified by this standard.
  398. +
  399. +A user-written or middleware profiling routine
  400. +should provide the same specific Fortran
  401. +procedure names and calling conventions, and therefore
  402. can interpose itself as the \MPI/ library routine.
  403. -The profiling routine can internally call the matching \mpicode{PMPI}
  404. +The profiling routine can internally call the matching \textsf{PMPI}
  405. routine with any of its existing bindings,
  406. -except for routines that have callback routine dummy arguments.
  407. -In this case, the profiling software must use the same Fortran
  408. +except for routines that have callback routine dummy arguments,
  409. +choice buffer arguments, or that are attribute caching routines
  410. +\mpifuncindex{MPI\_COMM\_SET\_ATTR}\mpifuncindex{MPI\_COMM\_GET\_ATTR}%
  411. +\mpifuncindex{MPI\_WIN\_SET\_ATTR}\mpifuncindex{MPI\_CWIN\_GET\_ATTR}%
  412. +\mpifuncindex{MPI\_TYPE\_SET\_ATTR}\mpifuncindex{MPI\_TYPE\_GET\_ATTR}%
  413. +(\mpiskipfunc{MPI\_\textrm{\{}COMM$|$WIN$|$TYPE\textrm{\}}\_\textrm{\{}SET$|$GET\textrm{\}}\_ATTR}).
  414. +In this case, the profiling software
  415. +should
  416. +invoke the corresponding \textsf{PMPI} routine using
  417. +the same Fortran
  418. support method as used in the calling application program,
  419. -because the C, \code{mpi\_f08} and \code{mpi} callback
  420. -prototypes are different.
  421. +because the C, \texttt{mpi\_f08} and \texttt{mpi} callback
  422. +prototypes are different or the meaning of the choice buffer
  423. +or \mpiarg{attribute\_val} arguments are different.
  424.  
  425. -\begin{users}
  426. -This advice is mainly for tool writers.
  427. -Even if an \MPI/ library supports subarrays in all three Fortran
  428. -support methods, a portable profiling layer should also provide
  429. -the two interfaces for \const{MPI\_SUBARRAYS\_SUPPORTED}==\ftype{.FALSE.} to
  430. -support older binary user routines that were compiled before
  431. -TS 29113 level support was availabile.
  432. +\begin{users}
  433. +Although for each support method and \MPI/ routine
  434. +(e.g., \mpifunc{MPI\_ISEND} in \texttt{mpi\_f08}),
  435. +multiple routines may need to be provided to intercept the
  436. +specific procedures in the \MPI/ library
  437. +(e.g., \ffunc{MPI\_Isend\_f08} and \ffunc{MPI\_Isend\_f08ts}),
  438. +each profiling routine itself uses only one support method
  439. +(e.g., \texttt{mpi\_f08})
  440. +and calls the real \MPI/ routine through the one
  441. +\textsf{PMPI} routine defined in this support method
  442. +(i.e., \ffunc{PMPI\_Isend} in this example).
  443. +\end{users}
  444.  
  445. -If a user application calls \mpifunc{MPI\_SEND}, then the
  446. -chosen Fortran support method together with
  447. -the \MPI/ implementation decision about
  448. -\const{MPI\_SUBARRAYS\_SUPPORTED} imply, to which
  449. -linker name the compiler will translate this call, i.e.,
  450. -whether the application calls
  451. -\code{mpi\_send\_\_}, or \code{MPI\_Send\_f}, or
  452. -\code{mpi\_send\_f08\_\_}, or \code{MPI\_Send\_f08}.
  453. -If the profiling layer wants to be independent of
  454. -the decision of the user program and \MPI/ implementation,
  455. -then it should provide all four routines.
  456. -For example:
  457. -%%HEADER
  458. -%%SKIP
  459. -%%ENDHEADER
  460. -\begin{verbatim}
  461. - SUBROUTINE MPI_SEND(...) BIND(C,NAME='MPI_Send_f')
  462. - USE mpi
  463. - CALL PMPI_SEND(...)
  464. - END SUBROUTINE
  465. -\end{verbatim}
  466. -The \MPI/ library must provide the \mpifunc{PMPI\_SEND} routine
  467. -according to the same rules as for providing the \mpifunc{MPI\_SEND} routine.
  468. -\end{users}
  469. -
  470. \begin{implementors}
  471. -If an implementation provides in a first step two sets of routines,
  472. -one for the \code{mpi} module and \code{mpif.h},
  473. -and the other for the \code{mpi\_f08} module, and both sets
  474. -without TS 29113, i.e., \const{MPI\_SUBARRAYS\_SUPPORTED} equals \ftype{.FALSE.},
  475. -and the implementor wants to add a TS 29113 based set of routines,
  476. -then it is not necessary to add two full sets of routines.
  477. -For full quality, it is enough to implement in each set only those
  478. -routines that have a choice buffer argument.
  479. -\end{implementors}
  480. -
  481. -In the case that a Fortran binding consists of multiple
  482. -routines through function overloading, the base names
  483. -of overloaded routines are appended by a suffix
  484. -indicating the difference in the argument list.
  485. -For example, \mpifunc{MPI\_ALLOC\_MEM}
  486. -(in the \code{mpi} module and \code{mpif.h}) has an
  487. -\ftype{INTEGER(KIND=...)} \mpiarg{baseptr} argument without a suffix.
  488. -This routine is overloaded by a routine with
  489. -\ftype{TYPE(C\_PTR)} \mpiarg{baseptr}
  490. -and the suffix \code{\_CPTR}.
  491. -The implied linker name base is \mpifunc{MPI\_ALLOC\_MEM\_CPTR}.
  492. -It is mapped to the linker names
  493. -\code{MPI\_Alloc\_mem\_cptr\_f},
  494. -and, e.g.,
  495. -\code{mpi\_alloc\_mem\_cptr\_\_}.
  496. -Note that these routines are always called
  497. -via the interface name \mpifunc{MPI\_ALLOC\_MEM}
  498. -by the application within all Fortran support methods.
  499. -
  500. -For routines without \ftype{ASYNCHRONOUS} choice buffers and that are not
  501. -predefined callback routines,
  502. -the implementor can freely choose to implement the routines
  503. -according to the rules for \const{MPI\_SUBARRAYS\_SUPPORTED} equals \ftype{.TRUE.}
  504. -or \ftype{.FALSE.}, provided that the following rule about routine grouping
  505. -is fulfilled.
  506. -The implementation of routines with \ftype{ASYNCHRONOUS} choice buffers
  507. -depends on the rules for the provided Fortran support method and
  508. -language level of the underlying compiler.
  509. -Predefined callback routines for the \code{mpi\_f08} module must be
  510. -implemented with \ftype{BIND(C)} interfaces, and for the \code{mpi} module
  511. -and \code{mpif.h} without \ftype{BIND(C)}.
  512. -
  513. -Similar \MPI/ routines are grouped together for linker symbol scheme
  514. -classification.
  515. -If the peer routine of a group is available within an \MPI/ library
  516. -with one of its possible linker names then
  517. -all of the routines in this group must be provided according
  518. -to the same linker name scheme.
  519. -If the peer routine is not available through
  520. -a linker name scheme then all other routines
  521. -in the group must not be available through this scheme.
  522. -
  523. -\noindent
  524. -Peer routines and their routine groups:
  525. -
  526. -\noindent
  527. -\begin{tabular}{lp{8cm}}
  528. -{ \mpifunc{MPI\_ALLOC\_MEM}} \dotfill &
  529. - \rule{0mm}{1mm}\mpifunc{MPI\_ALLOC\_MEM},
  530. - \mpifunc{MPI\_WIN\_ALLOCATE},
  531. - \mpifunc{MPI\_WIN\_SHARED\_ALLOCATE}, and
  532. - \mpifunc{MPI\_WIN\_SHARED\_QUERY}. \\
  533. -{ \mpifunc{MPI\_FREE\_MEM}} \dotfill &
  534. - Only this routine is in this group. \\
  535. -{ \mpifunc{MPI\_GET\_ADDRESS}} \dotfill &
  536. - Only this routine is in this group. \\
  537. -{ \mpifunc{MPI\_SEND}} \dotfill &
  538. - All routines with choice buffer arguments that
  539. - are not declared as \ftype{ASYNCHRONOUS} within the \code{mpi\_f08} module. \\
  540. -{ \mpifunc{MPI\_ISEND}} \dotfill &
  541. - All routines with choice buffer arguments that
  542. - are declared as \ftype{ASYNCHRONOUS} within the \code{mpi\_f08} module. \\
  543. -{ \mpifunc{MPI\_OP\_CREATE}} \dotfill &
  544. - Only this routine is in this group. \\
  545. -{ \mpifunc{MPI\_REGISTER\_DATAREP}} \dotfill &
  546. - Only this routine is in this group. \\
  547. -{ \mpifunc{MPI\_COMM\_KEYVAL\_CREATE}} \dotfill &
  548. - All other routines with callback function arguments. \\
  549. -{ \mpifunc{MPI\_COMM\_DUP\_FN}\cdeclindex{MPI\_COMM\_DUP\_FN}} \dotfill &
  550. - All predefined callback routines. \\
  551. -{ \mpifunc{MPI\_COMM\_RANK}} \dotfill &
  552. - All other \MPI/ routines.
  553. -\end{tabular}
  554. -
  555. -\begin{implementors}
  556. - Removed interfaces (see Chapter~\ref{chap:removed}) are in the same
  557. - routine group as their corresponding replacement functions.
  558. -\end{implementors}
  559. -
  560. -Additionally, four C preprocessor macros are available
  561. -in \code{mpi.h} for each routine group.
  562. -The name of the macros are the peer routine name written as in the
  563. -list above and appended
  564. -with one of the following suffixes and meanings:
  565. -
  566. -\noindent
  567. -\begin{tabular}{lp{10cm}}
  568. -{ \cfunc{\_mpi\_f08\_BIND\_C}} &
  569. - The macro is set to 1 if the \ftype{BIND(C)} linker name with
  570. - the linker suffix \ffunc{\_f08} is available for all routines
  571. - within this group (e.g., \ffunc{MPI\_Send\_f08}), otherwise it is set to 0.\\
  572. -{ \cfunc{\_mpi\_f08\_BIND\_F}} &
  573. - The macro is set to 1 if the Fortran linker name with
  574. - the linker suffix \ffunc{\_f08} is available for all routines
  575. - within this group (e.g., \ffunc{mpi\_send\_f08\_\_}), otherwise it is set to 0.\\
  576. -{ \cfunc{\_mpi\_BIND\_C}} \dotfill &
  577. - The macro is set to 1 if the \ftype{BIND(C)} linker name with
  578. - the linker suffix \ffunc{\_f} is available for all routines
  579. - within this group (e.g., \ffunc{MPI\_Send\_f}), otherwise it is set to 0.\\
  580. -{ \cfunc{\_mpi\_BIND\_F}} \dotfill &
  581. - The macro is set to 1 if the Fortran linker name without
  582. - a linker suffix is available for all routines
  583. - within this group (e.g., \ffunc{mpi\_send\_\_}), otherwise it is set to 0.
  584. -\end{tabular}
  585. -
  586. -\noindent
  587. -For example
  588. -%%HEADER
  589. -%%SKIP
  590. -%%ENDHEADER
  591. -\begin{verbatim}
  592. - ...
  593. - #define MPI_SEND_mpi_f08_BIND_C 0
  594. - #define MPI_SEND_mpi_f08_BIND_F 1
  595. - #define MPI_SEND_mpi_BIND_C 0
  596. - #define MPI_SEND_mpi_BIND_F 1
  597. -
  598. - #define MPI_ISEND_mpi_f08_BIND_C 1
  599. - #define MPI_ISEND_mpi_f08_BIND_F 1
  600. - #define MPI_ISEND_mpi_BIND_C 1
  601. - #define MPI_ISEND_mpi_BIND_F 1
  602. - ...
  603. - #define MPI_COMM_DUP_FN_mpi_f08_BIND_C 1
  604. - #define MPI_COMM_DUP_FN_mpi_f08_BIND_F 0
  605. - #define MPI_COMM_DUP_FN_mpi_BIND_C 0
  606. - #define MPI_COMM_DUP_FN_mpi_BIND_F 1
  607. - ...
  608. -\end{verbatim}
  609. -shows, that
  610. +If all of the following conditions are fulfilled:
  611. \begin{itemize}
  612. -\item the routines in the \mpifunc{MPI\_SEND} group are only available through
  613. - their Fortran linker names (e.g., \code{mpi\_send\_f08\_\_}, \code{mpi\_send\_\_},
  614. - \code{mpi\_recv\_f08\_\_}, \code{mpi\_recv\_\_}, $\ldots$),
  615. -\item the routines in the \mpifunc{MPI\_ISEND} group are available with all four
  616. - interfaces: the \MPI/ library, the \code{mpi\_f08} and \code{mpi} modules (that
  617. - provide the TS 29113 quality), and this \MPI/ library supports
  618. - application routines that are compiled with an older \MPI/ library
  619. - version with \cfunc{\_BIND\_C} set to 0 and \cfunc{\_BIND\_F} set to 1.
  620. -\end{itemize}
  621. -For the predefined callbacks, there is no choice, because
  622. -the interfaces must fit to the callback function prototypes
  623. -which are \ftype{BIND(C)} based for \code{mpi\_f08} and
  624. -without \ftype{BIND(C)} for the mpi \code{module} and \code{mpif.h}.
  625. -
  626. -\begin{implementors}
  627. -If all following conditions are fulfilled
  628. -(which is the case for most compilers):
  629. -\begin{itemize}
  630. -\item the handles in the \code{mpi\_f08} module occupy one Fortran
  631. +\item the handles in the \texttt{mpi\_f08} module occupy one Fortran
  632. numerical storage unit (same as an \ftype{INTEGER} handle),
  633. \item the internal argument passing mechanism used to pass an actual \mpiarg{ierror}
  634. argument to a non-optional \mpiarg{ierror} dummy argument is binary
  635. @@ -897,38 +747,176 @@
  636. \item the internal argument passing mechanism for \ftype{ASYNCHRONOUS} and
  637. non-\ftype{ASYNCHRONOUS} arguments is the same,
  638. \item the internal routine call mechanism is the same for
  639. - the Fortran and the C compilers for which the \MPI/ library is compiled,
  640. + the Fortran and the C compilers for which the MPI library is compiled,
  641. \item the compiler does not provide TS 29113,
  642. \end{itemize}
  643. -then for the routine groups, the implementor may use the same
  644. +then the implementor may use the same
  645. internal routine implementations for all Fortran support
  646. -methods but with several different linker names.
  647. -For TS 29113 quality, new routines are needed only for
  648. -the routine group of \mpifunc{MPI\_ISEND}.
  649. -Typical settings for
  650. -\cfunc{\_mpi\_f08\_BIND\_C} / \cfunc{\_mpi\_f08\_BIND\_F} / \cfunc{\_mpi\_BIND\_C} / \cfunc{\_mpi\_BIND\_F} may be:
  651. +methods but with several different specific procedure names.
  652. +If the accompanying Fortran compiler supports TS 29113,
  653. +then the new routines are needed only for routines with
  654. +choice buffer arguments. % 9/18/13 replacement for ``TS 29113 quality''
  655. +\end{implementors}
  656. +
  657. +\begin{implementors}
  658. +In the Fortran support method \texttt{mpif.h},
  659. +compile-time argument checking
  660. +can be also implemented for all routines.
  661. +For \texttt{mpif.h}, the argument names are not specified through the \MPI/ standard,
  662. +i.e., only positional argument lists are defined, and not key-word based lists.
  663. +Due to the rule that \texttt{mpif.h}
  664. +must be valid for fixed and free source form,
  665. +the subroutine declaration is restricted to one line with 72 characters.
  666. +To keep the argument lists short, each argument name can be shortened
  667. +to a minimum of one character. With this, the two longest subroutine
  668. +declaration statements are
  669. +%23456789012345678901234567890123456789012345678901234567890123456789012
  670. +\begin{verbatim}
  671. + SUBROUTINE PMPI_Dist_graph_create_adjacent(a,b,c,d,e,f,g,h,i,j,k)
  672. + SUBROUTINE PMPI_Rget_accumulate(a,b,c,d,e,f,g,h,i,j,k,l,m,n)
  673. +\end{verbatim}
  674. +with 71 and 66 characters.
  675. +With buffers implemented with TS 29113, the specific procedure names have an
  676. +additional postfix. The longest of such interface definitions is
  677. +\begin{verbatim}
  678. + INTERFACE PMPI_Rget_accumulate
  679. + SUBROUTINE PMPI_Rget_accumulate_fts(a,b,c,d,e,f,g,h,i,j,k,l,m,n)
  680. +\end{verbatim}
  681. +%23456789012345678901234567890123456789012345678901234567890123456789012
  682. +with 70 characters.
  683. +In principle, continuation lines would be possible in \texttt{mpif.h}
  684. +(spaces in columns 73--131, \& in column 132, and in column 6 of the
  685. +continuation line) but this would not be valid if the source line
  686. +length is extended with a compiler flag to 132 characters.
  687. +Column 133 is also not available for the continuation character because
  688. +lines longer than 132 characters are invalid with some compilers by default.
  689.  
  690. -\noindent
  691. -{\small
  692. -\begin{tabular}{lllll}
  693. - & & & Upgrade for & New impl.\\
  694. - & Without & Upgrade to& strided data& with \\
  695. - & TS 29113& TS 29113 & optimization& TS 29113 \\[3pt]
  696. -\cfunc{MPI\_ALLOC\_MEM\_...} \dotfill & 0/1/0/1 & 0/1/0/1 & 0/1/0/1 & 1/0/1/0 \\
  697. -\cfunc{MPI\_FREE\_MEM\_...} \dotfill & 0/1/0/1 & 0/1/0/1 & 0/1/0/1 & 1/0/1/0 \\
  698. -\cfunc{MPI\_GET\_ADDRESS\_...} \dotfill & 0/1/0/1 & 0/1/0/1 & 0/1/0/1 & 1/0/1/0 \\
  699. -\cfunc{MPI\_SEND\_...} \dotfill & 0/1/0/1 & 0/1/0/1 & \textbf{1}/1/\textbf{1}/1 & 1/0/1/0 \\
  700. -\cfunc{MPI\_ISEND\_...} \dotfill & 0/1/0/1 & \textbf{1}/1/\textbf{1}/1 & 1/1/1/1 & 1/0/1/0 \\
  701. -\cfunc{MPI\_OP\_CREATE\_...} \dotfill & 0/1/0/1 & 0/1/0/1 & 0/1/0/1 & 1/0/1/0 \\
  702. -\cfunc{MPI\_REGISTER\_DATAREP\_...} \dotfill & 0/1/0/1 & 0/1/0/1 & 0/1/0/1 & 1/0/1/0 \\
  703. -\cfunc{MPI\_COMM\_KEYVAL\_CREATE\_...} & 0/1/0/1 & 0/1/0/1 & 0/1/0/1 & 1/0/1/0 \\
  704. -\cfunc{MPI\_COMM\_DUP\_FN\_...} \dotfill & \textbf{1}/\textbf{0}/0/1 & 1/0/0/1 & 1/0/0/1 & 1/0/0/1 \\
  705. -\cfunc{MPI\_COMM\_RANK\_...} \dotfill & 0/1/0/1 & 0/1/0/1 & 0/1/0/1 & 1/0/1/0
  706. -\end{tabular}
  707. -}% \small
  708. +The longest specific procedure names are
  709. +\ffunc{PMPI\_Dist\_graph\_create\_adjacent\_f08}
  710. +% 1234 56789 012345 6789012 345678901 2345
  711. +and
  712. +\ffunc{PMPI\_File\_write\_ordered\_begin\_f08ts}
  713. +% 1234 56789 012345 67890123 456789 012345
  714. +both with 35 characters in the \texttt{mpi\_f08} module.
  715. +
  716. +For example, the interface specifications together with the specific procedure names
  717. +can be implemented with
  718. +\mpifuncindex{MPI\_COMM\_RANK\_F08}%
  719. +\mpifuncindex{MPI\_COMM\_RANK}%
  720. +{\small
  721. +\begin{verbatim}
  722. +MODULE mpi_f08
  723. + TYPE, BIND(C) :: MPI_Comm
  724. + INTEGER :: MPI_VAL
  725. + END TYPE MPI_Comm
  726. + ...
  727. + INTERFACE MPI_Comm_rank ! (as defined in Chapter 6)
  728. + SUBROUTINE MPI_Comm_rank_f08(comm, rank, ierror)
  729. + IMPORT :: MPI_Comm
  730. + TYPE(MPI_Comm), INTENT(IN) :: comm
  731. + INTEGER, INTENT(OUT) :: rank
  732. + INTEGER, OPTIONAL, INTENT(OUT) :: ierror
  733. + END SUBROUTINE
  734. + END INTERFACE
  735. +END MODULE mpi_f08
  736. +
  737. +MODULE mpi
  738. + INTERFACE MPI_Comm_rank ! (as defined in Chapter 6)
  739. + SUBROUTINE MPI_Comm_rank(comm, rank, ierror)
  740. + INTEGER, INTENT(IN) :: comm ! The INTENT may be added although
  741. + INTEGER, INTENT(OUT) :: rank ! it is not defined in the
  742. + INTEGER, INTENT(OUT) :: ierror ! official routine definition.
  743. + END SUBROUTINE
  744. + END INTERFACE
  745. +END MODULE mpi
  746. +\end{verbatim}
  747. +}%\small
  748. +And if interfaces are provided in \texttt{mpif.h}, they might look like this
  749. +(outside of any module and in fixed source format):
  750. +{\small
  751. +\begin{verbatim}
  752. +!23456789012345678901234567890123456789012345678901234567890123456789012
  753. + INTERFACE MPI_Comm_rank ! (as defined in Chapter 6)
  754. + SUBROUTINE MPI_Comm_rank(comm, rank, ierror)
  755. + INTEGER, INTENT(IN) :: comm ! The argument names may be
  756. + INTEGER, INTENT(OUT) :: rank ! shortened so that the
  757. + INTEGER, INTENT(OUT) :: ierror ! subroutine line fits to the
  758. + END SUBROUTINE ! maximum of 72 characters.
  759. + END INTERFACE
  760. +\end{verbatim}
  761. +}%\small
  762. +\end{implementors}
  763. +
  764. +\begin{users}
  765. +The following is an example of how
  766. +a user-written or middleware profiling routine
  767. +can be implemented:
  768. +{\small
  769. +\begin{verbatim}
  770. +SUBROUTINE MPI_Isend_f08ts(buf,count,datatype,dest,tag,comm,request,ierror)
  771. + USE :: mpi_f08, my_noname => MPI_Isend_f08ts
  772. + TYPE(*), DIMENSION(..), ASYNCHRONOUS :: buf
  773. + INTEGER, INTENT(IN) :: count, dest, tag
  774. + TYPE(MPI_Datatype), INTENT(IN) :: datatype
  775. + TYPE(MPI_Comm), INTENT(IN) :: comm
  776. + TYPE(MPI_Request), INTENT(OUT) :: request
  777. + INTEGER, OPTIONAL, INTENT(OUT) :: ierror
  778. + ! ... some code for the begin of profiling
  779. + call PMPI_Isend (buf, count, datatype, dest, tag, comm, request, ierror)
  780. + ! ... some code for the end of profiling
  781. +END SUBROUTINE MPI_Isend_f08ts
  782. +\end{verbatim}
  783. +}%\small
  784. +Note that this routine is used to intercept the existing specific
  785. +procedure name \ffunc{MPI\_Isend\_f08ts} in the \MPI/ library.
  786. +This routine must not be part of a module.
  787. +This routine itself calls \ffunc{PMPI\_Isend}\mpifuncindex{PMPI\_ISEND}.
  788. +The \texttt{USE} of the \texttt{mpi\_f08} module is needed for
  789. +definitions of handle types and the interface for \ffunc{PMPI\_Isend}.
  790. +However, this module also contains an interface definition for
  791. +the specific procedure name \ffunc{MPI\_Isend\_f08ts} that conflicts
  792. +with the definition of this profiling routine (i.e., the name is
  793. +doubly defined).
  794. +Therefore, the \texttt{USE} here specifically excludes the interface
  795. +from the module by renaming the unused routine name in the
  796. +\texttt{mpi\_f08} module into ``\texttt{my\_noname}'' in the scope of this routine.
  797. +\end{users}
  798.  
  799. +\begin{users}
  800. +The \textsf{PMPI} interface allows intercepting \MPI/ routines.
  801. +For example, an additional \mpifunc{MPI\_ISEND} profiling wrapper
  802. +can be provided that is called by the
  803. +application and internally calls \mpifunc{PMPI\_ISEND}.
  804. +There are two typical use cases: a profiling layer that is developed
  805. +independently from the application and the \MPI/ library,
  806. +and profiling routines that are part of the application
  807. +and have access to the application data.
  808. +With \MPIIIIDOTO/, new Fortran interfaces and implementation schemes
  809. +were introduced that have several implications on how Fortran
  810. +\MPI/ routines are internally implemented and optimized.
  811. +For profiling layers, these schemes imply that several
  812. +internal interfaces with different specific procedure names
  813. +may need to be intercepted,
  814. +as shown in the example code above.
  815. +Therefore, for wrapper routines that
  816. +are part of a Fortran application,
  817. +it may be more convenient to make the name shift within
  818. +the application, i.e., to substitute the call to the
  819. +\MPI/ routine (e.g., \mpifunc{MPI\_ISEND}) by a call to a user-written
  820. +profiling wrapper with a new name (e.g., \ffunc{X\_MPI\_ISEND})
  821. +and to call the Fortran \mpifunc{MPI\_ISEND} from this wrapper,
  822. +instead of using the \textsf{PMPI} interface.
  823. +\end{users}
  824. +
  825. +\begin{implementors}
  826. + An implementation that provides a Fortran interface must provide a
  827. + combination of \MPI/ library and module or include file that uses
  828. + the specific procedure names as described in
  829. + Table~\ref{tab:specific-fortran-proc-names} on
  830. + page~\pageref{tab:specific-fortran-proc-names} so that the \MPI/
  831. + Fortran routines are interceptable as described above.
  832. \end{implementors}
  833. -
  834. +
  835. \subsection{\MPI/ for Different Fortran Standard Versions}
  836. \label{sec:f90:different-fortran-versions}
  837.  
  838. @@ -986,7 +974,6 @@
  839. In this preliminary interface of \mpicode{S1}, the following changes are
  840. necessary:
  841. \begin{itemize}
  842. - \item The routines are not \ftype{BIND(C)}.
  843. \item \code{TYPE(*), DIMENSION(..)} is substituted by
  844. non-standardized extensions like \ftype{!\$PRAGMA IGNORE\_TKR}.
  845. \item The \ftype{ASYNCHRONOUS} attribute is omitted.
  846. @@ -994,7 +981,7 @@
  847. substituted by \ftype{EXTERNAL}.
  848. \end{itemize}
  849. \item
  850. - The linker names are specified in \sectionref{sec:f90:linker-names}.
  851. + The specific procedure names are specified in \sectionref{sec:f90:linker-names}.
  852. \item
  853. Due to the rules specified in \sectionref{sec:f90:linker-names},
  854. choice buffer declarations should be implemented only with
  855. @@ -1049,7 +1036,6 @@
  856. \begin{itemize}
  857. \item Interoperability with C, i.e.,
  858. \begin{itemize}
  859. - \item \ftype{BIND(C, NAME='...')} interfaces.
  860. \item \ftype{BIND(C)} derived types.
  861. \item The \ftype{ISO\_C\_BINDING} intrinsic type \ftype{C\_PTR}
  862. and routine \ftype{C\_F\_POINTER}.
  863. @@ -1056,6 +1042,9 @@
  864. \end{itemize}
  865. \item The ability to define an \ftype{ABSTRACT INTERFACE}
  866. and to use it for \ftype{PROCEDURE} dummy arguments.
  867. + \item The ability to overload the operators \code{.EQ.} and
  868. + \code{.NE.} to allow the comparison of derived types (used in
  869. + \MPIIIIDOTO/ for \MPI/ handles).
  870. \item The \ftype{ASYNCHRONOUS} attribute is available to protect
  871. Fortran asynchronous I/O.
  872. This feature is not yet used by \MPI/, but it is the basis
  873. @@ -1079,12 +1068,11 @@
  874. For \mpicode{S1}, only a preliminary implementation is possible.
  875. The following changes are necessary:
  876. \begin{itemize}
  877. - \item The routines are not \ftype{BIND(C)}.
  878. \item \code{TYPE(*), DIMENSION(..)} is substituted by
  879. non-standardized extensions like \ftype{!\$PRAGMA IGNORE\_TKR}.
  880. \end{itemize}
  881. \item
  882. - The linker names are specified in \sectionref{sec:f90:linker-names}.
  883. + The specific procedure names are specified in \sectionref{sec:f90:linker-names}.
  884. \item
  885. With \mpicode{S1}, the \ftype{ASYNCHRONOUS} is required as specified in
  886. the second Fortran interfaces.
  887. @@ -1115,10 +1103,6 @@
  888. \item \code{TYPE(*), DIMENSION(..)} is available.
  889. \item The \ftype{ASYNCHRONOUS} attribute is extended to protect also
  890. nonblocking \MPI/ communication.
  891. - \item \ftype{OPTIONAL} dummy arguments are allowed in combination with
  892. - \ftype{BIND(C)} interfaces.
  893. - \item \ftype{CHARACTER(LEN=*)} dummy arguments are allowed in combination with
  894. - \ftype{BIND(C)} interfaces.
  895. \item The array dummy argument of the \ftype{ISO\_C\_BINDING} intrinsic
  896. \ftype{C\_F\_POINTER} is not restricted to Fortran types for which
  897. a corresponding type in C exists.
  898. @@ -1265,44 +1249,18 @@
  899. nor on the declaration of application routines that are involved
  900. in invoking \MPI/ procedures.
  901. \end{itemize}
  902. -All of these rules are valid independently of whether
  903. -the \MPI/ routine interfaces in the \code{mpi\_f08} and \code{mpi} modules
  904. -are internally defined with an \ftype{INTERFACE} or \ftype{CONTAINS}
  905. -construct, and with or without \ftype{BIND(C)}, and also if
  906. -\code{mpif.h} uses explicit interfaces.
  907. +All of these rules are valid
  908. +for the \texttt{mpi\_f08} and \texttt{mpi}
  909. +modules and
  910. +independently of whether
  911. +\texttt{mpif.h} uses explicit interfaces.
  912. \begin{implementors}
  913. - Some of these rules are already part of the Fortran 2003 standard
  914. - if the \MPI/ interfaces are defined without \ftype{BIND(C)}.
  915. - Additional compiler support may be necessary if \ftype{BIND(C)}
  916. - is used. Some of these additional requirements are defined in
  917. - the Fortran TS 29113 \cite{fortran2008:ts29113-interop}.
  918. - Some of these requirements for \MPIIIIDOTO/ are beyond the scope of TS 29113.
  919. + Some of these rules are already part of the Fortran 2003 standard,
  920. + some of these requirements require
  921. + the Fortran TS 29113 \cite{fortran2008:ts29113-interop},
  922. + and
  923. + some of these requirements for \MPIIIIDOTO/ are beyond the scope of TS 29113.
  924. \end{implementors}
  925. -Further requirements apply if
  926. -the \MPI/ library internally uses \ftype{BIND(C)} routine interfaces
  927. -(i.e., for a full implementation of \code{mpi\_f08}):
  928. -\begin{itemize}
  929. -\item
  930. - Non-buffer arguments are
  931. - \ftype{INTEGER}, \ftype{INTEGER(KIND=...)},
  932. - \ftype{CHARACTER(LEN=*)},
  933. - \ftype{LOGICAL},
  934. - and \ftype{BIND(C)} derived types (handles and status in \code{mpi\_f08}),
  935. - variables and arrays;
  936. - function results are \ftype{DOUBLE PRECISION}.
  937. - All these types must be valid as dummy arguments in the
  938. - \ftype{BIND(C)} \MPI/ routine interfaces.
  939. - When compiling an \MPI/ application, the compiler should not
  940. - issue warnings indicating that these types may not be interoperable
  941. - with an existing type in C.
  942. - Some of these types are already valid in \ftype{BIND(C)} interfaces
  943. - since Fortran 2003,
  944. - some may be valid based on TS 29113 (e.g., \ftype{CHARACTER*(*)}).
  945. -\item
  946. - \ftype{OPTIONAL} dummy arguments are also valid within \ftype{BIND(C)}
  947. - interfaces. This requirement is fulfilled if TS 29113 is fully supported
  948. - by the compiler.
  949. -\end{itemize}
  950.  
  951.  
  952. \subsection{Additional Support for Fortran Register-Memory-Synchronization}
  953. @@ -1316,7 +1274,7 @@
  954. \begin{funcdef}{MPI\_F\_SYNC\_REG(buf)}
  955. \funcarg{\INOUT}{buf}{initial address of buffer (choice)}
  956. \end{funcdef}
  957. -\mpifnewbind{MPI\_F\_sync\_reg(buf) BIND(C) \fargs TYPE(*), DIMENSION(..), ASYNCHRONOUS :: buf}
  958. +\mpifnewbind{MPI\_F\_sync\_reg(buf) \fargs TYPE(*), DIMENSION(..), ASYNCHRONOUS :: buf}
  959. \mpifbind{MPI\_F\_SYNC\_REG(buf)\fargs <type> buf(*)}
  960.  
  961. This routine has no executable statements. It must be compiled in the \MPI/ library
  962. @@ -1471,7 +1429,7 @@
  963. \funcarg{\OUT}{newtype}{the requested \MPI/ datatype (handle)}
  964. \end{funcdef}
  965. \mpibind{MPI\_Type\_create\_f90\_real(int~p, int~r, MPI\_Datatype~*newtype)}
  966. -\mpifnewbind{MPI\_Type\_create\_f90\_real(p, r, newtype, ierror) BIND(C) \fargs INTEGER, INTENT(IN) :: p, r \\ TYPE(MPI\_Datatype), INTENT(OUT) :: newtype \\ INTEGER, OPTIONAL, INTENT(OUT) :: ierror}
  967. +\mpifnewbind{MPI\_Type\_create\_f90\_real(p, r, newtype, ierror) \fargs INTEGER, INTENT(IN) :: p, r \\ TYPE(MPI\_Datatype), INTENT(OUT) :: newtype \\ INTEGER, OPTIONAL, INTENT(OUT) :: ierror}
  968. \mpifbind{MPI\_TYPE\_CREATE\_F90\_REAL(P, R, NEWTYPE, IERROR)\fargs INTEGER P, R, NEWTYPE, IERROR}
  969.  
  970. This function returns a predefined \MPI/ datatype that matches a \ftype{REAL} variable
  971. @@ -1500,7 +1458,7 @@
  972. \end{funcdef}
  973.  
  974. \mpibind{MPI\_Type\_create\_f90\_complex(int~p, int~r, MPI\_Datatype~*newtype)}
  975. -\mpifnewbind{MPI\_Type\_create\_f90\_complex(p, r, newtype, ierror) BIND(C) \fargs INTEGER, INTENT(IN) :: p, r \\ TYPE(MPI\_Datatype), INTENT(OUT) :: newtype \\ INTEGER, OPTIONAL, INTENT(OUT) :: ierror}
  976. +\mpifnewbind{MPI\_Type\_create\_f90\_complex(p, r, newtype, ierror) \fargs INTEGER, INTENT(IN) :: p, r \\ TYPE(MPI\_Datatype), INTENT(OUT) :: newtype \\ INTEGER, OPTIONAL, INTENT(OUT) :: ierror}
  977. \mpifbind{MPI\_TYPE\_CREATE\_F90\_COMPLEX(P, R, NEWTYPE, IERROR)\fargs INTEGER P, R, NEWTYPE, IERROR}
  978.  
  979. This function returns a predefined \MPI/ datatype that matches a \ftype{COMPLEX} variable
  980. @@ -1523,7 +1481,7 @@
  981. \funcarg{\OUT}{newtype}{the requested \MPI/ datatype (handle)}
  982. \end{funcdef}
  983. \mpibind{MPI\_Type\_create\_f90\_integer(int~r, MPI\_Datatype~*newtype)}
  984. -\mpifnewbind{MPI\_Type\_create\_f90\_integer(r, newtype, ierror) BIND(C) \fargs INTEGER, INTENT(IN) :: r \\ TYPE(MPI\_Datatype), INTENT(OUT) :: newtype \\ INTEGER, OPTIONAL, INTENT(OUT) :: ierror}
  985. +\mpifnewbind{MPI\_Type\_create\_f90\_integer(r, newtype, ierror) \fargs INTEGER, INTENT(IN) :: r \\ TYPE(MPI\_Datatype), INTENT(OUT) :: newtype \\ INTEGER, OPTIONAL, INTENT(OUT) :: ierror}
  986. \mpifbind{MPI\_TYPE\_CREATE\_F90\_INTEGER(R, NEWTYPE, IERROR)\fargs INTEGER R, NEWTYPE, IERROR}
  987.  
  988. This function returns a predefined \MPI/ datatype that matches a \ftype{INTEGER} variable
  989. @@ -1691,7 +1649,7 @@
  990. Fortran where \constskip{$<$TYPE$>$} is one of
  991. \constskip{REAL}, \constskip{INTEGER} and \constskip{COMPLEX}, and \textbf{n} is the length in bytes of the
  992. machine representation. This datatype locally matches all variables
  993. -of type (\textbf{typeclass}, \textbf{n}). The list of names for such types
  994. +of type (\textbf{typeclass}, \textbf{n}) in Fortran. The list of names for such types
  995. includes:
  996. %%HEADER
  997. %%SKIP
  998. @@ -1711,7 +1669,20 @@
  999. \end{verbatim}
  1000. One
  1001. datatype is required for each representation supported by
  1002. -the compiler. To be backward compatible with the interpretation of
  1003. +the Fortran compiler.
  1004. +
  1005. +\begin{rationale}
  1006. + Particularly for the longer floating-point types, C and Fortran may
  1007. + use different representations. For example, a Fortran compiler may
  1008. + define a 16-byte \constskip{REAL} type with 33 decimal digits of
  1009. + precision while a C compiler may define a 16-byte \constskip{long
  1010. + double} type that implements an 80-bit (10 byte) extended
  1011. + precision floating point value. Both of these types are 16 bytes
  1012. + long, but they are not interoperable. Thus, these types are defined
  1013. + by Fortran, even though C may define types of the same length.
  1014. +\end{rationale}
  1015. +
  1016. +To be backward compatible with the interpretation of
  1017. these types in \MPII/, we assume that the nonstandard declarations
  1018. \ftype{REAL*n}, \ftype{INTEGER*n}, always create a variable whose
  1019. representation is of size \textbf{n}.
  1020. @@ -1731,7 +1702,7 @@
  1021. \funcarg{\OUT}{size}{size of machine representation of that type (integer)}
  1022. \end{funcdef}
  1023.  
  1024. -\mpifnewbind{MPI\_Sizeof(x, size, ierror) BIND(C) \fargs TYPE(*), DIMENSION(..) :: x \\ INTEGER, INTENT(OUT) :: size \\ INTEGER, OPTIONAL, INTENT(OUT) :: ierror}
  1025. +\mpifnewbind{MPI\_Sizeof(x, size, ierror) \fargs TYPE(*), DIMENSION(..) :: x \\ INTEGER, INTENT(OUT) :: size \\ INTEGER, OPTIONAL, INTENT(OUT) :: ierror}
  1026. \mpifbind{MPI\_SIZEOF(X, SIZE, IERROR) \fargs <type> X\\INTEGER SIZE, IERROR }
  1027.  
  1028. This function returns the size in bytes of the machine representation of
  1029. @@ -1757,7 +1728,7 @@
  1030. \end{funcdef}
  1031.  
  1032. \mpibind{MPI\_Type\_match\_size(int~typeclass, int~size, MPI\_Datatype~*datatype)}
  1033. -\mpifnewbind{MPI\_Type\_match\_size(typeclass, size, datatype, ierror) BIND(C) \fargs INTEGER, INTENT(IN) :: typeclass, size \\ TYPE(MPI\_Datatype), INTENT(OUT) :: datatype \\ INTEGER, OPTIONAL, INTENT(OUT) :: ierror}
  1034. +\mpifnewbind{MPI\_Type\_match\_size(typeclass, size, datatype, ierror) \fargs INTEGER, INTENT(IN) :: typeclass, size \\ TYPE(MPI\_Datatype), INTENT(OUT) :: datatype \\ INTEGER, OPTIONAL, INTENT(OUT) :: ierror}
  1035. \mpifbind{MPI\_TYPE\_MATCH\_SIZE(TYPECLASS, SIZE, DATATYPE, IERROR) \fargs INTEGER TYPECLASS, SIZE, DATATYPE, IERROR}
  1036.  
  1037. \mpiarg{typeclass} is one of \const{MPI\_TYPECLASS\_REAL},
  1038. @@ -2145,6 +2116,12 @@
  1039. \end{rationale}
  1040.  
  1041. \item If \const{MPI\_SUBARRAYS\_SUPPORTED} equals \ftype{.FALSE.}:
  1042. +
  1043. +In this case, the use of Fortran arrays with subscript triplets as
  1044. +actual choice buffer arguments in any nonblocking \MPI/ operation
  1045. +(which also includes persistent request, and split collectives) may
  1046. +cause undefined behavior. They may, however, be used in blocking \MPI/
  1047. +operations.
  1048.  
  1049. Implicit in \MPI/ is the idea of a contiguous chunk of memory accessible
  1050. through a linear address space. \MPI/ copies data to and from this
  1051. @@ -2280,7 +2257,7 @@
  1052. CALL MPI_Send( A((/7,9,23,81,82/)), 5, MPI_REAL, ...)
  1053. \end{verbatim}
  1054.  
  1055. -Arrays with a vector subscript must not be used as actual choice buffer arguments
  1056. +Fortran arrays with a vector subscript must not be used as actual choice buffer arguments
  1057. in any nonblocking or split collective \MPI/ operations. They may, however, be used in
  1058. blocking \MPI/ operations.
  1059.  
  1060. @@ -2596,6 +2573,15 @@
  1061. The register optimization / code movement problem for \const{MPI\_BOTTOM}
  1062. and derived \MPI/ datatypes may occur in each blocking and nonblocking
  1063. communication call, as well as in each parallel file I/O operation.
  1064. +
  1065. +\subsubsection{Persistent Operations}
  1066. +
  1067. +With persistent requests, the buffer argument is hidden from the
  1068. +\mpifunc{MPI\_START} and \mpifunc{MPI\_STARTALL} calls, i.e., the
  1069. +Fortran compiler may move buffer accesses across the
  1070. +\mpifunc{MPI\_START} or \mpifunc{MPI\_STARTALL} call, similar to the
  1071. +\mpifunc{MPI\_WAIT} call as described in the Nonblocking Operations
  1072. +subsection in Section~\ref{sec:f90-problems:code-movements}.
  1073.  
  1074. \subsubsection{One-sided Communication}
  1075.  
  1076. @@ -3225,7 +3211,7 @@
  1077. \begin{itemize}
  1078. \item \MPI/ datatype handles with absolute addresses in combination
  1079. with \const{MPI\_BOTTOM}.
  1080. -\item Nonblocking \MPI/ operations (communication, one-sided, I/O)
  1081. +\item All nonblocking \MPI/ operations
  1082. if the internally used
  1083. pointers to the buffers are not updated by the Fortran
  1084. runtime, or if within an \MPI/ process,
  1085. @@ -3772,7 +3758,7 @@
  1086. \funcarg{\OUT}{f08\_status}{status object declared as named type}
  1087. \end{funcdef}
  1088. \mpibind{MPI\_Status\_f2f08(MPI\_Fint~*f\_status, MPI\_F08\_status *f08\_status)}
  1089. -\mpifnewbind{MPI\_Status\_f2f08(f\_status, f08\_status, ierror) BIND(C) \fargs INTEGER, INTENT(IN) :: f\_status(MPI\_STATUS\_SIZE) \\ TYPE(MPI\_Status), INTENT(OUT) :: f08\_status \\ INTEGER, OPTIONAL, INTENT(OUT) :: ierror }
  1090. +\mpifnewbind{MPI\_Status\_f2f08(f\_status, f08\_status, ierror) \fargs INTEGER, INTENT(IN) :: f\_status(MPI\_STATUS\_SIZE) \\ TYPE(MPI\_Status), INTENT(OUT) :: f08\_status \\ INTEGER, OPTIONAL, INTENT(OUT) :: ierror }
  1091. \mpifbind{MPI\_STATUS\_F2F08(F\_STATUS, F08\_STATUS, IERROR)\fargs INTEGER :: F\_STATUS(MPI\_STATUS\_SIZE) \\ TYPE(MPI\_Status) :: F08\_STATUS \\ INTEGER IERROR}
  1092.  
  1093. This routine converts a Fortran \ftype{INTEGER}, \ftype{DIMENSION(MPI\_STATUS\_SIZE)} status array
  1094. @@ -3783,7 +3769,7 @@
  1095. \funcarg{\OUT}{f\_status}{status object declared as array}
  1096. \end{funcdef}
  1097. \mpibind{MPI\_Status\_f082f(MPI\_F08\_status *f08\_status, MPI\_Fint~*f\_status)}
  1098. -\mpifnewbind{MPI\_Status\_f082f(f08\_status, f\_status, ierror) BIND(C) \fargs TYPE(MPI\_Status), INTENT(IN) :: f08\_status \\ INTEGER, INTENT(OUT) :: f\_status(MPI\_STATUS\_SIZE) \\ INTEGER, OPTIONAL, INTENT(OUT) :: ierror}
  1099. +\mpifnewbind{MPI\_Status\_f082f(f08\_status, f\_status, ierror) \fargs TYPE(MPI\_Status), INTENT(IN) :: f08\_status \\ INTEGER, INTENT(OUT) :: f\_status(MPI\_STATUS\_SIZE) \\ INTEGER, OPTIONAL, INTENT(OUT) :: ierror}
  1100. \mpifbind{MPI\_STATUS\_F082F(F08\_STATUS, F\_STATUS, IERROR)\fargs TYPE(MPI\_Status) :: F08\_STATUS \\ INTEGER :: F\_STATUS(MPI\_STATUS\_SIZE) \\ INTEGER IERROR}
  1101.  
  1102. This routine converts a Fortran \code{mpi\_f08} \ftype{TYPE(MPI\_Status)}\cdeclindex{MPI\_Status}
Advertisement
Add Comment
Please, Sign In to add comment
Advertisement
Public Pastes
Advertisement
We use cookies for various purposes including analytics. By continuing to use Pastebin, you agree to our use of cookies as described in the Cookies Policy.  OK, I Understand
Not a member of Pastebin yet?
Sign Up, it unlocks many cool features!