Added stuff for file advertising. I'd be happy for suggestions on shorter names.

Here is some explanation how to use it:
The routine

  int IOUtil_RegisterAdvertisedFileListener (cGH *GH,
                                             const char *listener,
                    const IOUtil_AdvertisedFileListenerCallbacks_t *callbacks);

registers a listener with its own callbacks for file advertising.
For the time being the only function pointer in the callback structure is

  int (*advertise) (cGH *GH,
                    const char *filename,
                    const IOUtil_AdvertisedFileDesc_t *description);

which gets passed the filename and a structure with information on the
file to be advertised.

Any IO methods which want to advertise a file do this by calling

  int IOUtil_AdvertiseFile (cGH *GH,
                            const char *filename,
                            const IOUtil_AdvertisedFileDesc_t *desc);

This routine simply loops through all registered listeners and calls their
advertise() callback.


git-svn-id: http://svn.cactuscode.org/arrangements/CactusBase/IOUtil/trunk@73 b32723a9-ab3a-4a60-88e2-2e5d99d7c17a

2 files changed, 174 insertions, 0 deletions

diff --git a/src/GHExtension.c b/src/GHExtension.c
index 44f075b..5d923c6 100644
--- a/src/GHExtension.c
+++ b/src/GHExtension.c
@@ -16,6 +16,7 @@
 #include <stdio.h>
 
 #include "cctk.h"
+#include "util_String.h"
 #include "cctk_Parameters.h"
 #include "ioGH.h"
 
@@ -161,6 +162,9 @@ int IOUtil_InitGH (cGH *GH)
   myGH->sp2xyz = (int *) calloc (GH->cctk_dim, sizeof (int));
   SetupSliceCenter (GH);
 
+  /* initialize the file advertising listeners database */
+  myGH->listener_DB = NULL;
+
   return 0;
 }
 
@@ -302,6 +306,121 @@ void ParseVarsForOutput (const char *var_list, char do_output [])
 }
 
 
+ /*@@
+   @routine    IOUtil_RegisterAdvertisedFileListener
+   @date       Wed May 17 2000
+   @author     Thomas Radke
+   @desc 
+               Registers a listener with its callbacks for
+               advertised file handling
+   @enddesc 
+   @history 
+   @endhistory 
+   @var        GH
+   @vdesc      pointer to grid hierarchy
+   @vtype      cGH *
+   @vio        in
+   @endvar
+   @var        listener
+   @vdesc      identification of the listener to be registered
+   @vtype      const char *
+   @vio        in
+   @endvar 
+   @var        callbacks
+   @vdesc      structure containing the listener's callback routines
+   @vtype      const IOUtil_AdvertisedFileListenerCallbacks_t *
+   @vio        in
+   @endvar 
+   @returntype int
+   @returndesc This routine returns
+                  0  on success
+                  -1 if memory allocation failed or NULL pointers were passed
+   @endreturndesc
+@@*/
+
+int IOUtil_RegisterAdvertisedFileListener (cGH *GH, const char *listener,
+                     const IOUtil_AdvertisedFileListenerCallbacks_t *callbacks)
+{
+  ioGH *myGH;
+  int retval = -1;
+  IOUtil_AdvertisedFileListenerCallbacks_t *new_callbacks;
+
+
+  if (listener && callbacks)
+  {
+    new_callbacks = (IOUtil_AdvertisedFileListenerCallbacks_t *)
+                     malloc (sizeof (IOUtil_AdvertisedFileListenerCallbacks_t));
+    if (new_callbacks)
+    {
+      *new_callbacks = *callbacks;
+      myGH = (ioGH *) GH->extensions [CCTK_GHExtensionHandle ("IO")];
+      retval = StoreNamedData (&myGH->listener_DB, listener, new_callbacks);
+      if (retval)
+        free (new_callbacks);
+    }
+  }
+
+  return (retval);
+}
+
+
+ /*@@
+   @routine    IOUtil_AdvertiseFile
+   @date       Wed May 17 2000
+   @author     Thomas Radke
+   @desc 
+               Adds a filename to the list of advertised files for downloading.
+               The routine calls all listeners which are currently registered
+               for advertised file handling.
+   @enddesc 
+   @history 
+   @endhistory 
+   @var        GH
+   @vdesc      pointer to grid hierarchy
+   @vtype      cGH *
+   @vio        in
+   @endvar
+   @var        filename
+   @vdesc      name of the file to advertise
+   @vtype      const char *
+   @vio        in
+   @endvar 
+   @var        description
+   @vdesc      structure which describes the file
+   @vtype      const IOUtil_AdvertisedFileDesc_t *
+   @vio        in
+   @endvar 
+   @returntype int
+   @returndesc This routine returns the logically OR'ed return values
+               of all listeners' advertise callbacks called.
+   @endreturndesc
+@@*/
+
+int IOUtil_AdvertiseFile (cGH *GH, const char *filename,
+                          const IOUtil_AdvertisedFileDesc_t *description)
+{
+  int retval = 0;
+  pNamedData *listener;
+  IOUtil_AdvertisedFileListenerCallbacks_t *callbacks;
+
+
+  /* get the listener database from IOUtil's GH extension */
+  listener = ((ioGH *)
+              GH->extensions [CCTK_GHExtensionHandle ("IO")])->listener_DB;
+
+  /* loop through all listeners' advertise() callbacks */
+  while (listener)
+  {
+    callbacks = (IOUtil_AdvertisedFileListenerCallbacks_t *) listener->data;
+    if (callbacks && callbacks->advertise)
+      retval |= (callbacks->advertise) (GH, filename, description);
+    listener = listener->next;
+  }
+
+  return (retval);
+}
+
+
 /****************************************************************************/
 /* local routines                                                           */
 /****************************************************************************/
