From e38365206ae36d83b8e573eb0b2e51e555699c97 Mon Sep 17 00:00:00 2001 From: Frank Baker Date: Thu, 23 Jun 2005 16:30:36 -0500 Subject: [svn-r10976] Purpose: Added new meta data cache functions. Added links to HDF5 High-Level API reference pages to nav bar. Other minor (though somewhat pervasive) reformatting. Platforms tested: Firefox --- doc/html/RM_H5F.html | 829 +++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 701 insertions(+), 128 deletions(-) diff --git a/doc/html/RM_H5F.html b/doc/html/RM_H5F.html index b77873d..b3cbb33 100644 --- a/doc/html/RM_H5F.html +++ b/doc/html/RM_H5F.html @@ -43,6 +43,11 @@ HDF5/H5F API Specification And in this document, the HDF5 Reference Manual  
+H5IM   +H5LT   +H5PT   +H5TB   +
H5   H5A   H5D   @@ -82,23 +87,28 @@ documented below.
  • H5Freopen
  • H5Fclose
  • H5Fflush +
  • H5Fis_hdf5 +
  • H5Fmount        -       - +       + @@ -109,38 +119,43 @@ documented below.
    -        -        -
    @@ -160,10 +175,10 @@ as the corresponding C function.
  • h5freopen_f
  • h5fclose_f
  • h5fflush_f +
  • h5fis_hdf5_f        @@ -234,25 +254,25 @@ as the corresponding C function.
    Parameters:
      - - + +
      hid_t file_id    IN: Identifier of a file to terminate access to.
      hid_t file_id    IN: Identifier of a file to terminate access to.
    Returns:
    Returns a non-negative value if successful; otherwise returns a negative value.
    Fortran90 Interface: h5fclose_f
    - 
    +    
     SUBROUTINE h5fclose_f(file_id, hdferr) 
   IMPLICIT NONE
   INTEGER(HID_T), INTENT(IN) :: file_id ! File identifier
   INTEGER, INTENT(OUT) :: hdferr        ! Error code
                                         ! 0 on success and -1 on failure
 END SUBROUTINE h5fclose_f 
-	
    		
-		
-		
 
 
+
+
+
    
+
    
+
    Name: H5Fget_mdc_config
+
    Signature:
+    
    herr_t H5Fget_mdc_config(hid_t 
+      file_id, H5AC_cache_config_t *config_ptr)
+
    Purpose:
+    
    Obtain current metadata cache configuration for target file.
+
    Description:
+    
    H5Fget_mdc_config loads the current metadata cache 
+      configuration into the instance of H5AC_cache_config_t 
+      pointed to by the config_ptr parameter.
+
+    
    Note that the version field of *config_ptr must 
+      be initialized --this allows the library to support old versions 
+      of the H5AC_cache_config_t structure.
+
+    
    See the overview of the metadata cache in the special topics section 
+      of the user manual for details on metadata cache configuration. 
+      If you haven't read and understood that documentation, the results 
+      of this call will not make much sense.
+
    Parameters:
+    
      
+        
+            
+            
+        
+            
+            
+        
+          
+        
+        
+          
+        
+        
+            
+            
+        
+            
+            
+        
+            
+            
+        
+            
+            
+        
+            
+            
+        
+            
+            
+        
+            
+            
+        
+            
+            
+        
+          
+        
+        
+          
+        
+        
+            
+            
+        
+            
+            
+        
+            
+            
+        
+            
+            
+        
+            
+            
+        
+          
+        
+        
+          
+        
+        
+            
+            
+        
+            
+            
+        
+            
+            
+        
+            
+            
+        
+            
+            
+        
+            
+            
+        
+            
+            
+        
+            
+            
+
+    
      hid_t file_id    IN: Identifier of the target file
      H5AC_cache_config_t *config_ptr    IN/OUT: Pointer to the instance of H5AC_cache_config_t 
+              in which the current metadata cache configuration is to be reported. 
+              The fields of this structure are discussed below:
       
      General configuration section:
      int version    IN: Integer field indicating the the version 
