Added comments and grdoced

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

1 files changed, 426 insertions, 75 deletions

diff --git a/src/IO/IOMethods.c b/src/IO/IOMethods.c
index 61292c09..7179142d 100644
--- a/src/IO/IOMethods.c
+++ b/src/IO/IOMethods.c
@@ -17,14 +17,11 @@
 
 static char *rcsid = "$Header$";
 
-
 /* Local data holding info on IO methods.*/
-
 static cHandledData *IOMethods = NULL;
 static int num_methods = 0;
 
-/* Dummy function prototypes. */
-
+/* Dummy registerable function prototypes. */
 static int DummyOutputGH(cGH *GH);
 static int DummyOutputVarAs(cGH *GH, 
                             const char *var, 
@@ -32,30 +29,45 @@ static int DummyOutputVarAs(cGH *GH,
 static int DummyTimeToOutput(cGH *GH, int);
 
 
-/**************************************************************************
- **************************************************************************
- **************************************************************************/
-
+/************************************************************************
+ *
+ *  Registration routines functions provided by IO methods
+ *
+ ************************************************************************/
 
  /*@@
    @routine    CCTK_RegisterIOMethod
    @date       Wed Feb  3 13:33:09 1999
    @author     Tom Goodale
    @desc 
-   Registers a new IO method.
+               Registers a new IO method.
    @enddesc 
-   @calls     
-   @calledby   
+   @calls      CCTK_GetHandle
+               CCTK_NewHandle
    @history 
+   @endhistory
  
-   @endhistory 
+   @var        name
+   @vdesc      The name of the method for IO
+   @vtype      const char *
+   @vio        in
+   @vcomment 
+   @endvar 
 
+   @returntype int
+   @returndesc
+               -2  = memory allocation failed
+               -1  = method with this name already registered
+               i>0 = handle for method
+   @endreturndesc
+
+   @version    $Header$
 @@*/
+
 int CCTK_RegisterIOMethod(const char *name)
 {
 
   int handle;
-
   struct IOMethod *new_method;
 
   /* Check that the method hasn't already been registered */
@@ -71,9 +83,9 @@ int CCTK_RegisterIOMethod(const char *name)
       /* Get a handle for it. */
       handle = CCTK_NewHandle(&IOMethods, name, new_method);
 
-      /* Initialise the IO method structure. */
-      new_method->OutputGH = DummyOutputGH;
-      new_method->OutputVarAs = DummyOutputVarAs;
+      /* Initialise the IO method structure with dummy routines */
+      new_method->OutputGH     = DummyOutputGH;
+      new_method->OutputVarAs  = DummyOutputVarAs;
       new_method->TimeToOutput = DummyTimeToOutput;
 
       /* Remember how many methods there are */
@@ -94,26 +106,43 @@ int CCTK_RegisterIOMethod(const char *name)
   return handle;
 }
 
-/***************************************************************************
- *
- *          Function Registration Routines.
- *
- ***************************************************************************/
 
  /*@@
    @routine    CCTK_RegisterIOMethodOutputGH
    @date       Wed Feb  3 13:34:12 1999
    @author     Tom Goodale
    @desc 
-   Registers a function to register a routine for OutputGH.
+               Registers a function to register a routine for OutputGH.
    @enddesc 
-   @calls     
+   @calls      CCTK_GetHandledData
    @calledby   
    @history 
- 
    @endhistory 
 
+   @var        handle
+   @vdesc      identifies the method in the stored data
+   @vtype      int
+   @vio        in
+   @vcomment 
+   @endvar 
+
+   @var        func
+   @vdesc      name of the routine for implementing OutputGH
+   @vtype      (* func)(cGH *)
+   @vio        in
+   @vcomment 
+   @endvar 
+
+   @returntype int
+   @returndesc
+               1 = function successfully registered
+               0 = function did not register
+   @endreturndesc
+
+   @version    $Header$
+
 @@*/
+
 int CCTK_RegisterIOMethodOutputGH(int handle, int (*func)(cGH *))
 {
   int return_code;
@@ -133,22 +162,45 @@ int CCTK_RegisterIOMethodOutputGH(int handle, int (*func)(cGH *))
   }
 
   return return_code;
-  }
+}
+
 
  /*@@
-   @routine    CCTK_RegisterIOMethodOutputVar
-   @date       Wed Feb  3 13:33:36 1999
+   @routine    CCTK_RegisterIOMethodOutputVarAs
+   @date       Wed Feb  3 13:34:12 1999
    @author     Tom Goodale
    @desc 
-   Registers a IO method OutputVarAs function.
+               Registers a function to register a routine for OutputVarAs
    @enddesc 
-   @calls     
+   @calls      CCTK_GetHandledData
    @calledby   
    @history 
- 
    @endhistory 
 
+   @var        handle
+   @vdesc      identifies the method in the stored data
+   @vtype      int
+   @vio        in
+   @vcomment 
+   @endvar 
+
+   @var        func
+   @vdesc      name of the routine for implementing OutputVarAs
+   @vtype      (* func)(cGH *, const char *,const char *)
+   @vio        in
+   @vcomment 
+   @endvar 
+
+   @returntype int
+   @returndesc
+               1 = function successfully registered
+               0 = function did not register
+   @endreturndesc
+
+   @version    $Header$
+
 @@*/
