[svn-r6578] Purpose:

    Code cleanup

Description:
    Added lots of comments to existing filters, so they are easier to understand
and use as examples for future filters.  Cleaned up various bits of code, etc.

Solution:

Platforms tested:
    FreeBSD 4.8 (sleipnir)
    IRIX64 6.5 (modi4) w/parallel

Misc. update:

5 files changed, 103 insertions, 68 deletions

diff --git a/src/H5Z.c b/src/H5Z.c
index 681ed04..cb96be5 100644
--- a/src/H5Z.c
+++ b/src/H5Z.c
@@ -53,9 +53,6 @@ H5Z_init_interface (void)
 {
     FUNC_ENTER_NOINIT(H5Z_init_interface);
 
-#ifdef H5_HAVE_FILTER_SZIP
-    H5Z_register (H5Z_FILTER_SZIP, "szip", H5Z_filter_szip);
-#endif /* H5_HAVE_FILTER_SZIP */
 #ifdef H5_HAVE_FILTER_DEFLATE
     H5Z_register (H5Z_FILTER_DEFLATE, "deflate", H5Z_filter_deflate);
 #endif /* H5_HAVE_FILTER_DEFLATE */
@@ -65,6 +62,9 @@ H5Z_init_interface (void)
 #ifdef H5_HAVE_FILTER_FLETCHER32
     H5Z_register (H5Z_FILTER_FLETCHER32, "fletcher32", H5Z_filter_fletcher32);
 #endif /* H5_HAVE_FILTER_FLETCHER32 */
+#ifdef H5_HAVE_FILTER_SZIP
+    H5Z_register (H5Z_FILTER_SZIP, "szip", H5Z_filter_szip);
+#endif /* H5_HAVE_FILTER_SZIP */
 
     FUNC_LEAVE_NOAPI(SUCCEED);
 }
diff --git a/src/H5Zdeflate.c b/src/H5Zdeflate.c
index d94185f..144c873 100644
--- a/src/H5Zdeflate.c
+++ b/src/H5Zdeflate.c
@@ -16,10 +16,11 @@
  * Programmer:  Robb Matzke <matzke@llnl.gov>
  *              Friday, August 27, 1999
  */
-#include "H5private.h"
-#include "H5Eprivate.h"
-#include "H5MMprivate.h"
-#include "H5Zprivate.h"
+
+#include "H5private.h"		/* Generic Functions			*/
+#include "H5Eprivate.h"		/* Error handling		  	*/
+#include "H5MMprivate.h"	/* Memory management			*/
+#include "H5Zprivate.h"		/* Data filters				*/
 
 #ifdef H5_HAVE_FILTER_DEFLATE
 
@@ -41,9 +42,8 @@ static int interface_initialize_g = 0;
  * Purpose:	Implement an I/O filter around the 'deflate' algorithm in
  *              libz
  *
- * Return:	Success:	
- *
- *		Failure:	
+ * Return:	Success: Size of buffer filtered
+ *		Failure: 0	
  *
  * Programmer:	Robb Matzke
  *              Thursday, April 16, 1998