diff --git a/src/ioGH.h b/src/ioGH.h
index f694d5f..e2ca749 100644
--- a/src/ioGH.h
+++ b/src/ioGH.h
@@ -16,6 +16,44 @@
  @@*/
 
 
+#ifdef __cplusplus
+extern "C"
+{
+#endif
+
+
+#include "StoreNamedData.h"
+
+
+/* structure describing an advertised file
+   It contains pointer to strings holding
+     - the thorn which created the file
+     - the variable name the file contents data belongs to
+     - the MIME type for the file format used
+     - a short slice string indication the dimensionality of the data
+     - an arbitrary additional description of the file contents */
+typedef struct
+{
+  char *thorn;
+  char *varname;
+  char *mimetype;
+  char *slice;
+  char *description;
+} IOUtil_AdvertisedFileDesc_t;
+
+
+/* structure containing function pointers for handling with advertised files
+   For the moment it contains only a registration routine for new files to
+   be advertised. In the future we might also want something like
+   unadvertising, or notification when the contents of the file changed. */
+typedef struct
+{
+  int (*advertise) (cGH *GH, const char *filename,
+                    const IOUtil_AdvertisedFileDesc_t *description);
+} IOUtil_AdvertisedFileListenerCallbacks_t;
+
+
+/* IOUtil's GH extension structure */
 typedef struct IOGH {
 
 #if 0
@@ -57,6 +95,9 @@ typedef struct IOGH {
   /* for data file reader */
   char *do_inVars;  /* flags indicating to read in variable [i] */
 
+  /* database holding all registered listeners for file advertising */
+  pNamedData *listener_DB;
+
 } ioGH;
 
 /* enums for checkpointing/recovery and filereader functions */
@@ -79,3 +120,17 @@ extern int IOUtil_RecoverParameters (int (*recoverFn) (cGH *GH,
                                      const char *fileType);
 extern char *IOUtil_GetAllParameters (cGH *GH);
 extern void IOUtil_SetAllParameters (char *parameters);
+
+/*** routines to handle with file advertising ***/
+/* register a new listener with its own callbacks for file advertising */
+extern int IOUtil_RegisterAdvertisedFileListener (cGH *GH,
+                                                  const char *listener,
+                    const IOUtil_AdvertisedFileListenerCallbacks_t *callbacks);
+/* advertise a file */
+extern int IOUtil_AdvertiseFile (cGH *GH,
+                                 const char *filename,
+                                 const IOUtil_AdvertisedFileDesc_t *desc);
+
+#ifdef __cplusplus
+}
+#endif