+              of the H5AC_cache_config_t in use.  This field should be 
+              set to H5AC__CURR_CACHE_CONFIG_VERSION 
+              (defined in H5ACpublic.h).
      hbool_t rpt_fcn_enabled    OUT: Boolean flag indicating whether the adaptive 
+              cache resize report function is enabled.  This field should almost 
+              always be set to FALSE. Since resize algorithm activity is reported 
+              via stdout, it MUST be set to FALSE on Windows machines.
+              
      The report function is not supported code, and can be 
+              expected to change between versions of the library.  
+              Use it at your own risk.
      hbool_t set_initial_size    OUT: Boolean flag indicating whether the cache 
+              should be created with a user specified initial maximum size.
+              
      If the configuration is loaded from the cache, 
+              this flag will always be FALSE.
      size_t initial_size    OUT: Initial maximum size of the cache in bytes, 
+              if applicable.
+              
      If the configuration is loaded from the cache, this 
+              field will contain the cache maximum size as of the 
+              time of the call.
      double min_clean_fraction    OUT: This field is only used in the parallel 
+              version of the library. It specifies the minimum fraction
+              of the cache that must be kept either clean or 
+              empty when possible.
      size_t max_size    OUT: Upper bound (in bytes) on the range of 
+              values that the adaptive cache resize code can select as 
+              the maximum cache size.
      size_t min_size    OUT: Lower bound (in bytes) on the range 
+              of values that the adaptive cache resize code can 
+              select as the maximum cache size.
      long int epoch_length    OUT: Number of cache accesses between runs 
+              of the adaptive cache resize code.
       
      Increment configuration section:
      enum H5C_cache_incr_mode incr_mode    OUT: Enumerated value indicating the operational 
+              mode of the automatic cache size increase code.  At present,
+              only the following values are legal:
+              
      H5C_incr__off: Automatic cache size increase is disabled.
+              
      H5C_incr__threshold: Automatic cache size increase is 
+              enabled using the hit rate threshold algorithm.
      double lower_hr_threshold    OUT: Hit rate threshold used in the hit rate 
+              threshold cache size increase algorithm.
      double increment    OUT: The factor by which the current maximum 
+              cache size is multiplied to obtain an initial new maximum cache
+              size if a size increase is triggered in the hit rate 
+              threshold cache size increase algorithm.
      hbool_t apply_max_increment    OUT: Boolean flag indicating whether an upper 
+              limit will be applied to the size of cache size increases.
      size_t max_increment    OUT: The maximum number of bytes by which the 
+              maximum cache size can be increased in a single step -- if
+              applicable.
       
      Decrement configuration section:
      enum H5C_cache_decr_mode decr_mode    OUT: Enumerated value indicating the operational 
+              mode of the automatic cache size decrease code.  At present,
+              the following values are legal:
+              
      H5C_decr__off:  Automatic cache size decrease is disabled, 
+              and the remaining decrement fields are ignored.
+              
      H5C_decr__threshold:  Automatic cache size decrease is 
+              enabled using the hit rate threshold algorithm.
+              
      H5C_decr__age_out:  Automatic cache size decrease is enabled 
+              using the ageout algorithm.
+              
      H5C_decr__age_out_with_threshold: Automatic cache size 
+              decrease is enabled using the ageout with hit rate 
+              threshold algorithm
      double upper_hr_threshold    OUT: Upper hit rate threshold. This value is only 
+              used if the decr_mode is either H5C_decr__threshold or 
+              H5C_decr__age_out_with_threshold.
      double decrement    OUT: Factor by which the current max cache size 
+              is multiplied to obtain an initial value for the new cache 
+              size when cache size reduction is triggered in the hit rate 
+              threshold cache size reduction algorithm.
      hbool_t apply_max_decrement    OUT: Boolean flag indicating whether an upper 
+              limit should be applied to the size of cache size 
+              decreases.
      size_t max_decrement    OUT: The maximum number of bytes by which cache 
+              size can be decreased if any single step, if applicable.
      int epochs_before_eviction    OUT: The minimum number of epochs that an entry 
