From a273f05be871d6fa8a6c173dcb733b32144f14cd Mon Sep 17 00:00:00 2001
From: jthorn <jthorn@17b73243-c579-4c4c-a9d2-2d5706c11dac>
Date: Fri, 26 May 2006 18:58:51 +0000
Subject: redo description of  CCTK_SyncGroup() * use modern
 FunctionDescription environment * document that GH argument is
 pointer-to-const   (i.e. document that  CCTK_SyncGroup  doesn't modify the
 GH) * document that this is a collective operation * add an example

git-svn-id: http://svn.cactuscode.org/flesh/trunk@4302 17b73243-c579-4c4c-a9d2-2d5706c11dac
---
 doc/ReferenceManual/CCTKReference.tex | 91 ++++++++++++++++++++++++++++-------
 1 file changed, 74 insertions(+), 17 deletions(-)

(limited to 'doc/ReferenceManual')

diff --git a/doc/ReferenceManual/CCTKReference.tex b/doc/ReferenceManual/CCTKReference.tex
index 83535bd9..c54c774b 100644
--- a/doc/ReferenceManual/CCTKReference.tex
+++ b/doc/ReferenceManual/CCTKReference.tex
@@ -9822,16 +9822,45 @@ Reduces a list of local arrays globally
 
 
 % CommOverloadables.c
-\begin{CCTKFunc}{CCTK\_SyncGroup}{Synchronise the ghostzones for a group of grid variables}
+\begin{FunctionDescription}{CCTK\_SyncGroup}
 \label{CCTK-SyncGroup}
-\subroutine{int}{integer}{istat}
-\argument{cGH *}{CCTK\_POINTER}{cctkGH}
-\argument{const char *}{character*(*)}{group}
-\showargs
-\begin{params}
-\parameter{cctkGH}{pointer to CCTK grid hierarchy}
-\end{params}
-\begin{discussion}
+Synchronise the ghostzones for a group of grid variables
+
+\begin{SynopsisSection}
+\begin{Synopsis}{C}
+\begin{verbatim}
+#include "cctk.h"
+int status = CCTK_SyncGroup(const cGH* GH, const char* group_name)
+\end{verbatim}
+\end{Synopsis}
+\begin{Synopsis}{Fortran}
+\begin{verbatim}
+#include "cctk.h"
+integer status
+CCTK_POINTER GH
+character*(*) group_name
+call CCTK_SyncGroup(status, GH, group_name)
+\end{verbatim}
+\end{Synopsis}
+\end{SynopsisSection}
+
+\begin{ResultSection}
+\begin{Result}{0}
+Success.
+\end{Result}
+\end{ResultSection}
+
+\begin{ParameterSection}
+\begin{Parameter}{GH}
+A pointer to a Cactus grid hierarchy.
+\end{Parameter}
+\begin{Parameter}{group\_name}
+The full name (Implementation::group or Thorn::group) of the group
+to be synchronized.
+\end{Parameter}
+\end{ParameterSection}
+
+\begin{Discussion}
 Only those grid variables which have communication enabled
 will be synchronised. This is usually equivalent to the variables
 which have storage assigned, unless communication has been explicitly
@@ -9842,16 +9871,44 @@ from within a thorn, is to use the \code{SYNC} keyword in a thorns
 \code{schedule.ccl} file to indicate which groups of variables need
 to be synchronised on exit from the routine. This latter method is
 the preferred method from synchronising variables.
-\end{discussion}
-\begin{examples}
-\begin{tabular}{@{}p{3cm}cp{11cm}}
-\end{tabular}
-\end{examples}
-\begin{errorcodes}
-\end{errorcodes}
-\end{CCTKFunc}
 
+Note that \code{CCTK\_SyncGroup} is a collective operation, so in the
+multiprocessor case you {\em must\/} call this function in parallel on
+{\em each\/} processor, passing the same \code{group\_name} argument.
+\end{Discussion}
 
+\begin{ErrorSection}
+\begin{Error}{-1}
+\code{group\_name} was invalid.
+\end{Error}
+\begin{Error}{-2}
+The driver returned an error on syncing the group.
+\end{Error}
+\end{ErrorSection}
+
+\begin{ExampleSection}
+\begin{Example}{C}
+\begin{verbatim}
+#include "cctk.h"
+#include "cctk_Arguments.h"
+
+/* this function synchronizes the ADM metric */
+void synchronize_ADM_metric(CCTK_ARGUMENTS)
+{
+DECLARE_CCTK_ARGUMENTS      /* defines "magic variable" cctkGH */
+
+const int status = CCTK_SyncGroup(cctkGH, "ADMBase::metric");
+if (status < 0)
+        CCTK_VWarn(CCTK_WARN_ABORT, __LINE__, __FILE__, CCTK_THORNSTRING,
+"***** synchronize_ADM_metric():\n"
+"        failed to synchronize ADM metric!\n"
+"        (CCTK_SyncGroup() returned error code %d)\n"
+                  ,
+                  status);                                 /*NOTREACHED*/
+\end{verbatim}
+\end{Example}
+\end{ExampleSection}
+\end{FunctionDescription}
 
 %%%%%
 % TTT
-- 
cgit v1.2.3