From f49a4443cfc58a176fb4d1f8c6b721665f8fd146 Mon Sep 17 00:00:00 2001
From: Thomas Jahns <jahns@dkrz.de>
Date: Mon, 4 Oct 2021 00:24:06 +0200
Subject: [PATCH] Improve CDI-PIO documentation.
---
doc/pio/tex/c_quick_ref.tex | 29 ++++++++++++++++++++++++++---
doc/pio/tex/f_quick_ref.tex | 29 ++++++++++++++++++++++++++---
src/cdipio.h | 13 ++++++++++---
3 files changed, 62 insertions(+), 9 deletions(-)
diff --git a/doc/pio/tex/c_quick_ref.tex b/doc/pio/tex/c_quick_ref.tex
index e5c1a8dbb..4880dca57 100644
--- a/doc/pio/tex/c_quick_ref.tex
+++ b/doc/pio/tex/c_quick_ref.tex
@@ -226,7 +226,7 @@ configuration object.
set function to be called after
setup of client/server communications of configuration object.
Deprecated: use cdiPioConfSetCallBackActions with
-trigger == CDIPIO_CALLBACK_POSTCOMMSETUP in new programs.
+trigger == CDIPIO_CALLBACK_POSTCOMMSETUP in new programs!.
\section*{\tt \htmlref{cdiPioConfSetRecordAggBufLim}{cdiPioConfSetRecordAggBufLim}}
@@ -385,10 +385,23 @@ namespace.
void cdiPioNoPostCommSetup ();
\end{verbatim}
-Dummy function to use as argument to pioInit
+Dummy default function to use as argument to
+cdiPioConfSetCallBackActions or pioInit
if no actions are necessary after I/O servers initialize communication.
+\section*{\tt \htmlref{cdiPioRDMAProgress}{cdiPioRDMAProgress}}
+
+\begin{verbatim}
+ void cdiPioRDMAProgress ();
+\end{verbatim}
+
+devote some resources to make RMA progress This
+call is meant for systems where the hardware and/or MPI make
+insufficient progress when only calling
+MPI_Win_post/MPI_Win_wait+MPI_Win_start/MPI_Win_get/MPI_Win_complete.
+
+
\section*{\tt \htmlref{cdiPioStr2IOMode}{cdiPioStr2IOMode}}
\begin{verbatim}
@@ -424,7 +437,17 @@ conversion[varID] == CDI_DATATYPE_FLT64 or with streamWriteVarF
void (*postCommSetupActions)(void));
\end{verbatim}
-initialize I/O server processes and communication.
+initialize I/O server processes and communication
+Deprecated, use cdiPioInit instead!.
+
+
+\section*{\tt \htmlref{pioWriteTimestep}{pioWriteTimestep}}
+
+\begin{verbatim}
+ void pioWriteTimestep ();
+\end{verbatim}
+
+flush data from all client RMA buffers to server.
\section*{\tt \htmlref{streamWriteScatteredVarPart}{streamWriteScatteredVarPart}}
diff --git a/doc/pio/tex/f_quick_ref.tex b/doc/pio/tex/f_quick_ref.tex
index 339605ff1..eed40e294 100644
--- a/doc/pio/tex/f_quick_ref.tex
+++ b/doc/pio/tex/f_quick_ref.tex
@@ -229,7 +229,7 @@ configuration object.
set function to be called after
setup of client/server communications of configuration object.
Deprecated: use cdiPioConfSetCallBackActions with
-trigger == CDIPIO_CALLBACK_POSTCOMMSETUP in new programs.
+trigger == CDIPIO_CALLBACK_POSTCOMMSETUP in new programs!.
\section*{\tt \htmlref{cdiPioConfSetRecordAggBufLim}{cdiPioConfSetRecordAggBufLim}}
@@ -392,10 +392,23 @@ namespace.
SUBROUTINE cdiPioNoPostCommSetup
\end{verbatim}
-Dummy function to use as argument to pioInit
+Dummy default function to use as argument to
+cdiPioConfSetCallBackActions or pioInit
if no actions are necessary after I/O servers initialize communication.
+\section*{\tt \htmlref{cdiPioRDMAProgress}{cdiPioRDMAProgress}}
+
+\begin{verbatim}
+ SUBROUTINE cdiPioRDMAProgress
+\end{verbatim}
+
+devote some resources to make RMA progress This
+call is meant for systems where the hardware and/or MPI make
+insufficient progress when only calling
+MPI_Win_post/MPI_Win_wait+MPI_Win_start/MPI_Win_get/MPI_Win_complete.
+
+
\section*{\tt \htmlref{cdiPioStr2IOMode}{cdiPioStr2IOMode}}
\begin{verbatim}
@@ -431,7 +444,17 @@ conversion[varID] == CDI_DATATYPE_FLT64 or with streamWriteVarF
PROCEDURE postCommSetupActions)
\end{verbatim}
-initialize I/O server processes and communication.
+initialize I/O server processes and communication
+Deprecated, use cdiPioInit instead!.
+
+
+\section*{\tt \htmlref{pioWriteTimestep}{pioWriteTimestep}}
+
+\begin{verbatim}
+ SUBROUTINE pioWriteTimestep
+\end{verbatim}
+
+flush data from all client RMA buffers to server.
\section*{\tt \htmlref{streamWriteScatteredVarPart}{streamWriteScatteredVarPart}}
diff --git a/src/cdipio.h b/src/cdipio.h
index 9bdb39258..e6e3fe088 100644
--- a/src/cdipio.h
+++ b/src/cdipio.h
@@ -36,16 +36,23 @@
void pioEndDef ( void );
void pioEndTimestepping ( void );
void pioFinalize ( void );
-/* cdiPioNoPostCommSetup: Dummy function to use as argument to pioInit
+/* cdiPioNoPostCommSetup: Dummy default function to use as argument to
+ * cdiPioConfSetCallBackActions or pioInit
* if no actions are necessary after I/O servers initialize communication */
void cdiPioNoPostCommSetup(void);
-/* pioInit: initialize I/O server processes and communication */
+/* pioInit: initialize I/O server processes and communication
+ * Deprecated, use cdiPioInit instead! */
MPI_Comm pioInit(MPI_Comm commSuper, int nProcsIO, int IOMode,
int *pioNamespace, float partInflate,
void (*postCommSetupActions)(void));
/* cdiPioInit: initialize I/O server processes and communication */
MPI_Comm cdiPioInit(MPI_Comm commSuper, int confResH, int *pioNamespace);
+/* pioWriteTimestep: flush data from all client RMA buffers to server */
void pioWriteTimestep(void);
+/* cdiPioRDMAProgress: devote some resources to make RMA progress This
+ * call is meant for systems where the hardware and/or MPI make
+ * insufficient progress when only calling
+ * MPI_Win_post/MPI_Win_wait+MPI_Win_start/MPI_Win_get/MPI_Win_complete */
void cdiPioRDMAProgress(void);
@@ -156,7 +163,7 @@ int cdiPioConfGetCSRole(int confResH);
/* cdiPioConfSetPostCommSetupActions: set function to be called after
* setup of client/server communications of configuration object.
* Deprecated: use cdiPioConfSetCallBackActions with
- * trigger == CDIPIO_CALLBACK_POSTCOMMSETUP in new programs */
+ * trigger == CDIPIO_CALLBACK_POSTCOMMSETUP in new programs! */
void cdiPioConfSetPostCommSetupActions(int confResH,
void (*postCommSetupActions)(void));
--
GitLab