+              must reside unaccessed in cache before being evicted under 
+              either of the ageout cache size reduction algorithms.
      hbool_t apply_empty_reserve    OUT: Boolean flag indicating whether an empty 
+              reserve should be maintained under either of the ageout 
+              cache size reduction algorithms.
      double empty_reserve    OUT: Empty reserve for use with the ageout 
+              cache size reduction algorithms, if applicable.
    
+
    Returns:
+  
    Returns a non-negative value if successful; otherwise returns a negative value.
+
+
    
+
+
+
+
    
+
    
+
    Name: H5Fget_mdc_hit_rate
+
    Signature:
+    
    herr_t H5Fget_mdc_hit_rate(hid_t 
+      file_id, double *hit_rate_ptr)
+
    Purpose:
+    
    Obtain target file's metadata cache hit rate.
+
    Description:
+    
    H5Fget_mdc_hit_rate queries the metadata cache of the target 
+      file to obtain its hit rate (cache hits / (cache hits + cache misses)) 
+      since the last time hit rate statistics were reset.  If the cache has 
+      not been accessed since the last time the hit rate stats were reset, 
+      the hit rate is defined to be 0.0.
+      
    The hit rate stats can be reset either manually (via 
+      H5Freset_mdc_hit_rate_stats()), or automatically.  If the cache's 
+      adaptive resize code is enabled, the hit rate stats will be reset 
+      once per epoch.  If they are reset manually as well, 
+      the cache may behave oddly.
+      
    See the overview of the metadata cache in the special 
+      topics section of the user manual for details on the metadata 
+      cache and its adaptive resize algorithms.
+
    Parameters:
+    
      
+        
+            
+            
+        
+            
+            
+    
      hid_t file_id
+                  IN: Identifier of the target file.
      double * hit_rate_ptr
+                  OUT: Pointer to the double in which the 
+              hit rate is returned.  Note that *hit_rate_ptr is 
+              undefined if the API call fails.
    
+
    Returns:
+    
    Returns a non-negative value if successful; otherwise 
+      returns a negative value.
+
+
    
+
+
+
+
    
+
    
+
    Name: H5Fget_mdc_size
+
    Signature:
+    
    herr_t H5Fget_mdc_size(hid_t file_id,
+                               size_t *max_size_ptr,
+                               size_t *min_clean_size_ptr,
+                               size_t *cur_size_ptr,
+                               int *cur_num_entries_ptr)
+
    Purpose:
+    
    Obtain current metadata cache size data for specified file.
+
    Description:
+    
    H5Fget_mdc_size queries the metadata cache of the target file 
+      for the desired size information, and returns this information in 
+      the locations indicated by the pointer parameters.  If any pointer 
+      parameter is NULL, the associated data is not returned.
+      
    If the API call fails, the values returned via the pointer 
+      parameters are undefined.
+      
    If adaptive cache resizing is enabled, the cache maximum size 
+      and minimum clean size may change at the end of each epoch. Current 
+      size and current number of entries can change on each cache access.
+      
    Current size can exceed maximum size under certain conditions. 
+      See the overview of the metadata cache in the special topics 
+      section of the user manual for a discussion of this.
+
    Parameters:
+    
      
+        
+            
+            
+        
+            
+            
+        
+            
+            
+        
+            
+            
+        
+            
+            
+    
      hid_t file_id
+                  IN: Identifier of the target file.
      size_t *max_size_ptr
+                  OUT: Pointer to the location in which the 
+              current cache maximum size is to be returned, or NULL if 
+              this datum is not desired.
      size_t *min_clean_size_ptr
+                  OUT: Pointer to the location in which the 
+              current cache minimum clean size is to be returned, or 
+              NULL if that datum is not desired.
      size_t *cur_size_ptr
+                  OUT: Pointer to the location in which the 
+              current cache size is to be returned, or NULL if that 
+              datum is not desired.
      int *cur_num_entries_ptr
+                  OUT: Pointer to the location in which the 
+              current number of entries in the cache is to be returned, 
+              or NULL if that datum is not desired.
    
+
    Returns:
+    
    Returns a non-negative value if successful; otherwise returns a
