Declare and make use of new overloadable CCTK_SyncGroupsByDirI() which

synchronises multiple groups in a single call. This function deprecates
the old overloadable function CCTK_SyncGroup().

This patch concludes the discussion thread starting on
http://www.cactuscode.org/old/pipermail/developers/2006-June/004933.html.


git-svn-id: http://svn.cactuscode.org/flesh/trunk@4348 17b73243-c579-4c4c-a9d2-2d5706c11dac

3 files changed, 162 insertions, 28 deletions

diff --git a/src/comm/CactusDefaultComm.c b/src/comm/CactusDefaultComm.c
index 5f0e0f29..ff0d96a4 100644
--- a/src/comm/CactusDefaultComm.c
+++ b/src/comm/CactusDefaultComm.c
@@ -13,6 +13,7 @@
 #include "cctk_Groups.h"
 #include "cctk_Constants.h"
 #include "cctk_Comm.h"
+#include "cctk_Sync.h"
 #include "cctk_WarnLevel.h"
 
 #include "cctki_GHExtensions.h"
@@ -79,6 +80,10 @@ int CactusDefaultExit(cGH *GH, int retval);
 int CactusDefaultAbort(cGH *GH, int retval);
 int CactusDefaultBarrier(const cGH *GH);
 
+int CactusDefaultSyncGroup (const cGH *GH, const char *groupname);
+int CactusDefaultSyncGroupsByDirI(const cGH *GH, int num_groups,
+                                  const int *groups,
+                                  const int *directions);
 int CactusDefaultEnableGroupStorage(const cGH *GH, const char *group);
 int CactusDefaultDisableGroupStorage(const cGH *GH, const char *group);
 int CactusDefaultGroupStorageIncrease(const cGH *GH, int n_groups,
@@ -461,6 +466,133 @@ int CactusDefaultBarrier (const cGH *GH)
   return (0);
 }
 