@@ -57,10 +57,9 @@ H5Z_filter_deflate (unsigned flags, size_t cd_nelmts,
 		    const unsigned cd_values[], size_t nbytes,
 		    size_t *buf_size, void **buf)
 {
-    size_t	ret_value = 0;
-    void	*outbuf = NULL;
-    int		aggression = 6;
-    int		status;
+    void	*outbuf = NULL;         /* Pointer to new buffer */
+    int		status;                 /* Status from zlib operation */
+    size_t	ret_value;              /* Return value */
     
     FUNC_ENTER_NOAPI(H5Z_filter_deflate, 0);
 
@@ -68,68 +67,104 @@ H5Z_filter_deflate (unsigned flags, size_t cd_nelmts,
     if (cd_nelmts!=1 || cd_values[0]>9)
 	HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, 0, "invalid deflate aggression level");
 
-    aggression = cd_values[0];
     if (flags & H5Z_FLAG_REVERSE) {
 	/* Input; uncompress */
-	z_stream	z_strm;
-	size_t		nalloc = *buf_size;
+	z_stream	z_strm;                 /* zlib parameters */
+	size_t		nalloc = *buf_size;     /* Number of bytes for output (compressed) buffer */
 
+        /* Allocate space for the compressed buffer */
 	if (NULL==(outbuf = H5MM_malloc(nalloc)))
 	    HGOTO_ERROR(H5E_RESOURCE, H5E_NOSPACE, 0, "memory allocation failed for deflate uncompression");
+
+        /* Set the uncompression parameters */
 	HDmemset(&z_strm, 0, sizeof(z_strm));
 	z_strm.next_in = *buf;
         H5_ASSIGN_OVERFLOW(z_strm.avail_in,nbytes,size_t,uInt);
 	z_strm.next_out = outbuf;
         H5_ASSIGN_OVERFLOW(z_strm.avail_out,nalloc,size_t,uInt);
+
+        /* Initialize the uncompression routines */
 	if (Z_OK!=inflateInit(&z_strm))
 	    HGOTO_ERROR(H5E_PLINE, H5E_CANTINIT, 0, "inflateInit() failed");
+
+        /* Loop to uncompress the buffer */
 	while (1) {
+            /* Uncompress some data */
 	    status = inflate(&z_strm, Z_SYNC_FLUSH);
+
+            /* Check if we are done uncompressing data */
 	    if (Z_STREAM_END==status)
                 break;	/*done*/
+
+            /* Check for error */
 	    if (Z_OK!=status) {
 		inflateEnd(&z_strm);
 		HGOTO_ERROR(H5E_PLINE, H5E_CANTINIT, 0, "inflate() failed");
 	    }
+
+            /* If we're not done and just ran out of buffer space, get more */
 	    if (Z_OK==status && 0==z_strm.avail_out) {
+                /* Allocate a buffer twice as big */
 		nalloc *= 2;
 		if (NULL==(outbuf = H5MM_realloc(outbuf, nalloc))) {
 		    inflateEnd(&z_strm);
 		    HGOTO_ERROR(H5E_RESOURCE, H5E_NOSPACE, 0, "memory allocation failed for deflate uncompression");
 		}
+
+                /* Update pointers to buffer for next set of uncompressed data */
 		z_strm.next_out = (unsigned char*)outbuf + z_strm.total_out;
 		z_strm.avail_out = (uInt)(nalloc - z_strm.total_out);
 	    }
 	}
 	
+        /* Free the input buffer */
 	H5MM_xfree(*buf);
+
+        /* Set return values */
 	*buf = outbuf;
 	outbuf = NULL;
 	*buf_size = nalloc;
 	ret_value = z_strm.total_out;
+
+        /* Finish uncompressing the stream */
 	inflateEnd(&z_strm);
-    } else {
+    }
+    else {
 	/*
 	 * Output; compress but fail if the result would be larger than the
 	 * input.  The library doesn't provide in-place compression, so we
 	 * must allocate a separate buffer for the result.
 	 */
-	const Bytef	*z_src = (const Bytef*)(*buf);
-	Bytef		*z_dst;		/*destination buffer		*/
-	uLongf		z_dst_nbytes = (uLongf)H5Z_DEFLATE_SIZE_ADJUST(nbytes);
-	uLong		z_src_nbytes = (uLong)nbytes;
+	const Bytef *z_src = (const Bytef*)(*buf);
+	Bytef	    *z_dst;		/*destination buffer		*/
+	uLongf	     z_dst_nbytes = (uLongf)H5Z_DEFLATE_SIZE_ADJUST(nbytes);
+	uLong	     z_src_nbytes = (uLong)nbytes;
+        int          aggression;     /* Compression aggression setting */
     
+        /* Set the compression aggression level */
+        aggression = cd_values[0];
+
+        /* Allocate output (compressed) buffer */
 	if (NULL==(z_dst=outbuf=H5MM_malloc(z_dst_nbytes)))
 	    HGOTO_ERROR(H5E_RESOURCE, H5E_NOSPACE, 0, "unable to allocate deflate destination buffer");
+
+        /* Perform compression from the source to the destination buffer */
 	status = compress2 (z_dst, &z_dst_nbytes, z_src, z_src_nbytes, aggression);
+
+        /* Check for various zlib errors */
 	if (Z_BUF_ERROR==status) {
 	    HGOTO_ERROR(H5E_PLINE, H5E_CANTINIT, 0, "overflow");
 	} else if (Z_MEM_ERROR==status) {
 	    HGOTO_ERROR (H5E_PLINE, H5E_CANTINIT, 0, "deflate memory error");
 	} else if (Z_OK!=status) {
 	    HGOTO_ERROR (H5E_PLINE, H5E_CANTINIT, 0, "other deflate error");
-	} else {
+	}
+        /* Successfully uncompressed the buffer */
+        else {
+            /* Free the input buffer */
 	    H5MM_xfree(*buf);
+
+            /* Set return values */
 	    *buf = outbuf;
 	    outbuf = NULL;
 	    *buf_size = nbytes;
@@ -142,5 +177,5 @@ done:
         H5MM_xfree(outbuf);
     FUNC_LEAVE_NOAPI(ret_value);
 }
-
 #endif /* H5_HAVE_FILTER_DEFLATE */
+
diff --git a/src/H5Zfletcher32.c b/src/H5Zfletcher32.c
index b3d82df..62fbfa5 100644
--- a/src/H5Zfletcher32.c
+++ b/src/H5Zfletcher32.c
@@ -16,10 +16,11 @@
  * Programmer:  Raymond Lu<slu@ncsa.uiuc.edu>
  *              Jan 3, 2003
  */
-#include "H5private.h"
-#include "H5Eprivate.h"
-#include "H5MMprivate.h"
-#include "H5Zprivate.h"
+
+#include "H5private.h"		/* Generic Functions			*/
+#include "H5Eprivate.h"		/* Error handling		  	*/
+#include "H5MMprivate.h"	/* Memory management			*/
+#include "H5Zprivate.h"		/* Data filters				*/
 
 #ifdef H5_HAVE_FILTER_FLETCHER32
 
@@ -47,12 +48,10 @@ static int interface_initialize_g = 0;
  *
  *-------------------------------------------------------------------------
  */
-static unsigned int H5Z_filter_fletcher32_compute(unsigned short *buf, size_t len)
+static uint32_t H5Z_filter_fletcher32_compute(unsigned short *src, size_t len)
 {
-    size_t         count = len;
-    register unsigned int s1 = 0;
-    register unsigned int s2 = 0;
-    unsigned short *src = buf;
+    size_t count = len;         /* Number of bytes left to checksum */
+    uint32_t s1 = 0, s2 = 0;    /* Temporary partial checksums */
 
     FUNC_ENTER_NOINIT(H5Z_filter_fletcher32_compute);
 
@@ -93,8 +92,7 @@ static unsigned int H5Z_filter_fletcher32_compute(unsigned short *buf, size_t le
  *
  * Purpose:	Implement an I/O filter of Fletcher32 Checksum
  *
- * Return:	Success: size of data plus the size of Fletcher32 value	
- *
+ * Return:	Success: Size of buffer filtered
  *		Failure: 0	
  *
  * Programmer:	Raymond Lu
@@ -108,42 +106,43 @@ size_t
 H5Z_filter_fletcher32 (unsigned flags, size_t UNUSED cd_nelmts, const unsigned UNUSED cd_values[], 
                      size_t nbytes, size_t *buf_size, void **buf)
 {
-    size_t	ret_value = 0;
-    void	*outbuf = NULL;
-    
+    void    *outbuf = NULL;     /* Pointer to new buffer */
     unsigned char *src = (unsigned char*)(*buf);
-    unsigned int fletcher = 0;
+    uint32_t fletcher;          /* Checksum value */
+    size_t   ret_value;         /* Return value */
     
     FUNC_ENTER_NOAPI(H5Z_filter_fletcher32, 0);
 
-    assert(sizeof(unsigned int)==4);
+    assert(sizeof(uint32_t)==4);
    
     if (flags & H5Z_FLAG_REVERSE) { /* Read */
-        size_t  src_nbytes = nbytes;
-        unsigned int origin_fletcher;
-
         /* Do checksum if it's enabled for read; otherwise skip it
          * to save performance. */
-        if (!(flags & H5Z_FLAG_SKIP_EDC)) { /* Read */
-            unsigned char *tmp_src;
+        if (!(flags & H5Z_FLAG_SKIP_EDC)) {
+            unsigned char *tmp_src;             /* Pointer to checksum in buffer */
+            size_t  src_nbytes = nbytes;        /* Original number of bytes */
+            uint32_t stored_fletcher;           /* Stored checksum value */
 
+            /* Get the stored checksum */
             src_nbytes -= FLETCHER_LEN;
             tmp_src=src+src_nbytes;
-            UINT32DECODE(tmp_src, origin_fletcher);
+            UINT32DECODE(tmp_src, stored_fletcher);
 
-            /* Compute checksum */
+            /* Compute checksum (can't fail) */
             fletcher = H5Z_filter_fletcher32_compute((unsigned short*)src,src_nbytes);
 
-            if(origin_fletcher != fletcher)
+            /* Verify computed checksum matches stored checksum */
+            if(stored_fletcher != fletcher)
 	        HGOTO_ERROR(H5E_STORAGE, H5E_READERROR, 0, "data error detected by Fletcher32 checksum");
         }
         
-        *buf_size = nbytes - FLETCHER_LEN;
-        ret_value = *buf_size;
+        /* Set return values */
+        /* (Re-use the input buffer, just note that the size is smaller by the size of the checksum) */
+        ret_value = nbytes-FLETCHER_LEN;
     } else { /* Write */
-        unsigned char *dst;
+        unsigned char *dst;     /* Temporary pointer to destination buffer */
 
-        /* Compute checksum */
+        /* Compute checksum (can't fail) */
         fletcher = H5Z_filter_fletcher32_compute((unsigned short*)src,nbytes);
         
 	if (NULL==(dst=outbuf=H5MM_malloc(nbytes+FLETCHER_LEN)))
@@ -152,12 +151,15 @@ H5Z_filter_fletcher32 (unsigned flags, size_t UNUSED cd_nelmts, const unsigned U
         /* Copy raw data */
         HDmemcpy((void*)dst, (void*)(*buf), nbytes);
 
-        /* Append checksum to raw data */
+        /* Append checksum to raw data for storage */
         dst += nbytes;
         UINT32ENCODE(dst, fletcher);
 
-        *buf_size = nbytes + FLETCHER_LEN;
+        /* Free input buffer */
  	H5MM_xfree(*buf);
+
+        /* Set return values */
+        *buf_size = nbytes + FLETCHER_LEN;
 	*buf = outbuf;
 	outbuf = NULL;
 	ret_value = *buf_size;           
@@ -168,5 +170,5 @@ done:
         H5MM_xfree(outbuf);
     FUNC_LEAVE_NOAPI(ret_value);
 }
-
 #endif /* H5_HAVE_FILTER_FLETCHER32 */
+
diff --git a/src/H5Zshuffle.c b/src/H5Zshuffle.c
index 864875c..bcadbc4 100644
--- a/src/H5Zshuffle.c
+++ b/src/H5Zshuffle.c
@@ -12,14 +12,10 @@
  * access to either file, you may request a copy from hdfhelp@ncsa.uiuc.edu. *
  * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
 
-/*
- * Programmer:  Robb Matzke <matzke@llnl.gov>
- *              Friday, August 27, 1999
- */
-#include "H5private.h"
-#include "H5Eprivate.h"
-#include "H5MMprivate.h"
-#include "H5Zprivate.h"
+#include "H5private.h"		/* Generic Functions			*/
+#include "H5Eprivate.h"		/* Error handling		  	*/
+#include "H5MMprivate.h"	/* Memory management			*/
+#include "H5Zprivate.h"		/* Data filters				*/
 
 #ifdef H5_HAVE_FILTER_SHUFFLE
 
@@ -39,9 +35,8 @@ static int interface_initialize_g = 0;
  *              Usually, the bytes in each byte position are more related to
  *              each other and putting them together will increase compression.
  *
- * Return:	Success:	
- *
- *		Failure:	
+ * Return:	Success: Size of buffer filtered
+ *		Failure: 0	
  *
  * Programmer:	Kent Yang
  *              Wednesday, November 13, 2002
@@ -127,8 +122,10 @@ H5Z_filter_shuffle(unsigned flags, size_t cd_nelmts, const unsigned cd_values[],
             }
         } /* end else */
 
-        /* Set the buffer information to return */
+        /* Free the input buffer */
         H5MM_xfree(*buf);
+
+        /* Set the buffer information to return */
         *buf = dest;
         *buf_size=nbytes;
     } /* end else */
@@ -140,3 +137,4 @@ done:
     FUNC_LEAVE_NOAPI(ret_value);
 }
 #endif /*H5_HAVE_FILTER_SHUFFLE */
+
diff --git a/src/Makefile.in b/src/Makefile.in
index b108e47..3f82d8e 100644
--- a/src/Makefile.in
+++ b/src/Makefile.in
@@ -42,7 +42,7 @@ LIB_SRC=H5.c H5A.c H5AC.c H5B.c H5D.c H5E.c H5F.c H5Farray.c H5Fcontig.c      \
         H5Tcompound.c H5Tconv.c H5Tcset.c H5Tenum.c H5Tfields.c H5Tfixed.c    \
         H5Tfloat.c H5Tinit.c H5Tnative.c H5Toffset.c H5Topaque.c H5Torder.c   \
         H5Tpad.c H5Tprecis.c H5Tstrpad.c H5Tvlen.c H5TB.c H5TS.c H5V.c H5Z.c  \
-        H5Zdeflate.c H5Zszip.c H5Zshuffle.c H5Zfletcher32.c
+        H5Zdeflate.c H5Zshuffle.c H5Zszip.c H5Zfletcher32.c
 
 LIB_OBJ=$(LIB_SRC:.c=.lo)