[svn-r8541] Purpose:

    Add more C++ wrappers and documentation - incrementally check-in

Description:
    Added wrappers for:
        H5garbage_collect
        H5set_free_list_limits
    to H5Library.*

Platforms:
    SunOS 5.7 (arabica)
    Linux 2.4 (eirene)
    Windows 2000

Misc. update:

2 files changed, 106 insertions, 8 deletions

diff --git a/c++/src/H5Library.cpp b/c++/src/H5Library.cpp
index b0afb44..a449dc2 100644
--- a/c++/src/H5Library.cpp
+++ b/c++/src/H5Library.cpp
@@ -25,7 +25,12 @@ namespace H5 {
 // This static variable will be set to true when dontAtExit is called
 bool H5Library::need_cleanup = false;
 
-// Initializes the HDF5 library. 
+//--------------------------------------------------------------------------
+// Function:	H5Library::open
+///\brief	Initializes the HDF5 library. 
+///\exception	H5::LibraryIException
+// Programmer	Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
 void H5Library::open()
 {
    herr_t ret_value = H5open();
@@ -35,7 +40,12 @@ void H5Library::open()
    }
 }
 
-// Flushes all data to disk, closes files, and cleans up memory. 
+//--------------------------------------------------------------------------
+// Function:	H5Library::close
+///\brief	Flushes all data to disk, closes files, and cleans up memory. 
+///\exception	H5::LibraryIException
+// Programmer	Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
 void H5Library::close()
 {
    herr_t ret_value = H5close();
@@ -45,7 +55,12 @@ void H5Library::close()
    }
 }
 
-// Instructs library not to install atexit cleanup routine
+//--------------------------------------------------------------------------
+// Function:	H5Library::dontAtExit
+///\brief	Instructs library not to install atexit cleanup routine
+///\exception	H5::LibraryIException
+// Programmer	Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
 void H5Library::dontAtExit()
 {
    herr_t ret_value = H5dont_atexit();
@@ -55,7 +70,15 @@ void H5Library::dontAtExit()
    }
 }
 
-// Returns the HDF library release number. 
+//--------------------------------------------------------------------------
+// Function:	H5Library::getLibVersion
+///\brief	Returns the HDF library release number. 
+///\param	majnum - OUT: Major version of the library
+///\param	minnum - OUT: Minor version of the library
+///\param	relnum - OUT: Release number of the library
+///\exception	H5::LibraryIException
+// Programmer	Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
 void H5Library::getLibVersion( unsigned& majnum, unsigned& minnum, unsigned& relnum )
 {
    herr_t ret_value = H5get_libversion( &majnum, &minnum, &relnum );
@@ -65,17 +88,84 @@ void H5Library::getLibVersion( unsigned& majnum, unsigned& minnum, unsigned& rel
    }
 }
 
-// Verifies that the arguments match the version numbers compiled
-// into the library
-void H5Library::checkVersion( unsigned majnum, unsigned minnum, unsigned relnum )
+//--------------------------------------------------------------------------
+// Function:	H5Library::checkVersion
+///\brief	Verifies that the arguments match the version numbers 
+///		compiled into the library
+///\param	majnum - OUT: Major version of the library
+///\param	minnum - OUT: Minor version of the library
+///\param	relnum - OUT: Release number of the library
+///\exception	H5::LibraryIException
+///\par Description
+///		For information about library version, please refer to
+///		the C layer Reference Manual at:
+/// http://hdf.ncsa.uiuc.edu/HDF5/doc/RM_H5.html#Library-VersCheck
+// Programmer	Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
+void H5Library::checkVersion(unsigned majnum, unsigned minnum, unsigned relnum)
 {
-   herr_t ret_value = H5check_version( majnum, minnum, relnum  );
+   herr_t ret_value = H5check_version(majnum, minnum, relnum);
    if( ret_value < 0 )
    {
       throw LibraryIException("H5Library::checkVersion", "H5check_version failed");
    }
 }
 
+//--------------------------------------------------------------------------
+// Function:	H5Library::garbageCollect
+///\brief	Walks through all the garbage collection routines for the
+///		library, which are supposed to free any unused memory they 
+///		have allocated.
+///\exception	H5::LibraryIException
+///\par Description
+///		It is not required that H5Library::garbageCollect be called 
+///		at any particular time; it is only necessary in certain 
+///		situations, such as when the application has performed actions 
+///		that cause the library to allocate many objects. The 
+///		application should call H5Library::garbageCollect if it 
+///		eventually releases those objects and wants to reduce the 
+///		memory used by the library from the peak usage required. 
+///\par
+///		The library automatically garbage collects all the free 
+///		lists when the application ends. 
+// Programmer	Binh-Minh Ribler - May, 2004
+//--------------------------------------------------------------------------
+void H5Library::garbageCollect()
+{
+   herr_t ret_value = H5garbage_collect();
+   if( ret_value < 0 )
+   {
+      throw LibraryIException("H5Library::garbageCollect", "H5garbage_collect failed");
+   }
+}
+
+//--------------------------------------------------------------------------
+// Function:	H5Library::setFreeListLimits
+///\brief	Sets limits on the different kinds of free lists.
+///\param	reg_global_lim - IN: Limit on all "regular" free list memory used
+///\param	reg_list_lim   - IN: Limit on memory used in each "regular" free list
+///\param	arr_global_lim - IN: Limit on all "array" free list memory used
+///\param	arr_list_lim   - IN: Limit on memory used in each "array" free list
+///\param	blk_global_lim - IN: Limit on all "block" free list memory used
+///\param	blk_list_lim   - IN: Limit on memory used in each "block" free list
+///\exception	H5::LibraryIException
+///\par Description
+///		Setting a value of -1 for a limit means no limit of that type.
+///		For more information on free list limits, please refer to C 
+///		layer Reference Manual at:
+/// http://hdf.ncsa.uiuc.edu/HDF5/doc/RM_H5.html#Library-SetFreeListLimits
+// Programmer	Binh-Minh Ribler - May, 2004
+//--------------------------------------------------------------------------
+void H5Library::setFreeListLimits(int reg_global_lim, int reg_list_lim, 
+	int arr_global_lim, int arr_list_lim, int blk_global_lim, 
+	int blk_list_lim)
+{
+   herr_t ret_value = H5set_free_list_limits(reg_global_lim, reg_list_lim, arr_global_lim, arr_list_lim, blk_global_lim, blk_list_lim);
+   if( ret_value < 0 )
+   {
+      throw LibraryIException("H5Library::setFreeListLimits", "H5set_free_list_limits failed");
+   }
+}
 #ifndef H5_NO_NAMESPACE
 } // end namespace
 #endif
diff --git a/c++/src/H5Library.h b/c++/src/H5Library.h
index 3e5b295..34b816b 100644
--- a/c++/src/H5Library.h
+++ b/c++/src/H5Library.h
@@ -46,6 +46,14 @@ class H5_DLLCPP H5Library {
 	// into the library
 	static void checkVersion( unsigned majnum, unsigned minnum, unsigned relnum ); 
 
+	// Walks through all the garbage collection routines for the library, 
+	// which are supposed to free any unused memory they have allocated.
+	static void garbageCollect();
+
+	// Sets limits on the different kinds of free lists.
+	static void setFreeListLimits(int reg_global_lim, int reg_list_lim, int
+	arr_global_lim, int arr_list_lim, int blk_global_lim, int blk_list_lim);
+		
    private:
 	// Default constructor - no instance ever created
 	H5Library() {};