+
+ /*@@
+   @routine    CactusDefaultSyncGroup
+   @date       Mon 3 July 2006
+   @author     Thomas Radke
+   @desc
+               Default routine for synchronising a single group.
+
+               If this function has not been overloaded by a driver,
+               it will simply call CCTK_SyncGroupsByDirI() (which then must be
+               overloaded by a driver).
+   @enddesc
+
+   @var        GH
+   @vdesc      Pointer to CCTK grid hierarchy
+   @vtype      const cGH *
+   @vio        in
+   @endvar
+   @var        groupname
+   @vdesc      full name of the group to be synchronised
+   @vtype      const char *
+   @vio        in
+   @endvar
+
+   @returntype int
+   @returndesc
+               0 for success,
+               or (negative) return code of @seeroutine CCTK_SyncGroupsByDirI
+   @endreturndesc
+ @@*/
+int CactusDefaultSyncGroup (const cGH *GH, const char *groupname)
+{
+  int group, retval;
+
+
+  group = CCTK_GroupIndex (groupname);
+  retval = CCTK_SyncGroupsByDirI (GH, 1, &group, NULL);
+
+  return (retval == 1 ? 0 : retval);
+}
+
+
+ /*@@
+   @routine    CactusDefaultSyncGroupsByDirI
+   @date       Mon 3 July 2006
+   @author     Thomas Radke
+   @desc
+               Default groups synchronisation routine.
+
+               If this function has not been overloaded by a driver,
+               it will loop over all groups to be synchronised and
+               for each of them call CCTK_SyncGroupI() which itself calls
+               the routine CCTK_SyncGroup() (which then must be overloaded
+               by a driver).
+   @enddesc
+
+   @var        GH
+   @vdesc      Pointer to CCTK grid hierarchy
+   @vtype      const cGH *
+   @vio        in
+   @endvar
+   @var        num_groups
+   @vdesc      number of groups to be synchronised
+   @vtype      int
+   @vio        in
+   @endvar
+   @var        groups
+   @vdesc      list of indices of groups to be synchronised
+   @vtype      int *
+   @vio        in
+   @endvar
+   @var        directions
+   @vdesc      (optional) array of dimensions which should be synchronised
+   @vtype      int *
+   @vio        in
+   @endvar
+
+   @returntype int
+   @returndesc
+               the number of groups which were synchronised
+   @endreturndesc
+ @@*/
+int CactusDefaultSyncGroupsByDirI (const cGH *GH, int num_groups,
+                                   const int *groups,
+                                   const int *directions)
+{
+  int group, retval = 0;
+  static int user_has_been_notified = 0;
+
+ 
+  /* individual directions aren't supported in the CCTK_SyncGroup* interface */
+  if (directions != NULL)
+  {
+    CCTK_VWarn (CCTK_WARN_ABORT, __LINE__, __FILE__, "Cactus",
+                "Synchronisation of individual directions isn't supported "
+                "with no driver overloading CCTK_SyncGroupsByDirI().");
+  }
+
+  /* if CCTK_SyncGroup() hasn't been overloaded then this is a no-op */
+  if (CCTK_SyncGroup != CactusDefaultSyncGroup)
+  {
+    /* on the first time through, warn the user if a driver overloaded
+       the (deprecated) routine CCTK_SyncGroup() but not the newer one
+       CCTK_SyncGroupsByDirI() */
+    if (! user_has_been_notified)
+    {
+      CCTK_VWarn (CCTK_WARN_COMPLAIN, __LINE__, __FILE__, "Cactus",
+                  "Overloading CCTK_SyncGroup() is deprecated. "
+                  "Please have your driver thorn updated to overload "
+                  "CCTK_SyncGroupsByDirI() instead !");
+    }
+    user_has_been_notified = 1;
+
+    /* synchronise all groups one by one */
+    for (group = 0; group < num_groups; group++)
+    {
+      if (CCTK_SyncGroupI (GH, groups[group]) == 0)
+      {
+        retval++;
+      }
+    }
+  }
+
+  return (retval);
+}
+
+
  /*@@
    @routine    CactusDefaultEnableGroupStorage
    @date       Wed Apr  3 17:01:22 2002
diff --git a/src/comm/CactusSync.c b/src/comm/CactusSync.c
index 102d91d1..ee411372 100644
--- a/src/comm/CactusSync.c
+++ b/src/comm/CactusSync.c
@@ -36,6 +36,9 @@ void CCTK_FCALL CCTK_FNAME (CCTK_SyncGroupWithVar)
                            (int *ierror, const cGH **GH, ONE_FORTSTRING_ARG);
 void CCTK_FCALL CCTK_FNAME (CCTK_SyncGroupWithVarI)
                            (int *ierror, const cGH **GH, const int *var);
+void CCTK_FCALL CCTK_FNAME (CCTK_SyncGroupsI)
+                           (int *ierror, const cGH **GH, const int *num_groups,
+                            const int *groups);
 
 
  /*@@
@@ -45,8 +48,7 @@ void CCTK_FCALL CCTK_FNAME (CCTK_SyncGroupWithVarI)
    @desc
                Synchronizes a group given by its index.
    @enddesc
-   @calls      CCTK_GroupName
-               CCTK_SyncGroup
+   @calls      CCTK_SyncGroupsI
 
    @var        GH
    @vdesc      Pointer to Grid Hierachy
@@ -62,29 +64,17 @@ void CCTK_FCALL CCTK_FNAME (CCTK_SyncGroupWithVarI)
    @returntype int
    @returndesc
                 0 for success, or<BR>
-               -1 if an invalid group was given,<BR>
-               -2 if driver returned an error on syncing the group
+               -negative return code of @seeroutine CCTK_SyncGroupsI
    @endreturndesc
 @@*/
 int CCTK_SyncGroupI (const cGH *GH, int group)
 {
   int retval;
-  char *groupname;
 
 
-  retval = -1;
-  groupname = CCTK_GroupName (group);
-  if (groupname)
-  {
-    retval = CCTK_SyncGroup (GH, groupname);
-    if (retval)
-    {
-      retval = -2;
-    }
-    free (groupname);
-  }
+  retval = CCTK_SyncGroupsI (GH, 1, &group);
 
-  return (retval);
+  return (retval == 1 ? 0 : retval);
 }
 
 void CCTK_FCALL CCTK_FNAME (CCTK_SyncGroupI)
@@ -192,7 +182,7 @@ void CCTK_FCALL CCTK_FNAME (CCTK_SyncGroupWithVarI)
    @desc
                Synchronises a list of groups given by their group indices.
    @enddesc
-   @calls      CCTK_SyncGroupI
+   @calls      CCTK_SyncGroupsByDirI
 
    @var        GH
    @vdesc      Pointer to Grid Hierachy
@@ -212,24 +202,19 @@ void CCTK_FCALL CCTK_FNAME (CCTK_SyncGroupWithVarI)
 
    @returntype int
    @returndesc
-               the total number of groups synchronized
+               the total number of groups synchronized, or
+               -negative return code of @seeroutine CCTK_SyncGroupsByDirI
    @endreturndesc
 @@*/
 int CCTK_SyncGroupsI (const cGH *GH,
                       int n_groups,
                       const int *groups)
 {
-  int i, retval;
+  int retval;
 
 
-  retval = 0;
-  for (i = 0; i < n_groups; i++)
-  {
-    if (CCTK_SyncGroupI (GH, groups[i]) == 0)
-    {
-      retval++;
-    }
-  }
+  /* passing NULL as the last argument means: synchronise all directions */
+  retval = CCTK_SyncGroupsByDirI (GH, n_groups, groups, NULL);
 
   return (retval);
 }
