[svn-r23350] I cleaned up some code and added comments for my previous checkin of the DESY project.

Tested on koala.

9 files changed, 142 insertions, 59 deletions

diff --git a/src/H5PL.c b/src/H5PL.c
index 4bf059c..afa1785 100644
--- a/src/H5PL.c
+++ b/src/H5PL.c
@@ -57,7 +57,7 @@ H5PL_init_interface(void)
 /*-------------------------------------------------------------------------
  * Function:	H5PL_term_interface
  *
- * Purpose:	Terminate the H5I interface: release all memory, reset all
+ * Purpose:	Terminate the H5PL interface: release all memory, reset all
  *		global variables to initial values. This only happens if all
  *		types have been destroyed from other interfaces.
  *
@@ -69,6 +69,8 @@ H5PL_init_interface(void)
  * Programmer:	Raymond Lu
  *              20 February 2013
  *
+ * Modifications:
+ *
  *-------------------------------------------------------------------------
  */
 int
@@ -80,16 +82,17 @@ H5PL_term_interface(void)
     FUNC_ENTER_NOAPI_NOINIT_NOERR
 
     if(H5_interface_initialize_g) {
-	/* Free the table of dynamic libraries */
+	/* Close opened dynamic libraries */
         for(i=0; i<H5PL_table_used_g; i++) { 
             handle = (H5PL_table_g[i]).handle;
-/*fprintf(stderr, "%s: handle=%p\n", FUNC, handle);*/
             H5PL_close(handle);
         }
 
+	/* Free the table of dynamic libraries */
 	H5PL_table_g = (H5PL_table_t *)H5MM_xfree(H5PL_table_g);
 	H5PL_table_used_g = H5PL_table_alloc_g = 0;
 
+        /* Free the table of search paths */
         for(i = 0; i < num_paths; i++) {
             if(path_table[i])
                 path_table[i] = H5MM_xfree(path_table[i]);
@@ -109,7 +112,9 @@ H5PL_term_interface(void)
 /*-------------------------------------------------------------------------
  * Function:	H5PL_load
  *
- * Purpose:	
+ * Purpose:	Given the plugin type and identifier, this function searches
+ *              and/or loads a dynamic plugin library first among the already
+ *              opened libraries then in the designated location paths.
  *
  * Return:	Non-negative on success/Negative on failure
  *
@@ -149,7 +154,10 @@ H5PL_load(H5PL_type_t type, int id)
         HGOTO_DONE(ret_value)
     }
 
+    /* Find the location paths for dynamic libraries */
     if(FALSE == path_found) {
+        /* Retrieve paths from HDF5_PLUGIN_PATH if the user sets it
+         * or from the default paths if it isn't set */
         origin_dl_path = HDgetenv("HDF5_PLUGIN_PATH");
         if(origin_dl_path == NULL) {
             len = HDstrlen(H5PL_DEFAULT_PATH) + 1;
@@ -162,6 +170,7 @@ H5PL_load(H5PL_type_t type, int id)
             HDstrncpy(dl_path, origin_dl_path, len);
         }
 
+        /* Put paths in the path table.  They are seperated by ":" */
         dir = HDstrtok(dl_path, H5PL_PATH_SEPERATOR);
         while(dir) {
             path_table[num_paths] = (char *)HDmalloc(HDstrlen(dir) + 1);
@@ -174,9 +183,8 @@ H5PL_load(H5PL_type_t type, int id)
         path_found = TRUE;
     }
 
-#ifndef TMP
+    /* Iterate through the path table to find the right dynamic libraries */
     for(i=0; i<num_paths; i++) {
-        /*fprintf(stderr, "path[%d]=%s\n", i, path_table[i]);*/
         if((found_in_path = H5PL_find(type, id, path_table[i], &plugin_info)) < 0)
             HGOTO_ERROR(H5E_PLUGIN, H5E_CANTGET, NULL, "search in paths failed")
  
@@ -186,7 +194,6 @@ H5PL_load(H5PL_type_t type, int id)
             HGOTO_DONE(ret_value)
         }
     }
-#endif
 
 done:
     if(dl_path)
@@ -231,11 +238,13 @@ H5PL_find(H5PL_type_t plugin_type, int type_id, char *dir, void **info)
 
     FUNC_ENTER_NOAPI(FAIL)
 
-  
-        if(dirp = HDopendir(dir)) {
-            struct dirent *dp = NULL;
-            struct stat my_stat;
-            while ((dp = HDreaddir(dirp)) != NULL) {
+    /* Open the directory */  
+    if(dirp = HDopendir(dir)) {
+        struct dirent *dp = NULL;
+        struct stat my_stat;
+        /* Iterates through all entries in the directory to find the right plugin library */
+        while ((dp = HDreaddir(dirp)) != NULL) {
+                   /* The library we are looking for should be called libxxx.so... */ 
                    if(!HDstrncmp(dp->d_name, "lib", 3) && HDstrstr(dp->d_name, ".so")) {
                        pathname = (char *)H5MM_malloc(strlen(dir) + strlen(dp->d_name) + 2); 
                        HDstrncpy(pathname, dir, strlen(dir)+1);
@@ -248,21 +257,25 @@ H5PL_find(H5PL_type_t plugin_type, int type_id, char *dir, void **info)
                        if(HDstat(pathname, &my_stat) == -1)
                            HGOTO_ERROR(H5E_FILE, H5E_CANTGET, FAIL, "can't stat file: %s", strerror(errno))
                        
-                       if(!S_ISDIR(my_stat.st_mode)) { /* if directory, skip it */
+                       if(!S_ISDIR(my_stat.st_mode)) { /* if it is a directory, skip it */
                            if(NULL == (handle = dlopen(pathname, RTLD_NOW|RTLD_LAZY))) {
                                /*fprintf(stderr, "not open dl library: %s", dlerror());*/
-                               if(!HDstrcmp(dp->d_name, "libbogus2.so"))
-                                   HGOTO_ERROR(H5E_DATATYPE, H5E_CANTCOPY, FAIL, "can't open dl library: %s", dlerror())
-                               else
-                                   continue;
+                               /* There are different reasons why a library can't be open, e.g. wrong architecture.
+                                * simply continue if we can't open it */
+                               continue;
                            }
 
-                           dlerror(); /*clear error*/ 
+                           dlerror(); /*clear error*/
+    
+                           /* Return a handle for the function H5PL_get_plugin_info in the dynamic library.
+                            * The plugin library is suppose to define this function. */
                            if(NULL == (H5PL_get_plugin_info = dlsym(handle, "H5PL_get_plugin_info"))) {
                                if(H5PL_close(handle) < 0)
                                    HGOTO_ERROR(H5E_PLUGIN, H5E_CLOSEERROR, FAIL, "can't close dynamic library")
                            }
 
+                           /* Envoke H5PL_get_plugin_info to verify this is the right library we are looking for.
+                            * Move on if it isn't. */
                            if(H5PL_get_plugin_info) {
                                if(NULL == (plugin_info = (*H5PL_get_plugin_info)())) {
                                    if(H5PL_close(handle) < 0)
@@ -289,13 +302,13 @@ H5PL_find(H5PL_type_t plugin_type, int type_id, char *dir, void **info)
                        if(pathname) 
                            pathname = (char *)H5MM_xfree(pathname);
                    }
-            }
-
-            if(HDclosedir(dirp) < 0)
-                HGOTO_ERROR(H5E_FILE, H5E_CLOSEERROR, FAIL, "can't close directory: %s", strerror(errno))
-            dirp = NULL;
         }
 
+        if(HDclosedir(dirp) < 0)
+            HGOTO_ERROR(H5E_FILE, H5E_CLOSEERROR, FAIL, "can't close directory: %s", strerror(errno))
+        dirp = NULL;
+    }
+
 
 done:
     if(pathname) 
@@ -310,7 +323,8 @@ done:
 /*-------------------------------------------------------------------------
  * Function:	H5PL_search_table
  *
- * Purpose:	
+ * Purpose:     Search in the list of already opened dynamic libraries
+ *              to see if the one we are looking for is already opened.
  *
  * Return:	TRUE on success, 
  *              FALSE on not found,
@@ -355,7 +369,7 @@ fprintf(stderr, "%s: H5PL_table_used_g=%d, id=%d\n", FUNC, H5PL_table_used_g, (H
         }
     }
 
-    /* Expand the table if it is small */
+    /* Expand the table if it is too small */
     if(H5PL_table_used_g >= H5PL_table_alloc_g) {
         size_t n = MAX(H5Z_MAX_NFILTERS, 2*H5PL_table_alloc_g);
         H5PL_table_t *table = (H5PL_table_t *)H5MM_realloc(H5PL_table_g, n * sizeof(H5PL_table_t));
@@ -375,7 +389,7 @@ done:
 /*-------------------------------------------------------------------------
  * Function:	H5PL_close
  *
- * Purpose:	
+ * Purpose:     Closes the handle for dynamic library	
  *
  * Return:	Non-negative on success/Negative on failure
  *
diff --git a/src/H5PLpkg.h b/src/H5PLpkg.h
index adbe38a..dae4c59 100644
--- a/src/H5PLpkg.h
+++ b/src/H5PLpkg.h
@@ -29,6 +29,7 @@
 /* Local typedefs */
 /****************************/
 
+/* Type for the list of info for opened plugin libraries */
 typedef struct H5PL_table_t {
     H5PL_type_t pl_type;			/* plugin type	     */
     int         pl_id;                          /* ID for the plugin */
@@ -39,10 +40,12 @@ typedef struct H5PL_table_t {
 /* Local variables */
 /****************************/
 
+/* Table for opened plugin libraries */
 static size_t		H5PL_table_alloc_g = 0;
 static size_t		H5PL_table_used_g = 0;
 static H5PL_table_t     *H5PL_table_g = NULL;
 
+/* Table of location paths for plugin libraries */
 static char             *path_table[MAX_PATH_NUM];
 static size_t           num_paths = 0;
 static htri_t           path_found = FALSE;
diff --git a/src/H5PLpublic.h b/src/H5PLpublic.h
index 1f21f88..4c4a669 100644
--- a/src/H5PLpublic.h
+++ b/src/H5PLpublic.h
@@ -27,6 +27,7 @@
 /* Library Public Typedefs */
 /****************************/
 
+/* Plugin type */
 typedef enum H5PL_type_t {
     H5PL_TYPE_ERROR        = -1,  /*error                    */
     H5PL_TYPE_FILTER       = 0,   /*filter                   */
diff --git a/src/H5Zpublic.h b/src/H5Zpublic.h
index b5ac475..24496e4 100644
--- a/src/H5Zpublic.h
+++ b/src/H5Zpublic.h
@@ -43,10 +43,12 @@ typedef int H5Z_filter_t;
 #define H5Z_FILTER_SCALEOFFSET  6       /*scale+offset compression      */
 #define H5Z_FILTER_RESERVED     256	/*filter ids below this value are reserved for library use */
 
+/* Filters for HDF5 internal test */
 #define H5Z_FILTER_DYNLIB1      257
 #define H5Z_FILTER_DYNLIB2      258 
 
-#define H5Z_FILTER_BZIP2        300
+/* Registered third-party filters */
+#define H5Z_FILTER_BZIP2        307
 
 #define H5Z_FILTER_MAX		65535	/*maximum filter id		*/
 
diff --git a/test/plugin.c b/test/plugin.c
index 4385916..debc38b 100644
--- a/test/plugin.c
+++ b/test/plugin.c
@@ -188,7 +188,7 @@ int	points_deflate[DSET_DIM1][DSET_DIM2],
 /*-------------------------------------------------------------------------
  * Function:	test_filter_internal
  *
- * Purpose:	Tests 
+ * Purpose:	Tests writing entire data and partial data with filters  
  *
  * Return:	Success:	0
  *		Failure:	-1
@@ -417,6 +417,8 @@ test_filter_internal(hid_t fid, const char *name, hid_t dcpl, hsize_t *dset_size
 
     PASSED();
 
+    /* Save the data written to the file for later comparison when the file 
+     * is reopened for read test */
     for(i=0; i<size[0]; i++) {
         for(j=0; j<size[1]; j++) {
             if(!HDstrcmp(name, DSET_DEFLATE_NAME)) {
@@ -450,13 +452,14 @@ error:
 /*-------------------------------------------------------------------------
  * Function:	test_filters
  *
- * Purpose:	Tests dataset filter.
+ * Purpose:	Tests creating datasets and writing data with dynamically
+ *              loaded filters
  *
  * Return:	Success:	0
  *		Failure:	-1
  *
- * Programmer:	Robb Matzke
- *              Wednesday, April 15, 1998
+ * Programmer:	Raymond Lu
+ *              14 March 2013
  *
  *-------------------------------------------------------------------------
  */
@@ -501,8 +504,10 @@ test_filters(hid_t file, hid_t fapl)
     if(H5Pset_filter (dc, H5Z_FILTER_DYNLIB1, H5Z_FLAG_MANDATORY, 1, &compress_level) < 0) goto error;
 
     if(test_filter_internal(file,DSET_DYNLIB1_NAME,dc,&deflate_size) < 0) goto error;
+
     /* Clean up objects used for this test */
     if(H5Pclose (dc) < 0) goto error;
+
     /* Unregister the dynamic filter DYNLIB1 for testing purpose. The next time when this test is run for 
      * the new file format, the library's H5PL code has to search in the table of loaded plugin libraries
      * for this filter. */
@@ -519,9 +524,11 @@ test_filters(hid_t file, hid_t fapl)
     if(H5Pset_filter (dc, H5Z_FILTER_DYNLIB2, H5Z_FLAG_MANDATORY, 1, &compress_level) < 0) goto error;
 
     if(test_filter_internal(file,DSET_DYNLIB2_NAME,dc,&deflate_size) < 0) goto error;
+
     /* Clean up objects used for this test */
     if(H5Pclose (dc) < 0) goto error;
-    /* Unregister the dynamic filter BOGUS for testing purpose. The next time when this test is run for 
+
+    /* Unregister the dynamic filter DYNLIB2 for testing purpose. The next time when this test is run for 
      * the new file format, the library's H5PL code has to search in the table of loaded plugin libraries
      * for this filter. */
     if(H5Zunregister(H5Z_FILTER_DYNLIB2) < 0) goto error;
@@ -537,8 +544,10 @@ test_filters(hid_t file, hid_t fapl)
     if(H5Pset_filter (dc, H5Z_FILTER_BZIP2, H5Z_FLAG_MANDATORY, 1, &compress_level) < 0) goto error;
 
     if(test_filter_internal(file,DSET_BZIP2_NAME,dc,&deflate_size) < 0) goto error;
+
     /* Clean up objects used for this test */
     if(H5Pclose (dc) < 0) goto error;
+
     /* Unregister the dynamic filter BOGUS for testing purpose. The next time when this test is run for 
      * the new file format, the library's H5PL code has to search in the table of loaded plugin libraries
      * for this filter. */
@@ -554,13 +563,13 @@ error:
 /*-------------------------------------------------------------------------
  * Function:	test_read_data
  *
- * Purpose:	Tests dataset filter.
+ * Purpose:	Tests reading data and compares values
  *
  * Return:	Success:	0
  *		Failure:	-1
  *
- * Programmer:	Robb Matzke
- *              Wednesday, April 15, 1998
+ * Programmer:	Raymond Lu
+ *              14 March 2013
  *
  *-------------------------------------------------------------------------
  */
@@ -601,13 +610,13 @@ error:
 /*-------------------------------------------------------------------------
  * Function:	test_read_with_filters
  *
- * Purpose:	Tests dataset filter.
+ * Purpose:	Tests reading dataset created with dynamically loaded filters
  *
  * Return:	Success:	0
  *		Failure:	-1
  *
- * Programmer:	Robb Matzke
- *              Wednesday, April 15, 1998
+ * Programmer:	Raymond Lu
+ *              14 March 2013
  *
  *-------------------------------------------------------------------------
  */
@@ -693,14 +702,14 @@ error:
 /*-------------------------------------------------------------------------
  * Function:	main
  *
- * Purpose:	Tests the dataset interface (H5D)
+ * Purpose:	Tests the plugin module (H5PL)
  *
  * Return:	Success:	exit(0)
  *
  *		Failure:	exit(1)
  *
- * Programmer:	Robb Matzke
- *		Tuesday, December  9, 1997
+ * Programmer:	Raymond Lu
+ *		14 March 2013
  *
  *-------------------------------------------------------------------------
  */
@@ -715,15 +724,6 @@ main(void)
     size_t rdcc_nbytes;
     double rdcc_w0;
     int	nerrors = 0;
-    const char *envval;
-
-    /* Don't run this test using certain file drivers */
-    envval = HDgetenv("HDF5_DRIVER");
-    if(envval == NULL)
-        envval = "nomatch";
-
-    /* Set the random # seed */
-    HDsrandom((unsigned)HDtime(NULL));
 
     /* Testing setup */
     h5_reset();
@@ -762,14 +762,7 @@ main(void)
         if((file = H5Fcreate(filename, H5F_ACC_TRUNC, H5P_DEFAULT, my_fapl)) < 0)
             TEST_ERROR 
 
-        /* Cause the library to emit initial messages */
-        if((grp = H5Gcreate2(file, "emit diagnostics", H5P_DEFAULT, H5P_DEFAULT, H5P_DEFAULT)) < 0)
-            TEST_ERROR 
-        if(H5Oset_comment(grp, "Causes diagnostic messages to be emitted") < 0)
-            TEST_ERROR 
-        if(H5Gclose(grp) < 0)
-            TEST_ERROR 
-
+        /* Test dynamically loaded filters */
         nerrors += (test_filters(file, my_fapl) < 0		? 1 : 0);
 
         if(H5Fclose(file) < 0)
@@ -790,6 +783,7 @@ main(void)
     if((file = H5Fopen(filename, H5F_ACC_RDONLY, fapl)) < 0)
         TEST_ERROR 
 
+    /* Read the data with filters */
     nerrors += (test_read_with_filters(file, fapl) < 0		? 1 : 0);
 
     if(H5Fclose(file) < 0)
diff --git a/test/plugin_lib/Makefile.in b/test/plugin_lib/Makefile.in
index aecb36e..83d350c 100644
--- a/test/plugin_lib/Makefile.in
+++ b/test/plugin_lib/Makefile.in
@@ -1,3 +1,22 @@
+# Copyright by The HDF Group.
+# Copyright by the Board of Trustees of the University of Illinois.
+# All rights reserved.
+#
+# This file is part of HDF5.  The full HDF5 copyright notice, including
+# terms governing use, modification, and redistribution, is contained in
+# the files COPYING and Copyright.html.  COPYING can be found at the root
+# of the source code distribution tree; Copyright.html can be found at the
+# root level of an installed copy of the electronic HDF5 document set and
+# is linked from the top-level documents page.  It can also be found at
+# http://hdfgroup.org/HDF5/doc/Copyright.html.  If you do not have
+# access to either file, you may request a copy from help@hdfgroup.org.
+#
+# HDF5 Library Test Makefile(.in)
+#
+# This Makefile.in is NOT generated by automake.  Since we want to build 
+# shared libraries for testing, automake can't create shared libraries when
+# configure asks to build static library.
+#
 CFLAGS = -fPIC -g
 CC = @CC@
 SRCDIR = @srcdir@
diff --git a/test/plugin_lib/dynlib1.c b/test/plugin_lib/dynlib1.c
index 619fe66..4b57ddb 100644
--- a/test/plugin_lib/dynlib1.c
+++ b/test/plugin_lib/dynlib1.c
@@ -1,3 +1,24 @@
+/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
+ * Copyright by The HDF Group.                                               *
+ * Copyright by the Board of Trustees of the University of Illinois.         *
+ * All rights reserved.                                                      *
+ *                                                                           *
+ * This file is part of HDF5.  The full HDF5 copyright notice, including     *
+ * terms governing use, modification, and redistribution, is contained in    *
+ * the files COPYING and Copyright.html.  COPYING can be found at the root   *
+ * of the source code distribution tree; Copyright.html can be found at the  *
+ * root level of an installed copy of the electronic HDF5 document set and   *
+ * is linked from the top-level documents page.  It can also be found at     *
+ * http://hdfgroup.org/HDF5/doc/Copyright.html.  If you do not have          *
+ * access to either file, you may request a copy from help@hdfgroup.org.     *
+ * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
+
+/*
+ * Programmer:	Raymond Lu
+ *		13 February 2013
+ *
+ * Purpose:	Tests the plugin module (H5PL)
+ */
 #include "dynlib1.h"
 
 /* This message derives from H5Z */
diff --git a/test/plugin_lib/dynlib1.h b/test/plugin_lib/dynlib1.h
index f255ee4..5d68780 100644
--- a/test/plugin_lib/dynlib1.h
+++ b/test/plugin_lib/dynlib1.h
@@ -1,9 +1,35 @@
+/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
+ * Copyright by The HDF Group.                                               *
+ * Copyright by the Board of Trustees of the University of Illinois.         *
+ * All rights reserved.                                                      *
+ *                                                                           *
+ * This file is part of HDF5.  The full HDF5 copyright notice, including     *
+ * terms governing use, modification, and redistribution, is contained in    *
+ * the files COPYING and Copyright.html.  COPYING can be found at the root   *
+ * of the source code distribution tree; Copyright.html can be found at the  *
+ * root level of an installed copy of the electronic HDF5 document set and   *
+ * is linked from the top-level documents page.  It can also be found at     *
+ * http://hdfgroup.org/HDF5/doc/Copyright.html.  If you do not have          *
+ * access to either file, you may request a copy from help@hdfgroup.org.     *
+ * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
+
+/*
+ * Programmer:	Raymond Lu
+ *		13 February 2013
+ *
+ * Purpose:	Tests the plugin module (H5PL)
+ */
 #include <stdlib.h>
 #include <stdio.h>
 #include <hdf5.h>
 
 #define FILTER_DYNLIB1_VERS 1
 
+const H5PL_type_t   H5PL_get_plugin_type(void);
+const int           H5PL_get_plugin_version(void);
+const char*         H5PL_get_plugin_name(void);
+const H5Z_class2_t* H5PL_get_plugin_info(void);
+
 /* Local prototypes for filter functions */
 static size_t H5Z_filter_dynlib1(unsigned int flags, size_t cd_nelmts,
     const unsigned int *cd_values, size_t nbytes, size_t *buf_size, void **buf);
diff --git a/test/test_plugin.sh.in b/test/test_plugin.sh.in
index a1287a5..a881198 100644
--- a/test/test_plugin.sh.in
+++ b/test/test_plugin.sh.in
@@ -13,7 +13,10 @@
 # http://hdfgroup.org/HDF5/doc/Copyright.html.  If you do not have
 # access to either file, you may request a copy from help@hdfgroup.org.
 #
-# Tests for test_error and err_compat 
+# This script file first envokes the Makefile in plugin_lib to build dynamic
+# plugin libraries.  Then it moves the libraries to some locations and points
+# HDF5_PLUGIN_PATH to these locations.  In the end, it runs plugin.c test.
+# 
 
 srcdir=@srcdir@
 TOP_BUILDDIR=@top_builddir@