H5ACprivate.h

00001 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
00002  * Copyright by The HDF Group.                                               *
00003  * Copyright by the Board of Trustees of the University of Illinois.         *
00004  * All rights reserved.                                                      *
00005  *                                                                           *
00006  * This file is part of HDF5.  The full HDF5 copyright notice, including     *
00007  * terms governing use, modification, and redistribution, is contained in    *
00008  * the files COPYING and Copyright.html.  COPYING can be found at the root   *
00009  * of the source code distribution tree; Copyright.html can be found at the  *
00010  * root level of an installed copy of the electronic HDF5 document set and   *
00011  * is linked from the top-level documents page.  It can also be found at     *
00012  * http://hdfgroup.org/HDF5/doc/Copyright.html.  If you do not have          *
00013  * access to either file, you may request a copy from help@hdfgroup.org.     *
00014  * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
00015 
00016 /*-------------------------------------------------------------------------
00017  *
00018  * Created:             H5ACprivate.h
00019  *                      Jul  9 1997
00020  *                      Robb Matzke <matzke@llnl.gov>
00021  *
00022  * Purpose:             Constants and typedefs available to the rest of the
00023  *                      library.
00024  *
00025  * Modifications:       JRM - 6/4/04
00026  *                      Complete re-write for a new caching algorithm
00027  *                      located in H5C.c
00028  *
00029  *-------------------------------------------------------------------------
00030  */
00031 
00032 #ifndef _H5ACprivate_H
00033 #define _H5ACprivate_H
00034 
00035 #include "H5ACpublic.h"         /*public prototypes                     */
00036 
00037 /* Pivate headers needed by this header */
00038 #include "H5private.h"          /* Generic Functions                    */
00039 #include "H5Fprivate.h"         /* File access                          */
00040 #include "H5Cprivate.h"         /* cache                                */
00041 
00042 #ifdef H5_METADATA_TRACE_FILE
00043 #define H5AC__TRACE_FILE_ENABLED        1
00044 #else /* H5_METADATA_TRACE_FILE */
00045 #define H5AC__TRACE_FILE_ENABLED        0
00046 #endif /* H5_METADATA_TRACE_FILE */
00047 
00048 /* Types of metadata objects cached */
00049 typedef enum {
00050     H5AC_BT_ID = 0,     /*B-tree nodes                               */
00051     H5AC_SNODE_ID,      /*symbol table nodes                         */
00052     H5AC_LHEAP_PRFX_ID, /*local heap prefix                          */
00053     H5AC_LHEAP_DBLK_ID, /*local heap data block                      */
00054     H5AC_GHEAP_ID,      /*global heap                                */
00055     H5AC_OHDR_ID,       /*object header                              */
00056     H5AC_BT2_HDR_ID,    /*v2 B-tree header                           */
00057     H5AC_BT2_INT_ID,    /*v2 B-tree internal node                    */
00058     H5AC_BT2_LEAF_ID,   /*v2 B-tree leaf node                        */
00059     H5AC_FHEAP_HDR_ID,  /*fractal heap header                        */
00060     H5AC_FHEAP_DBLOCK_ID, /*fractal heap direct block                */
00061     H5AC_FHEAP_IBLOCK_ID, /*fractal heap indirect block              */
00062     H5AC_FSPACE_HDR_ID, /*free space header                          */
00063     H5AC_FSPACE_SINFO_ID,/*free space sections                       */
00064     H5AC_SOHM_TABLE_ID, /*shared object header message master table  */
00065     H5AC_SOHM_LIST_ID,  /*shared message index stored as a list      */
00066     H5AC_SUPERBLOCK_ID, /* file superblock                           */
00067     H5AC_TEST_ID,       /*test entry -- not used for actual files    */
00068     H5AC_NTYPES         /* Number of types, must be last             */
00069 } H5AC_type_t;
00070 
00071 /* H5AC_DUMP_STATS_ON_CLOSE should always be FALSE when
00072  * H5C_COLLECT_CACHE_STATS is FALSE.
00073  *
00074  * When H5C_COLLECT_CACHE_STATS is TRUE, H5AC_DUMP_STATS_ON_CLOSE must
00075  * be FALSE for "make check" to succeed, but may be set to TRUE at other
00076  * times for debugging purposes.
00077  *
00078  * Hence the following, somewhat odd set of #defines.
00079  */
00080 #if H5C_COLLECT_CACHE_STATS
00081 
00082 #define H5AC_DUMP_STATS_ON_CLOSE        0
00083 
00084 #else /* H5C_COLLECT_CACHE_STATS */
00085 
00086 #define H5AC_DUMP_STATS_ON_CLOSE        0
00087 
00088 #endif /* H5C_COLLECT_CACHE_STATS */
00089 
00090 /* Default max metadata cache size and min clean size are give here.
00091  * At present, these are the same as those given in H5Cprivate.h.
00092  */
00093 
00094 #define H5AC__DEFAULT_MAX_CACHE_SIZE    H5C__DEFAULT_MAX_CACHE_SIZE
00095 #define H5AC__DEFAULT_MIN_CLEAN_SIZE    H5C__DEFAULT_MIN_CLEAN_SIZE
00096 
00097 
00098 /*
00099  * Class methods pertaining to caching.  Each type of cached object will
00100  * have a constant variable with permanent life-span that describes how
00101  * to cache the object.  That variable will be of type H5AC_class_t and
00102  * have the following required fields...
00103  *
00104  * LOAD:        Loads an object from disk to memory.  The function
00105  *              should allocate some data structure and return it.
00106  *
00107  * FLUSH:       Writes some data structure back to disk.  It would be
00108  *              wise for the data structure to include dirty flags to
00109  *              indicate whether it really needs to be written.  This
00110  *              function is also responsible for freeing memory allocated
00111  *              by the LOAD method if the DEST argument is non-zero (by
00112  *              calling the DEST method).
00113  *
00114  * DEST:        Just frees memory allocated by the LOAD method.
00115  *
00116  * CLEAR:       Just marks object as non-dirty.
00117  *
00118  * SIZE:        Report the size (on disk) of the specified cache object.
00119  *              Note that the space allocated on disk may not be contiguous.
00120  */
00121 
00122 #define H5AC_CALLBACK__NO_FLAGS_SET             H5C_CALLBACK__NO_FLAGS_SET
00123 #define H5AC_CALLBACK__SIZE_CHANGED_FLAG        H5C_CALLBACK__SIZE_CHANGED_FLAG
00124 #define H5AC_CALLBACK__RENAMED_FLAG             H5C_CALLBACK__RENAMED_FLAG
00125 
00126 typedef H5C_load_func_t         H5AC_load_func_t;
00127 typedef H5C_flush_func_t        H5AC_flush_func_t;
00128 typedef H5C_dest_func_t         H5AC_dest_func_t;
00129 typedef H5C_clear_func_t        H5AC_clear_func_t;
00130 typedef H5C_size_func_t         H5AC_size_func_t;
00131 
00132 typedef H5C_class_t             H5AC_class_t;
00133 
00134 
00135 /* The H5AC_NSLOTS #define is now obsolete, as the metadata cache no longer
00136  * uses slots.  However I am leaving it in for now to avoid modifying the
00137  * interface between the metadata cache and the rest of HDF.  It should
00138  * be removed when we get to dealing with the size_hint parameter in
00139  * H5AC_create().
00140  *                                              JRM - 5/20/04
00141  *
00142  * Old comment on H5AC_NSLOTS follows:
00143  *
00144  * A cache has a certain number of entries.  Objects are mapped into a
00145  * cache entry by hashing the object's file address.  Each file has its
00146  * own cache, an array of slots.
00147  */
00148 #define H5AC_NSLOTS     10330           /* The library "likes" this number... */
00149 
00150 
00151 typedef H5C_cache_entry_t       H5AC_info_t;
00152 
00153 
00154 /*===----------------------------------------------------------------------===
00155  *                             Protect Types
00156  *===----------------------------------------------------------------------===
00157  *
00158  * These are for the wrapper functions to H5AC_protect. They specify what
00159  * type of operation you're planning on doing to the metadata. The
00160  * Flexible Parallel HDF5 locking can then act accordingly.
00161  */
00162 
00163 typedef enum H5AC_protect_t {
00164     H5AC_WRITE,                 /* Protect object for writing                */
00165     H5AC_READ                   /* Protect object for reading                */
00166 } H5AC_protect_t;
00167 
00168 
00169 /* Typedef for metadata cache (defined in H5Cpkg.h) */
00170 typedef H5C_t   H5AC_t;
00171 
00172 /* Metadata specific properties for FAPL */
00173 /* (Only used for parallel I/O) */
00174 #ifdef H5_HAVE_PARALLEL
00175 /* Definitions for "block before metadata write" property */
00176 #define H5AC_BLOCK_BEFORE_META_WRITE_NAME       "H5AC_block_before_meta_write"
00177 #define H5AC_BLOCK_BEFORE_META_WRITE_SIZE       sizeof(unsigned)
00178 #define H5AC_BLOCK_BEFORE_META_WRITE_DEF        0
00179 
00180 /* Definitions for "library internal" property */
00181 #define H5AC_LIBRARY_INTERNAL_NAME       "H5AC_library_internal"
00182 #define H5AC_LIBRARY_INTERNAL_SIZE       sizeof(unsigned)
00183 #define H5AC_LIBRARY_INTERNAL_DEF        0
00184 #endif /* H5_HAVE_PARALLEL */
00185 
00186 /* Dataset transfer property list for flush calls */
00187 /* (Collective set, "block before metadata write" set and "library internal" set) */
00188 /* (Global variable declaration, definition is in H5AC.c) */
00189 extern hid_t H5AC_dxpl_id;
00190 
00191 /* Dataset transfer property list for independent metadata I/O calls */
00192 /* (just "library internal" set - i.e. independent transfer mode) */
00193 /* (Global variable declaration, definition is in H5AC.c) */
00194 extern hid_t H5AC_ind_dxpl_id;
00195 
00196 
00197 /* Default cache configuration. */
00198 
00199 #ifdef H5_HAVE_PARALLEL
00200 #define H5AC__DEFAULT_CACHE_CONFIG                                            \
00201 {                                                                             \
00202   /* int         version                = */ H5C__CURR_AUTO_SIZE_CTL_VER,     \
00203   /* hbool_t     rpt_fcn_enabled        = */ FALSE,                           \
00204   /* hbool_t     open_trace_file        = */ FALSE,                           \
00205   /* hbool_t     close_trace_file       = */ FALSE,                           \
00206   /* char        trace_file_name[]      = */ "",                              \
00207   /* hbool_t     evictions_enabled      = */ TRUE,                            \
00208   /* hbool_t     set_initial_size       = */ TRUE,                            \
00209   /* size_t      initial_size           = */ ( 2 * 1024 * 1024),              \
00210   /* double      min_clean_fraction     = */ 0.3,                             \
00211   /* size_t      max_size               = */ (32 * 1024 * 1024),              \
00212   /* size_t      min_size               = */ ( 1 * 1024 * 1024),              \
00213   /* long int    epoch_length           = */ 50000,                           \
00214   /* enum H5C_cache_incr_mode incr_mode = */ H5C_incr__threshold,             \
00215   /* double      lower_hr_threshold     = */ 0.9,                             \
00216   /* double      increment              = */ 2.0,                             \
00217   /* hbool_t     apply_max_increment    = */ TRUE,                            \
00218   /* size_t      max_increment          = */ (4 * 1024 * 1024),               \
00219   /* enum H5C_cache_flash_incr_mode       */                                  \
00220   /*                    flash_incr_mode = */ H5C_flash_incr__add_space,       \
00221   /* double      flash_multiple         = */ 1.0,                             \
00222   /* double      flash_threshold        = */ 0.25,                            \
00223   /* enum H5C_cache_decr_mode decr_mode = */ H5C_decr__age_out_with_threshold,\
00224   /* double      upper_hr_threshold     = */ 0.999,                           \
00225   /* double      decrement              = */ 0.9,                             \
00226   /* hbool_t     apply_max_decrement    = */ TRUE,                            \
00227   /* size_t      max_decrement          = */ (1 * 1024 * 1024),               \
00228   /* int         epochs_before_eviction = */ 3,                               \
00229   /* hbool_t     apply_empty_reserve    = */ TRUE,                            \
00230   /* double      empty_reserve          = */ 0.1,                             \
00231   /* int         dirty_bytes_threshold  = */ (256 * 1024)                     \
00232 }
00233 #else /* H5_HAVE_PARALLEL */
00234 #define H5AC__DEFAULT_CACHE_CONFIG                                            \
00235 {                                                                             \
00236   /* int         version                = */ H5C__CURR_AUTO_SIZE_CTL_VER,     \
00237   /* hbool_t     rpt_fcn_enabled        = */ FALSE,                           \
00238   /* hbool_t     open_trace_file        = */ FALSE,                           \
00239   /* hbool_t     close_trace_file       = */ FALSE,                           \
00240   /* char        trace_file_name[]      = */ "",                              \
00241   /* hbool_t     evictions_enabled      = */ TRUE,                            \
00242   /* hbool_t     set_initial_size       = */ TRUE,                            \
00243   /* size_t      initial_size           = */ ( 2 * 1024 * 1024),              \
00244   /* double      min_clean_fraction     = */ 0.01,                            \
00245   /* size_t      max_size               = */ (32 * 1024 * 1024),              \
00246   /* size_t      min_size               = */ ( 1 * 1024 * 1024),              \
00247   /* long int    epoch_length           = */ 50000,                           \
00248   /* enum H5C_cache_incr_mode incr_mode = */ H5C_incr__threshold,             \
00249   /* double      lower_hr_threshold     = */ 0.9,                             \
00250   /* double      increment              = */ 2.0,                             \
00251   /* hbool_t     apply_max_increment    = */ TRUE,                            \
00252   /* size_t      max_increment          = */ (4 * 1024 * 1024),               \
00253   /* enum H5C_cache_flash_incr_mode       */                                  \
00254   /*                    flash_incr_mode = */ H5C_flash_incr__add_space,       \
00255   /* double      flash_multiple         = */ 1.4,                             \
00256   /* double      flash_threshold        = */ 0.25,                            \
00257   /* enum H5C_cache_decr_mode decr_mode = */ H5C_decr__age_out_with_threshold,\
00258   /* double      upper_hr_threshold     = */ 0.999,                           \
00259   /* double      decrement              = */ 0.9,                             \
00260   /* hbool_t     apply_max_decrement    = */ TRUE,                            \
00261   /* size_t      max_decrement          = */ (1 * 1024 * 1024),               \
00262   /* int         epochs_before_eviction = */ 3,                               \
00263   /* hbool_t     apply_empty_reserve    = */ TRUE,                            \
00264   /* double      empty_reserve          = */ 0.1,                             \
00265   /* int         dirty_bytes_threshold  = */ (256 * 1024)                     \
00266 }
00267 #endif /* H5_HAVE_PARALLEL */
00268 
00269 
00270 /*
00271  * Library prototypes.
00272  */
00273 
00274 /* #defines of flags used in the flags parameters in some of the
00275  * following function calls.  Note that they are just copies of
00276  * the equivalent flags from H5Cprivate.h.
00277  */
00278 
00279 #define H5AC__NO_FLAGS_SET                H5C__NO_FLAGS_SET
00280 #define H5AC__SET_FLUSH_MARKER_FLAG       H5C__SET_FLUSH_MARKER_FLAG
00281 #define H5AC__DELETED_FLAG                H5C__DELETED_FLAG
00282 #define H5AC__DIRTIED_FLAG                H5C__DIRTIED_FLAG
00283 #define H5AC__SIZE_CHANGED_FLAG           H5C__SIZE_CHANGED_FLAG
00284 #define H5AC__PIN_ENTRY_FLAG              H5C__PIN_ENTRY_FLAG
00285 #define H5AC__UNPIN_ENTRY_FLAG            H5C__UNPIN_ENTRY_FLAG
00286 #define H5AC__FLUSH_INVALIDATE_FLAG       H5C__FLUSH_INVALIDATE_FLAG
00287 #define H5AC__FLUSH_CLEAR_ONLY_FLAG       H5C__FLUSH_CLEAR_ONLY_FLAG
00288 #define H5AC__FLUSH_MARKED_ENTRIES_FLAG   H5C__FLUSH_MARKED_ENTRIES_FLAG
00289 #define H5AC__FLUSH_IGNORE_PROTECTED_FLAG H5C__FLUSH_IGNORE_PROTECTED_FLAG
00290 #define H5AC__FREE_FILE_SPACE_FLAG        H5C__FREE_FILE_SPACE_FLAG
00291 #define H5AC__TAKE_OWNERSHIP_FLAG         H5C__TAKE_OWNERSHIP_FLAG
00292 
00293 
00294 /* #defines of flags used to report entry status in the
00295  * H5AC_get_entry_status() call.
00296  */
00297 
00298 #define H5AC_ES__IN_CACHE       0x0001
00299 #define H5AC_ES__IS_DIRTY       0x0002
00300 #define H5AC_ES__IS_PROTECTED   0x0004
00301 #define H5AC_ES__IS_PINNED      0x0008
00302 
00303 
00304 /* external function declarations: */
00305 
00306 H5_DLL herr_t H5AC_init(void);
00307 H5_DLL herr_t H5AC_create(const H5F_t *f, H5AC_cache_config_t *config_ptr);
00308 H5_DLL herr_t H5AC_get_entry_status(const H5F_t * f, haddr_t addr,
00309                                     unsigned * status_ptr);
00310 H5_DLL herr_t H5AC_set(H5F_t *f, hid_t dxpl_id, const H5AC_class_t *type,
00311                        haddr_t addr, void *thing, unsigned int flags);
00312 H5_DLL herr_t H5AC_pin_protected_entry(void *thing);
00313 H5_DLL void * H5AC_protect(H5F_t *f, hid_t dxpl_id, const H5AC_class_t *type,
00314                            haddr_t addr, const void *udata1, void *udata2,
00315                            H5AC_protect_t rw);
00316 H5_DLL herr_t H5AC_resize_pinned_entry(void *thing, size_t new_size);
00317 H5_DLL herr_t H5AC_unpin_entry(void *thing);
00318 H5_DLL herr_t H5AC_unprotect(H5F_t *f, hid_t dxpl_id,
00319                              const H5AC_class_t *type, haddr_t addr,
00320                              void *thing, unsigned flags);
00321 H5_DLL herr_t H5AC_flush(H5F_t *f, hid_t dxpl_id);
00322 H5_DLL herr_t H5AC_mark_pinned_entry_dirty(void *thing, hbool_t size_changed,
00323     size_t  new_size);
00324 H5_DLL herr_t H5AC_mark_pinned_or_protected_entry_dirty(void *thing);
00325 H5_DLL herr_t H5AC_rename(H5F_t *f, const H5AC_class_t *type,
00326                            haddr_t old_addr, haddr_t new_addr);
00327 
00328 H5_DLL herr_t H5AC_dest(H5F_t *f, hid_t dxpl_id);
00329 
00330 H5_DLL herr_t H5AC_expunge_entry(H5F_t *f, hid_t dxpl_id,
00331                                  const H5AC_class_t *type, haddr_t addr,
00332                                  unsigned flags);
00333 
00334 H5_DLL herr_t H5AC_set_write_done_callback(H5C_t * cache_ptr,
00335                                            void (* write_done)(void));
00336 H5_DLL herr_t H5AC_stats(const H5F_t *f);
00337 
00338 H5_DLL herr_t H5AC_get_cache_auto_resize_config(const H5AC_t * cache_ptr,
00339                                                H5AC_cache_config_t *config_ptr);
00340 
00341 H5_DLL herr_t H5AC_get_cache_size(H5AC_t * cache_ptr,
00342                                   size_t * max_size_ptr,
00343                                   size_t * min_clean_size_ptr,
00344                                   size_t * cur_size_ptr,
00345                                   int32_t * cur_num_entries_ptr);
00346 
00347 H5_DLL herr_t H5AC_get_cache_hit_rate(H5AC_t * cache_ptr,
00348                                       double * hit_rate_ptr);
00349 
00350 H5_DLL herr_t H5AC_reset_cache_hit_rate_stats(H5AC_t * cache_ptr);
00351 
00352 H5_DLL herr_t H5AC_set_cache_auto_resize_config(H5AC_t *cache_ptr,
00353                                                H5AC_cache_config_t *config_ptr);
00354 
00355 H5_DLL herr_t H5AC_validate_config(H5AC_cache_config_t * config_ptr);
00356 
00357 H5_DLL herr_t H5AC_close_trace_file( H5AC_t * cache_ptr);
00358 
00359 H5_DLL herr_t H5AC_open_trace_file(H5AC_t * cache_ptr,
00360                                    const char * trace_file_name);
00361 
00362 #endif /* !_H5ACprivate_H */
00363