diff --git a/src/comm/OverloadComm.c b/src/comm/OverloadComm.c
index eeb1c253..c39c1059 100644
--- a/src/comm/OverloadComm.c
+++ b/src/comm/OverloadComm.c
@@ -35,6 +35,8 @@ CCTK_FILEVERSION(comm_OverloadComm_c);
 #define CCTKi_DummySetupGH  CactusDefaultSetupGH
 
   /* Need to do some stuff to make sure old routines still work. */
+#define CCTKi_DummySyncGroup             CactusDefaultSyncGroup
+#define CCTKi_DummySyncGroupsByDirI      CactusDefaultSyncGroupsByDirI
 #define CCTKi_DummyEnableGroupStorage    CactusDefaultEnableGroupStorage
 #define CCTKi_DummyDisableGroupStorage   CactusDefaultDisableGroupStorage
 #define CCTKi_DummyGroupStorageIncrease  CactusDefaultGroupStorageIncrease
@@ -52,6 +54,8 @@ CCTK_FILEVERSION(comm_OverloadComm_c);
 #undef CCTKi_DummyExit
 #undef CCTKi_DummyAbort
 
+#undef CCTKi_DummySyncGroup
+#undef CCTKi_DummySyncGroupsByDirI
 #undef CCTKi_DummyEnableGroupStorage
 #undef CCTKi_DummyDisableGroupStorage
 #undef CCTKi_DummyGroupStorageIncrease
@@ -98,6 +102,8 @@ int CCTKi_SetupCommFunctions(void)
 #define CCTKi_DummynProcs  CactusDefaultnProcs
 #define CCTKi_DummySetupGH CactusDefaultSetupGH
 
+#define CCTKi_DummySyncGroup             CactusDefaultSyncGroup
+#define CCTKi_DummySyncGroupsByDirI      CactusDefaultSyncGroupsByDirI
 #define CCTKi_DummyEnableGroupStorage    CactusDefaultEnableGroupStorage
 #define CCTKi_DummyDisableGroupStorage   CactusDefaultDisableGroupStorage
 #define CCTKi_DummyGroupStorageIncrease  CactusDefaultGroupStorageIncrease
@@ -115,6 +121,8 @@ int CCTKi_SetupCommFunctions(void)
 #undef CCTKi_DummynProcs
 #undef CCTKi_DummySetupGH  
 
+#undef CCTKi_DummySyncGroup
+#undef CCTKi_DummySyncGroupsByDirI
 #undef CCTKi_DummyEnableGroupStorage
 #undef CCTKi_DummyDisableGroupStorage
 #undef CCTKi_DummyGroupStorageIncrease
@@ -151,6 +159,7 @@ void CCTK_FCALL CCTK_FNAME (CCTK_Barrier) (int *ierror, const cGH **GH);
 void CCTK_FCALL CCTK_FNAME (CCTK_Exit) (int *ierror, cGH **GH, const int *retval);
 void CCTK_FCALL CCTK_FNAME (CCTK_Abort) (int *ierror, cGH **GH, const int *retval);
 void CCTK_FCALL CCTK_FNAME (CCTK_SyncGroup) (int *ierror, cGH **GH, ONE_FORTSTRING_ARG);
+void CCTK_FCALL CCTK_FNAME (CCTK_SyncGroupsByDirI) (int *ierror, cGH **GH, const int *num_groups, const int *groups, const int *directions);
 void CCTK_FCALL CCTK_FNAME (CCTK_EnableGroupComm) (int *ierror, const cGH **GH, ONE_FORTSTRING_ARG);
 void CCTK_FCALL CCTK_FNAME (CCTK_DisableGroupComm) (int *ierror, const cGH **GH, ONE_FORTSTRING_ARG);
 void CCTK_FCALL CCTK_FNAME (CCTK_EnableGroupStorage) (int *ierror, const cGH **GH, ONE_FORTSTRING_ARG);
@@ -191,6 +200,14 @@ void CCTK_FCALL CCTK_FNAME (CCTK_SyncGroup) (int *ierror, cGH **GH, ONE_FORTSTRI
   free (group_name); 
 }
 
+void CCTK_FCALL CCTK_FNAME (CCTK_SyncGroupsByDirI) (int *ierror, cGH **GH,
+                                                    const int *num_groups,
+                                                    const int *groups,
+                                                    const int *directions)
+{
+  *ierror = CCTK_SyncGroupsByDirI (*GH, *num_groups, groups, directions);
+}
+
 void CCTK_FCALL CCTK_FNAME (CCTK_EnableGroupComm) (int *ierror, const cGH **GH, ONE_FORTSTRING_ARG)
 {
   ONE_FORTSTRING_CREATE (group_name)