+
 int CCTK_RegisterIOMethodOutputVarAs(int handle, int (*func)(cGH *, 
                                     const char *,const char *))
 {
@@ -171,20 +223,43 @@ int CCTK_RegisterIOMethodOutputVarAs(int handle, int (*func)(cGH *,
   return return_code;
 }
 
+
  /*@@
-   @routine    CCTK_RegisterIOMethodTimeToOutput
-   @date       Sat 6 March 1999
+   @routine    CCTK_RegisterIOMethodOutputVarAs
+   @date       Sat March 6 1999
    @author     Gabrielle Allen
    @desc 
-   Registers a IO method TimeToOutput function.
+               Registers a function to register a routine for TimeToOutput
    @enddesc 
-   @calls     
+   @calls      CCTK_GetHandledData
    @calledby   
    @history 
- 
    @endhistory 
 
+   @var        handle
+   @vdesc      identifies the method in the stored data
+   @vtype      int
+   @vio        in
+   @vcomment 
+   @endvar 
+
+   @var        func
+   @vdesc      name of the routine for implementing TimeToOutput
+   @vtype      (* func)(cGH *, int)
+   @vio        in
+   @vcomment 
+   @endvar 
+
+   @returntype int
+   @returndesc
+               1 = function successfully registered
+               0 = function did not register
+   @endreturndesc
+
+   @version    $Header$
+
 @@*/
+
 int CCTK_RegisterIOMethodTimeToOutput(int handle, int (*func)(cGH *, int))
 {
   int return_code;
@@ -206,13 +281,14 @@ int CCTK_RegisterIOMethodTimeToOutput(int handle, int (*func)(cGH *, int))
   return return_code;
 }
 
+
+
 /************************************************************************
  *
  *  Dummy functions.  Registered if no real function registered.
  *
  ************************************************************************/
 
-
  /*@@
    @routine    DummyOutputGH
    @date       Wed Feb  3 13:36:52 1999
@@ -220,13 +296,8 @@ int CCTK_RegisterIOMethodTimeToOutput(int handle, int (*func)(cGH *, int))
    @desc 
    Dummy for OutputGH functions.
    @enddesc 
-   @calls     
-   @calledby   
-   @history 
- 
-   @endhistory 
-
 @@*/
+
 static int DummyOutputGH(cGH *GH)
 {
   return 0;
@@ -239,13 +310,8 @@ static int DummyOutputGH(cGH *GH)
    @desc 
    Dummy for TimeToOutput function.
    @enddesc 
-   @calls     
-   @calledby   
-   @history 
- 
-   @endhistory 
-
 @@*/
+
 static int DummyTimeToOutput(cGH *GH, int var)
 {
   return 0;
@@ -258,13 +324,8 @@ static int DummyTimeToOutput(cGH *GH, int var)
    @desc 
    Dummy for OutputVarAs functions.
    @enddesc 
-   @calls     
-   @calledby   
-   @history 
- 
-   @endhistory 
-
 @@*/
+
 static int DummyOutputVarAs(cGH *GH, 
                             const char *var, 
                             const char *alias)
@@ -274,6 +335,41 @@ static int DummyOutputVarAs(cGH *GH,
 
 
 
+/************************************************************************
+ *
+ *  Default functions for overloadable functions provided by IO methods
+ *
+ ************************************************************************/
+
+ /*@@
+   @routine    CactusDefaultOutputGH
+   @date       Sat March 6 1999
+   @author     Gabrielle Allen
+   @desc 
+               Loops over all methods calling each methods OutputGH 
+               routine
+   @enddesc 
+   @calls      IOMethod->OutputGH
+   @calledby   
+   @history 
+   @endhistory 
+
+   @var        GH
+   @vdesc      Pointer to Grid Hierachy
+   @vtype      cGH *
+   @vio        in
+   @vcomment 
+   @endvar 
+
+   @returntype int
+   @returndesc
+              -1    = No IO methods were found
+               i>=0 = Last handle used for output (number of IO methods-1)
+   @endreturndesc
+
+   @version    $Header$
+
+@@*/
 
 int CactusDefaultOutputGH(cGH *GH)
 {
@@ -289,11 +385,59 @@ int CactusDefaultOutputGH(cGH *GH)
     }
     else
     {
-      return handle;
+      return handle--;
     }
   }
 }
 
+
+ /*@@
+   @routine    CactusDefaultOutputVarAsByMethod
+   @date       Sat March 6 1999
+   @author     Gabrielle Allen
+   @desc 
+               Outputs one chosen variable by one chosen method
+   @enddesc 
+   @calls      
+   @history 
+   @endhistory 
+
+   @var        GH
+   @vdesc      Pointer to Grid Hierachy
+   @vtype      cGH *
+   @vio        in
+   @vcomment 
+   @endvar 
+
+   @var        var
+   @vdesc      Name of variable to output
+   @vtype      const char *
+   @vio        in
+   @vcomment 
+   @endvar 
+
+   @var        method
+   @vdesc      Name of method to use for output
+   @vtype      const char *
+   @vio        in
+   @vcomment 
+   @endvar 
+
+   @var        alias
+   @vdesc      Name variable should be output as
+   @vtype      const char *alias
+   @vio        in
+   @vcomment   Note that the IO method may not use this feature
+   @endvar 
+
+   @returntype int
+   @returndesc
+   @endreturndesc
+
+   @version    $Header$
+
+@@*/
+
 int CactusDefaultOutputVarAsByMethod(cGH *GH, 
                              const char *var,   
                              const char *methodname, 
@@ -304,22 +448,113 @@ int CactusDefaultOutputVarAsByMethod(cGH *GH,
 }
 
 
+
+/************************************************************************
+ *
+ *  More IO functions which perhaps should be overloadable
+ *
+ ************************************************************************/
+
+
+ /*@@
+   @routine    CactusOutputVarAs
+   @date       Sat March 6 1999
+   @author     Gabrielle Allen
+   @desc 
+               Loops over all methods for a given variable,
+               calling each methods OutputVarAs routine
+   @enddesc 
+   @calls      CCTK_GetHandledData
+               IOMethod->OutputVarAs
+   @history 
+   @endhistory 
+
+   @var        GH
+   @vdesc      Pointer to Grid Hierachy
+   @vtype      cGH *
+   @vio        in
+   @vcomment 
+   @endvar 
+
+   @var        var
+   @vdesc      Name of variable to output
+   @vtype      const char *
+   @vio        in
+   @vcomment 
+   @endvar 
+
+   @var        alias
+   @vdesc      Name variable should be output as
+   @vtype      const char *alias
+   @vio        in
+   @vcomment   Note that the IO method may not use this feature
+   @endvar 
+
+   @returntype int
+   @returndesc
+              -1    = No IO methods were found
+               i>=0 = Last handle used for output (number of IO methods-1)
+   @endreturndesc
+
+   @version    $Header$
+
+@@*/
+
+
 int CCTK_OutputVarAs(cGH *GH, const char *var, const char *alias)
 {
   int handle;
-  char *method;
+  struct IOMethod *method;
   
   for (handle = 0;;handle++)
   {
-    method = CCTK_GetHandleName(IOMethods, handle);
-    printf("Method is %s\n",method);
-    CCTK_OutputVarAsByMethod(GH, var, method, alias);
+    method = (struct IOMethod *)CCTK_GetHandledData(IOMethods, handle);
+    if (method)
+    {
+      method->OutputVarAs(GH, var, alias);
+    }
+    else
+    {
+      return handle--;
+    }
   }
-  
-  return 0;
 }
 
 
+ /*@@
+   @routine    CactusOutputVar
+   @date       Sat March 6 1999
+   @author     Gabrielle Allen
+   @desc 
+               Outputs a variable using all methods and no alias
+   @enddesc 
+   @calls      CCTK_OutputVarAs
+   @history 
+   @endhistory 
+
+   @var        GH
+   @vdesc      Pointer to Grid Hierachy
+   @vtype      cGH *
+   @vio        in
+   @vcomment 
+   @endvar 
+
+   @var        var
+   @vdesc      Name of variable to output
+   @vtype      const char *
+   @vio        in
+   @vcomment   This is also the name the variable will be output as
+   @endvar 
+
+   @returntype int
+   @returndesc
+               0    = always returns this
+   @endreturndesc
+
+   @version    $Header$
+
+@@*/
+
 int CCTK_OutputVar(cGH *GH, const char *var)
 {
   CCTK_OutputVarAs(GH, var, var);
@@ -328,6 +563,47 @@ int CCTK_OutputVar(cGH *GH, const char *var)
 }
 
 
+ /*@@
+   @routine    CactusOutputVarByMethods
+   @date       Sat March 6 1999
+   @author     Gabrielle Allen
+   @desc 
+               Outputs a variable using one given method and no alias
+   @enddesc 
+   @calls      CCTK_OutputVarAsByMethod
+   @history 
+   @endhistory 
+
+   @var        GH
+   @vdesc      Pointer to Grid Hierachy
+   @vtype      cGH *
+   @vio        in
+   @vcomment 
+   @endvar 
+
+   @var        var
+   @vdesc      Name of variable to output
+   @vtype      const char *
+   @vio        in
+   @vcomment   This is also the name the variable will be output as
+   @endvar 
+
+   @var        method
+   @vdesc      Name of method to use for output
+   @vtype      const char *
+   @vio        in
+   @vcomment 
+   @endvar 
+
+   @returntype int
+   @returndesc
+               0    = always returns this
+   @endreturndesc
+
+   @version    $Header$
+
+@@*/
+
 int CCTK_OutputVarByMethod(cGH *GH, const char *var, const char *method)
 {
   CCTK_OutputVarAsByMethod(GH, var, method, var);
@@ -336,25 +612,46 @@ int CCTK_OutputVarByMethod(cGH *GH, const char *var, const char *method)
 }
 
 
+/************************************************************************
+ *
+ *  These routines are here because they need to get at IOMethods
+ *
+ ************************************************************************/
+
  /*@@
    @routine    CCTK_rfrTriggerSaysGo
    @date       Sat March 6 1999
    @author     Gabrielle Allen
    @desc 
-   Checks if a triggers registered for a routine is
-   due for output by any IO method.
+               Checks if a trigger registered for a routine is
+               due for output by any IO method.
    @enddesc 
-   @calls     
-   @calledby   
-   @history 
- 
+   @calls      CCTK_GetHandledData
+               IOMethod->TimeToOutput
+   @history  
    @endhistory 
-   @var     variable
-   @vdesc   GH variable index
-   @vtype   int
-   @vio     in
+
+   @var        GH
+   @vdesc      Pointer to Grid Hierachy
+   @vtype      cGH *
+   @vio        in
    @vcomment 
    @endvar 
+
+   @var        variable
+   @vdesc      GH variable index
+   @vtype      int
+   @vio        in
+   @vcomment 
+   @endvar 
+
+   @returntype int
+   @returndesc
+               0    = Trigger says don't output me this iteration
+	       1    = Trigger says output me this iteration
+   @endreturndesc
+
+   @version    $Header$
  */
 
 int CCTK_rfrTriggerSaysGo(cGH *GH, int variable)
@@ -363,17 +660,20 @@ int CCTK_rfrTriggerSaysGo(cGH *GH, int variable)
   int flag;
   struct IOMethod *method;
 
+  /* Loop over all registered IO methods */
   for (handle = 0;;handle++)
   {
     method = (struct IOMethod *)CCTK_GetHandledData(IOMethods, handle);
     if (method)
     {
+      /* Check if it is time to output this variable for this method*/
       flag = method->TimeToOutput(GH, variable);
       if (flag) 
 	return 1;
     }
     else
     {
+      /* There are no more methods left, so the variable will not be output */
       return 0;
     }
   }
@@ -381,34 +681,85 @@ int CCTK_rfrTriggerSaysGo(cGH *GH, int variable)
 }
 
 
+ /*@@
+   @routine    CCTK_rfrTriggerAction
+   @date       Sat March 6 1999
+   @author     Gabrielle Allen
+   @desc 
+               Essentially the same as CCTK_rfrTriggerSaysGo, 
+               but now calls each IO method for which it is 
+               time to output the trigger
+   @enddesc 
+   @calls      CCTK_GetHandledData
+               CCTK_GetFullName
+	       CCTK_GetVarName
+               IOMethod->TimeToOutput
+	       IOMethod->OutputVarAs
+   @history  
+   @endhistory 
+
+   @var        GH
+   @vdesc      Pointer to Grid Hierachy
+   @vtype      cGH *
+   @vio        in
+   @vcomment 
+   @endvar 
+
+   @var        variable
+   @vdesc      GH variable index
+   @vtype      int
+   @vio        in
+   @vcomment 
+   @endvar 
+
+   @returntype int
+   @returndesc
+               0    = This should never happen, since at least
+                      one IO method should have been found by
+		      CCTK_rfrTriggerSaysGo
+	       >0   = Number of IO methods called for output for
+                      this variable
+   @endreturndesc
 
+   @version    $Header$
+ */
 
 int CCTK_rfrTriggerAction(void *GH, int variable)
 {
   char *varname;
   char *fullvarname;
   int handle;
-  int flag;
+  int nmethods;
   struct IOMethod *method;
 
   fullvarname = CCTK_GetFullName(variable);
   varname = CCTK_GetVarName(variable);
 
+  /* Count the number of methods used */
+  nmethods = 0;
+
+  /* Loop over all registered IO methods */
   for (handle = 0;;handle++)
   {
     method = (struct IOMethod *)CCTK_GetHandledData(IOMethods, handle);
     if (method)
     {
-      flag = method->TimeToOutput(GH, variable);
-      if (flag) 
+      /* Check if it is time to output this variable for this method*/
+      if (method->TimeToOutput(GH, variable))
       {
+	/* And if so do call the output routine for the method */
 	method->OutputVarAs(GH,fullvarname,varname);
+	nmethods++;
       }
     }
     else
     {
+      /* There are no methods left */
+
+      /* This was assigned by CCTK_GetFullName */
       free(fullvarname);
-      return 0;
+
+      return nmethods;
     }
   }
 }