+        negative value.
+
+
    
 
 
 
@@ -735,7 +1041,7 @@ END SUBROUTINE h5fget_freespace_f
         otherwise returns a negative value.
 
    Fortran90 Interface: h5fget_name_f
     
    
-	
    +    
     SUBROUTINE h5fget_name_f(obj_id, buf, size, hdferr)
 
   IMPLICIT NONE
@@ -745,9 +1051,9 @@ SUBROUTINE h5fget_name_f(obj_id, buf, size, hdferr)
   INTEGER, INTENT(OUT) :: hdferr           ! Error code: 0 on success,
                                            ! -1 if fail
 END SUBROUTINE h5fget_name_f
-	
    		
-		
-				
-		
-		
+
+        
         
-		    hid_t access_id    
+            hid_t access_id    
             IN: Identifier for the file access properties list.
                 If parallel file access is desired, this is a collective
                 call according to the communicator stored in the
@@ -1205,7 +1511,7 @@ END SUBROUTINE h5fmount_f
         otherwise returns a negative value.
 
    Fortran90 Interface: h5fopen_f
     
    
-	
    +    
     SUBROUTINE h5fopen_f(name, access_flags, file_id, hdferr, &  
                      access_prp)
   IMPLICIT NONE 
@@ -1221,10 +1527,10 @@ SUBROUTINE h5fopen_f(name, access_flags, file_id, hdferr, &
                                          ! File access property list 
                                          ! identifier  
 END SUBROUTINE h5fopen_f
-	
    		
-		
-		
+
+
    
+
    
+
    Name: H5Freset_mdc_hit_rate_stats
+
    Signature:
+    
    herr_t H5Freset_mdc_hit_rate_stats(hid_t 
+      file_id)
+
    Purpose:
+    
    Reset hit rate statistics counters for the target file.
+
    Description:
+    
    H5Freset_mdc_hit_rate_stats resets the hit rate statistics 
+      counters in the metadata cache associated with the specified 
+      file. 
+      
    If the adaptive cache resizing code is enabled, the hit 
+      rate statistics are reset at the beginning of each epoch.  
+      This API call allows you to do the same thing from your program. 
+      
    The adaptive cache resizing code may behave oddly if you use 
+      this call when adaptive cache resizing is enabled.  However, 
+      the call should be useful if you choose to control metadata 
+      cache size from your program. 
+      
    See the overview of the metadata cache in the special topics 
+      section of the user manual for details of the metadata cache and 
+      the adaptive cache resizing algorithms.  If you haven't read, 
+      understood, and thought about the material covered in that 
+      documentation, you shouldn't be using this API call.
+
    Parameters:
+    
      
+        
+            
+            
+    
      hid_t file_id    IN: Identifier of the target file.
    
+
    Returns:
+    
    Returns a non-negative value if successful; otherwise returns a 
+      negative value.
+
+
    
+
+
+
+
    
+
    
+
    Name: H5Fset_mdc_config
+
    Signature:
+    
    herr_t H5Fset_mdc_config(hid_t 
+      file_id, H5AC_cache_config_t *config_ptr)
+
    Purpose:
+    
    Attempt to configure metadata cache of target file.
+
    Description:
+    
    H5Fset_mdc_config attempts to configure the file's metadata cache 
+      according configuration supplied in *config_ptr. 
+      
    See the overview of the metadata cache in the special topics 
+      section of the user manual for details on what is being configured.  
+      If you haven't read and understood that documentation, you really 
+      shouldn't be using this API call.
+
    Parameters:
+    
      
+        
+            
+            
+        
+            
+            
+        
+          
+        
+        
+          
+        
+        
+            
+            
+        
+            
+            
+        
+            
+            
+        
+            
+            
+        
+            
+            
+        
+            
+            
+        
+            
+            
+        
+            
+            
+        
+          
+        
+        
+          
+        
+        
+            
+            
+        
+            
+            
+        
+            
+            
+        
+            
+            
+        
+            
+            
+        
+          
+        
+        
+          
+        
+        
+            
+            
+        
+            
+            
+        
+            
+            
+        
+            
+            
+        
+            
+            
+        
+            
+            
+        
+            
+            
+        
+            
+            
+    
      hid_t file_id
+                  IN: Identifier of the target file
      H5AC_cache_config_t *config_ptr
+                  IN: Pointer to the instance of H5AC_cache_config_t 
+              containing the desired configuration.  The fields of this structure 
+              are discussed below:
       
      General configuration section:
      int version
+                  IN: Integer field indicating the the version of 
+              the H5AC_cache_config_t in use.  This field should be set to 
+              H5AC__CURR_CACHE_CONFIG_VERSION (defined in H5ACpublic.h).
      hbool_t rpt_fcn_enabled
+                  IN: Boolean flag indicating whether the adaptive 
+              cache resize report function is enabled.  This field should almost 
+              always be set to FALSE. Since resize algorithm activity is reported 
+              via stdout, it MUST be set to FALSE on Windows machines.
+              
      The report function is not supported code, and can be expected to 
+              change between versions of the library.  Use it at your own risk.
      hbool_t set_initial_size
+                  IN: Boolean flag indicating whether the cache should be 
+              forced to the user specified initial size.
      size_t initial_size
+                  IN: If set_initial_size is TRUE, initial_size must 
+              contains the desired initial size in bytes.  This value must lie 
+              in the closed interval [min_size, max_size]. (see below)
      double min_clean_fraction
+                  IN: This field is only used in the parallel version 
+              of the library. It specifies the minimum fraction of the cache that 
+              must be kept either clean or empty.
+              
      The value must lie in the interval [0.0, 1.0].  0.25 is a good place 
+              to start.
      size_t max_size
+                  IN: Upper bound (in bytes) on the range of values 
+              that the adaptive cache resize code can select as the maximum 
+              cache size.
      size_t min_size
+                  IN: Lower bound (in bytes) on the range of values 
+              that the adaptive cache resize code can select as the maximum 
+              cache size.
      long int epoch_length
+                  IN: Number of cache accesses between runs of the 
+              adaptive cache resize code. 50,000 is a good starting number.
       
      Increment configuration section:
      enum H5C_cache_incr_mode incr_mode
+                  IN: Enumerated value indicating the operational mode 
+              of the automatic cache size increase code.  At present, only two 
+              values are legal:
+              
      H5C_incr__off:  Automatic cache size increase is disabled, 
+              and the remaining increment fields are ignored.
+              
      H5C_incr__threshold:  Automatic cache size increase is enabled 
+              using the hit rate threshold algorithm.
      double lower_hr_threshold
+                  IN: Hit rate threshold used by the hit rate threshold 
+              cache size increment algorithm.
+              
      When the hit rate over an epoch is below this threshold and the 
+              cache is full, the maximum size of the cache is multiplied by 
+              increment (below), and then clipped as necessary to stay within 
+              max_size, and possibly max_increment.
+              
      This field must lie in the interval [0.0, 1.0].  0.8 or 0.9 
+              is a good starting point.
      double increment
+                  IN: Factor by which the hit rate threshold cache 
+              size increment algorithm multiplies the current cache max size 
+              to obtain a tentative new cache size.
+              
      The actual cache size increase will be clipped to satisfy the 
+              max_size specified in the general configuration, and possibly 
+              max_increment below.
+              
      The parameter must be greater than or equal to 1.0 -- 2.0 
+              is a reasonable value.
+              
      If you set it to 1.0, you will effectively disable cache size 
+              increases.
      hbool_t apply_max_increment
+                  IN: Boolean flag indicating whether an upper limit 
+              should be applied to the size of cache size increases.
      size_t max_increment
+                  IN: Maximum number of bytes by which cache size can 
+              be increased in a single step -- if applicable.
       
      Decrement configuration section:
      enum H5C_cache_decr_mode decr_mode
+                  IN: Enumerated value indicating the operational 
+              mode of the automatic cache size decrease code.  At present,
+              the following values are legal:
+              
      H5C_decr__off:  Automatic cache size decrease is disabled.
+              
      H5C_decr__threshold:  Automatic cache size decrease is 
+              enabled using the hit rate threshold algorithm.
+              
      H5C_decr__age_out:  Automatic cache size decrease is enabled 
+              using the ageout algorithm.
+              
      H5C_decr__age_out_with_threshold:  Automatic cache size 
+              decrease is enabled using the ageout with hit rate threshold 
+              algorithm
      double upper_hr_threshold
+                  IN: Hit rate threshold for the hit rate threshold and 
+              ageout with hit rate threshold cache size decrement algorithms.
+              
      When decr_mode is H5C_decr__threshold, and the hit rate over a 
+              given epoch exceeds the supplied threshold, the current maximum 
+              cache size is multiplied by decrement to obtain a tentative new
+              (and smaller) maximum cache size.
+              
      When decr_mode is H5C_decr__age_out_with_threshold, there is no 
+              attempt to find and evict aged out entries unless the hit rate in 
+              the previous epoch exceeded the supplied threshold.
+              
      This field must lie in the interval [0.0, 1.0].
+              
      For H5C_incr__threshold, .9995 or .99995 is a good place to start.
+              
      For H5C_decr__age_out_with_threshold, .999 might be 
+              more useful.
      double decrement
+                  IN: In the hit rate threshold cache size decrease 
+              algorithm, this parameter contains the factor by which the
+              current max cache size is multiplied to produce a tentative 
+              new cache size.
+              
      The actual cache size decrease will be clipped to satisfy the 
+              min_size specified in the general configuration, and possibly 
+              max_decrement below.
+              
      The parameter must be be in the interval [0.0, 1.0].
+              
      If you set it to 1.0, you will effectively disable cache size
+              decreases.  0.9 is a reasonable starting point.
      hbool_t apply_max_decrement
+                  IN: Boolean flag indicating whether an upper limit 
+              should be applied to the size of cache size decreases.
      size_t max_decrement
+                  IN: Maximum number of bytes by which the maximum cache 
+              size can be decreased in any single step -- if applicable.
      int epochs_before_eviction
+                  IN: In the ageout based cache size reduction algorithms, 
+              this field contains the minimum number of epochs an entry must remain 
+              unaccessed in cache before the cache size reduction algorithm tries to 
+              evict it. 3 is a reasonable value.
      hbool_t apply_empty_reserve
+                  IN: Boolean flag indicating whether the ageout based 
+              decrement algorithms will maintain a empty reserve when decreasing 
+              cache size.
      double empty_reserve
+                  IN: Empty reserve as a fraction of maximum cache 
+              size if applicable.
+              
      When so directed, the ageout based algorithms will not decrease 
+              the maximum cache size unless the empty reserve can be met.
+              
      The parameter must lie in the interval [0.0, 1.0].  
+              0.1 or 0.05 is a good place to start.
    
+
    Returns:
+    
    Returns a non-negative value if successful; otherwise returns a
+        negative value.
+
+
    
+
+
 
 
    
 
    
@@ -1317,11 +1885,11 @@ END SUBROUTINE h5freopen_f
 
    Parameters:
     
      
-		    
+            
-		    
+            
      
         
      hid_t loc_idhid_t loc_id
             IN: File or group identifier for the location at which
                 the specified file is to be unmounted.
      
         
      const char *name    const char *name    
             IN: Name of the mount point.
      
     
    
 
    Returns:
@@ -1329,7 +1897,7 @@ END SUBROUTINE h5freopen_f
         otherwise returns a negative value.
 
    Fortran90 Interface: h5funmount_f
     
    
-	
    +    
     SUBROUTINE h5funmount_f(loc_id, name, child_id, hdferr)
   IMPLICIT NONE 
   INTEGER(HID_T), INTENT(IN)  :: loc_id      ! File or group identifier
@@ -1337,10 +1905,10 @@ SUBROUTINE h5funmount_f(loc_id, name, child_id, hdferr)
   INTEGER, INTENT(OUT)        :: hdferr      ! Error code 
                                              ! 0 on success and -1 on failure
 END SUBROUTINE h5funmount_f
-	
    		
-		
-