1 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * 2 * Copyright by The HDF Group. * 3 * Copyright by the Board of Trustees of the University of Illinois. * 4 * All rights reserved. * 5 * * 6 * This file is part of HDF5. The full HDF5 copyright notice, including * 7 * terms governing use, modification, and redistribution, is contained in * 8 * the files COPYING and Copyright.html. COPYING can be found at the root * 9 * of the source code distribution tree; Copyright.html can be found at the * 10 * root level of an installed copy of the electronic HDF5 document set and * 11 * is linked from the top-level documents page. It can also be found at * 12 * http://hdfgroup.org/HDF5/doc/Copyright.html. If you do not have * 13 * access to either file, you may request a copy from help@hdfgroup.org. * 14 * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ 15 16 /*------------------------------------------------------------------------- 17 * 18 * Created: H5ACprivate.h 19 * Jul 9 1997 20 * Robb Matzke <matzke@llnl.gov> 21 * 22 * Purpose: Constants and typedefs available to the rest of the 23 * library. 24 * 25 *------------------------------------------------------------------------- 26 */ 27 28 #ifndef _H5ACprivate_H 29 #define _H5ACprivate_H 30 31 #include "H5ACpublic.h" /*public prototypes */ 32 33 /* Pivate headers needed by this header */ 34 #include "H5private.h" /* Generic Functions */ 35 #include "H5Cprivate.h" /* Cache */ 36 #include "H5Fprivate.h" /* File access */ 37 38 #ifdef H5_METADATA_TRACE_FILE 39 #define H5AC__TRACE_FILE_ENABLED 1 40 #else /* H5_METADATA_TRACE_FILE */ 41 #define H5AC__TRACE_FILE_ENABLED 0 42 #endif /* H5_METADATA_TRACE_FILE */ 43 44 /* Types of metadata objects cached */ 45 typedef enum { 46 H5AC_BT_ID = 0, /*B-tree nodes */ 47 H5AC_SNODE_ID, /*symbol table nodes */ 48 H5AC_LHEAP_PRFX_ID, /*local heap prefix */ 49 H5AC_LHEAP_DBLK_ID, /*local heap data block */ 50 H5AC_GHEAP_ID, /*global heap */ 51 H5AC_OHDR_ID, /*object header */ 52 H5AC_OHDR_CHK_ID, /*object header chunk */ 53 H5AC_BT2_HDR_ID, /*v2 B-tree header */ 54 H5AC_BT2_INT_ID, /*v2 B-tree internal node */ 55 H5AC_BT2_LEAF_ID, /*v2 B-tree leaf node */ 56 H5AC_FHEAP_HDR_ID, /*fractal heap header */ 57 H5AC_FHEAP_DBLOCK_ID, /*fractal heap direct block */ 58 H5AC_FHEAP_IBLOCK_ID, /*fractal heap indirect block */ 59 H5AC_FSPACE_HDR_ID, /*free space header */ 60 H5AC_FSPACE_SINFO_ID,/*free space sections */ 61 H5AC_SOHM_TABLE_ID, /*shared object header message master table */ 62 H5AC_SOHM_LIST_ID, /*shared message index stored as a list */ 63 H5AC_SUPERBLOCK_ID, /* file superblock */ 64 H5AC_TEST_ID, /*test entry -- not used for actual files */ 65 H5AC_NTYPES /* Number of types, must be last */ 66 } H5AC_type_t; 67 68 /* H5AC_DUMP_STATS_ON_CLOSE should always be FALSE when 69 * H5C_COLLECT_CACHE_STATS is FALSE. 70 * 71 * When H5C_COLLECT_CACHE_STATS is TRUE, H5AC_DUMP_STATS_ON_CLOSE must 72 * be FALSE for "make check" to succeed, but may be set to TRUE at other 73 * times for debugging purposes. 74 * 75 * Hence the following, somewhat odd set of #defines. 76 */ 77 #if H5C_COLLECT_CACHE_STATS 78 79 #define H5AC_DUMP_STATS_ON_CLOSE 0 80 81 #else /* H5C_COLLECT_CACHE_STATS */ 82 83 #define H5AC_DUMP_STATS_ON_CLOSE 0 84 85 #endif /* H5C_COLLECT_CACHE_STATS */ 86 87 /* Default max metadata cache size and min clean size are give here. 88 * At present, these are the same as those given in H5Cprivate.h. 89 */ 90 91 #define H5AC__DEFAULT_MAX_CACHE_SIZE H5C__DEFAULT_MAX_CACHE_SIZE 92 #define H5AC__DEFAULT_MIN_CLEAN_SIZE H5C__DEFAULT_MIN_CLEAN_SIZE 93 94 95 /* 96 * Class methods pertaining to caching. Each type of cached object will 97 * have a constant variable with permanent life-span that describes how 98 * to cache the object. That variable will be of type H5AC_class_t and 99 * have the following required fields... 100 * 101 * LOAD: Loads an object from disk to memory. The function 102 * should allocate some data structure and return it. 103 * 104 * FLUSH: Writes some data structure back to disk. It would be 105 * wise for the data structure to include dirty flags to 106 * indicate whether it really needs to be written. This 107 * function is also responsible for freeing memory allocated 108 * by the LOAD method if the DEST argument is non-zero (by 109 * calling the DEST method). 110 * 111 * DEST: Just frees memory allocated by the LOAD method. 112 * 113 * CLEAR: Just marks object as non-dirty. 114 * 115 * SIZE: Report the size (on disk) of the specified cache object. 116 * Note that the space allocated on disk may not be contiguous. 117 */ 118 119 #define H5AC_CALLBACK__NO_FLAGS_SET H5C_CALLBACK__NO_FLAGS_SET 120 #define H5AC_CALLBACK__SIZE_CHANGED_FLAG H5C_CALLBACK__SIZE_CHANGED_FLAG 121 #define H5AC_CALLBACK__MOVED_FLAG H5C_CALLBACK__MOVED_FLAG 122 123 typedef H5C_load_func_t H5AC_load_func_t; 124 typedef H5C_flush_func_t H5AC_flush_func_t; 125 typedef H5C_dest_func_t H5AC_dest_func_t; 126 typedef H5C_clear_func_t H5AC_clear_func_t; 127 typedef H5C_size_func_t H5AC_size_func_t; 128 129 typedef H5C_class_t H5AC_class_t; 130 131 132 /* The H5AC_NSLOTS #define is now obsolete, as the metadata cache no longer 133 * uses slots. However I am leaving it in for now to avoid modifying the 134 * interface between the metadata cache and the rest of HDF. It should 135 * be removed when we get to dealing with the size_hint parameter in 136 * H5AC_create(). 137 * JRM - 5/20/04 138 * 139 * Old comment on H5AC_NSLOTS follows: 140 * 141 * A cache has a certain number of entries. Objects are mapped into a 142 * cache entry by hashing the object's file address. Each file has its 143 * own cache, an array of slots. 144 */ 145 #define H5AC_NSLOTS 10330 /* The library "likes" this number... */ 146 147 148 typedef H5C_cache_entry_t H5AC_info_t; 149 150 151 /*===----------------------------------------------------------------------=== 152 * Protect Types 153 *===----------------------------------------------------------------------=== 154 * 155 * These are for the wrapper functions to H5AC_protect. They specify what 156 * type of operation you're planning on doing to the metadata. The 157 * Flexible Parallel HDF5 locking can then act accordingly. 158 */ 159 160 typedef enum H5AC_protect_t { 161 H5AC_WRITE, /* Protect object for writing */ 162 H5AC_READ /* Protect object for reading */ 163 } H5AC_protect_t; 164 165 166 /* Typedef for metadata cache (defined in H5Cpkg.h) */ 167 typedef H5C_t H5AC_t; 168 169 /* Metadata specific properties for FAPL */ 170 /* (Only used for parallel I/O) */ 171 #ifdef H5_HAVE_PARALLEL 172 /* Definitions for "block before metadata write" property */ 173 #define H5AC_BLOCK_BEFORE_META_WRITE_NAME "H5AC_block_before_meta_write" 174 #define H5AC_BLOCK_BEFORE_META_WRITE_SIZE sizeof(unsigned) 175 #define H5AC_BLOCK_BEFORE_META_WRITE_DEF 0 176 177 /* Definitions for "collective metadata write" property */ 178 #define H5AC_COLLECTIVE_META_WRITE_NAME "H5AC_collective_metadata_write" 179 #define H5AC_COLLECTIVE_META_WRITE_SIZE sizeof(unsigned) 180 #define H5AC_COLLECTIVE_META_WRITE_DEF 0 181 182 /* Definitions for "library internal" property */ 183 #define H5AC_LIBRARY_INTERNAL_NAME "H5AC_library_internal" 184 #define H5AC_LIBRARY_INTERNAL_SIZE sizeof(unsigned) 185 #define H5AC_LIBRARY_INTERNAL_DEF 0 186 #endif /* H5_HAVE_PARALLEL */ 187 188 /* Dataset transfer property list for flush calls */ 189 /* (Collective set, "block before metadata write" set and "library internal" set) */ 190 /* (Global variable declaration, definition is in H5AC.c) */ 191 extern hid_t H5AC_dxpl_id; 192 193 /* Dataset transfer property list for independent metadata I/O calls */ 194 /* (just "library internal" set - i.e. independent transfer mode) */ 195 /* (Global variable declaration, definition is in H5AC.c) */ 196 extern hid_t H5AC_ind_dxpl_id; 197 198 199 /* Default cache configuration. */ 200 201 #define H5AC__DEFAULT_METADATA_WRITE_STRATEGY \ 202 H5AC_METADATA_WRITE_STRATEGY__DISTRIBUTED 203 204 #ifdef H5_HAVE_PARALLEL 205 #define H5AC__DEFAULT_CACHE_CONFIG \ 206 { \ 207 /* int version = */ H5AC__CURR_CACHE_CONFIG_VERSION, \ 208 /* hbool_t rpt_fcn_enabled = */ FALSE, \ 209 /* hbool_t open_trace_file = */ FALSE, \ 210 /* hbool_t close_trace_file = */ FALSE, \ 211 /* char trace_file_name[] = */ "", \ 212 /* hbool_t evictions_enabled = */ TRUE, \ 213 /* hbool_t set_initial_size = */ TRUE, \ 214 /* size_t initial_size = */ ( 2 * 1024 * 1024), \ 215 /* double min_clean_fraction = */ 0.3, \ 216 /* size_t max_size = */ (32 * 1024 * 1024), \ 217 /* size_t min_size = */ (1 * 1024 * 1024), \ 218 /* long int epoch_length = */ 50000, \ 219 /* enum H5C_cache_incr_mode incr_mode = */ H5C_incr__threshold, \ 220 /* double lower_hr_threshold = */ 0.9, \ 221 /* double increment = */ 2.0, \ 222 /* hbool_t apply_max_increment = */ TRUE, \ 223 /* size_t max_increment = */ (4 * 1024 * 1024), \ 224 /* enum H5C_cache_flash_incr_mode */ \ 225 /* flash_incr_mode = */ H5C_flash_incr__add_space, \ 226 /* double flash_multiple = */ 1.0, \ 227 /* double flash_threshold = */ 0.25, \ 228 /* enum H5C_cache_decr_mode decr_mode = */ H5C_decr__age_out_with_threshold, \ 229 /* double upper_hr_threshold = */ 0.999, \ 230 /* double decrement = */ 0.9, \ 231 /* hbool_t apply_max_decrement = */ TRUE, \ 232 /* size_t max_decrement = */ (1 * 1024 * 1024), \ 233 /* int epochs_before_eviction = */ 3, \ 234 /* hbool_t apply_empty_reserve = */ TRUE, \ 235 /* double empty_reserve = */ 0.1, \ 236 /* int dirty_bytes_threshold = */ (256 * 1024), \ 237 /* int metadata_write_strategy = */ \ 238 H5AC__DEFAULT_METADATA_WRITE_STRATEGY \ 239 } 240 #else /* H5_HAVE_PARALLEL */ 241 #define H5AC__DEFAULT_CACHE_CONFIG \ 242 { \ 243 /* int version = */ H5C__CURR_AUTO_SIZE_CTL_VER, \ 244 /* hbool_t rpt_fcn_enabled = */ FALSE, \ 245 /* hbool_t open_trace_file = */ FALSE, \ 246 /* hbool_t close_trace_file = */ FALSE, \ 247 /* char trace_file_name[] = */ "", \ 248 /* hbool_t evictions_enabled = */ TRUE, \ 249 /* hbool_t set_initial_size = */ TRUE, \ 250 /* size_t initial_size = */ ( 2 * 1024 * 1024), \ 251 /* double min_clean_fraction = */ 0.01, \ 252 /* size_t max_size = */ (32 * 1024 * 1024), \ 253 /* size_t min_size = */ ( 1 * 1024 * 1024), \ 254 /* long int epoch_length = */ 50000, \ 255 /* enum H5C_cache_incr_mode incr_mode = */ H5C_incr__threshold, \ 256 /* double lower_hr_threshold = */ 0.9, \ 257 /* double increment = */ 2.0, \ 258 /* hbool_t apply_max_increment = */ TRUE, \ 259 /* size_t max_increment = */ (4 * 1024 * 1024), \ 260 /* enum H5C_cache_flash_incr_mode */ \ 261 /* flash_incr_mode = */ H5C_flash_incr__add_space, \ 262 /* double flash_multiple = */ 1.4, \ 263 /* double flash_threshold = */ 0.25, \ 264 /* enum H5C_cache_decr_mode decr_mode = */ H5C_decr__age_out_with_threshold,\ 265 /* double upper_hr_threshold = */ 0.999, \ 266 /* double decrement = */ 0.9, \ 267 /* hbool_t apply_max_decrement = */ TRUE, \ 268 /* size_t max_decrement = */ (1 * 1024 * 1024), \ 269 /* int epochs_before_eviction = */ 3, \ 270 /* hbool_t apply_empty_reserve = */ TRUE, \ 271 /* double empty_reserve = */ 0.1, \ 272 /* int dirty_bytes_threshold = */ (256 * 1024), \ 273 /* int metadata_write_strategy = */ \ 274 H5AC__DEFAULT_METADATA_WRITE_STRATEGY \ 275 } 276 #endif /* H5_HAVE_PARALLEL */ 277 278 279 /* 280 * Library prototypes. 281 */ 282 283 /* #defines of flags used in the flags parameters in some of the 284 * following function calls. Note that they are just copies of 285 * the equivalent flags from H5Cprivate.h. 286 */ 287 288 #define H5AC__NO_FLAGS_SET H5C__NO_FLAGS_SET 289 #define H5AC__SET_FLUSH_MARKER_FLAG H5C__SET_FLUSH_MARKER_FLAG 290 #define H5AC__DELETED_FLAG H5C__DELETED_FLAG 291 #define H5AC__DIRTIED_FLAG H5C__DIRTIED_FLAG 292 #define H5AC__PIN_ENTRY_FLAG H5C__PIN_ENTRY_FLAG 293 #define H5AC__UNPIN_ENTRY_FLAG H5C__UNPIN_ENTRY_FLAG 294 #define H5AC__FLUSH_INVALIDATE_FLAG H5C__FLUSH_INVALIDATE_FLAG 295 #define H5AC__FLUSH_CLEAR_ONLY_FLAG H5C__FLUSH_CLEAR_ONLY_FLAG 296 #define H5AC__FLUSH_MARKED_ENTRIES_FLAG H5C__FLUSH_MARKED_ENTRIES_FLAG 297 #define H5AC__FLUSH_IGNORE_PROTECTED_FLAG H5C__FLUSH_IGNORE_PROTECTED_FLAG 298 #define H5AC__FREE_FILE_SPACE_FLAG H5C__FREE_FILE_SPACE_FLAG 299 #define H5AC__TAKE_OWNERSHIP_FLAG H5C__TAKE_OWNERSHIP_FLAG 300 301 302 /* #defines of flags used to report entry status in the 303 * H5AC_get_entry_status() call. 304 */ 305 306 #define H5AC_ES__IN_CACHE 0x0001 307 #define H5AC_ES__IS_DIRTY 0x0002 308 #define H5AC_ES__IS_PROTECTED 0x0004 309 #define H5AC_ES__IS_PINNED 0x0008 310 311 312 /* external function declarations: */ 313 314 H5_DLL herr_t H5AC_init(void); 315 H5_DLL herr_t H5AC_create(const H5F_t *f, H5AC_cache_config_t *config_ptr); 316 H5_DLL herr_t H5AC_get_entry_status(const H5F_t *f, haddr_t addr, 317 unsigned * status_ptr); 318 H5_DLL herr_t H5AC_insert_entry(H5F_t *f, hid_t dxpl_id, const H5AC_class_t *type, 319 haddr_t addr, void *thing, unsigned int flags); 320 H5_DLL herr_t H5AC_pin_protected_entry(void *thing); 321 H5_DLL void * H5AC_protect(H5F_t *f, hid_t dxpl_id, const H5AC_class_t *type, 322 haddr_t addr, void *udata, H5AC_protect_t rw); 323 H5_DLL herr_t H5AC_resize_entry(void *thing, size_t new_size); 324 H5_DLL herr_t H5AC_unpin_entry(void *thing); 325 H5_DLL herr_t H5AC_unprotect(H5F_t *f, hid_t dxpl_id, 326 const H5AC_class_t *type, haddr_t addr, 327 void *thing, unsigned flags); 328 H5_DLL herr_t H5AC_flush(H5F_t *f, hid_t dxpl_id); 329 H5_DLL herr_t H5AC_mark_entry_dirty(void *thing); 330 H5_DLL herr_t H5AC_move_entry(H5F_t *f, const H5AC_class_t *type, 331 haddr_t old_addr, haddr_t new_addr); 332 333 H5_DLL herr_t H5AC_dest(H5F_t *f, hid_t dxpl_id); 334 335 H5_DLL herr_t H5AC_expunge_entry(H5F_t *f, hid_t dxpl_id, 336 const H5AC_class_t *type, haddr_t addr, 337 unsigned flags); 338 339 H5_DLL herr_t H5AC_set_sync_point_done_callback(H5C_t *cache_ptr, 340 void (*sync_point_done)(int num_writes, haddr_t *written_entries_tbl)); 341 342 H5_DLL herr_t H5AC_set_write_done_callback(H5C_t * cache_ptr, 343 void (* write_done)(void)); 344 H5_DLL herr_t H5AC_stats(const H5F_t *f); 345 346 H5_DLL herr_t H5AC_dump_cache(const H5F_t *f); 347 348 H5_DLL herr_t H5AC_get_cache_auto_resize_config(const H5AC_t * cache_ptr, 349 H5AC_cache_config_t *config_ptr); 350 351 H5_DLL herr_t H5AC_get_cache_size(H5AC_t * cache_ptr, 352 size_t * max_size_ptr, 353 size_t * min_clean_size_ptr, 354 size_t * cur_size_ptr, 355 int32_t * cur_num_entries_ptr); 356 357 H5_DLL herr_t H5AC_get_cache_hit_rate(H5AC_t * cache_ptr, 358 double * hit_rate_ptr); 359 360 H5_DLL herr_t H5AC_reset_cache_hit_rate_stats(H5AC_t * cache_ptr); 361 362 H5_DLL herr_t H5AC_set_cache_auto_resize_config(H5AC_t *cache_ptr, 363 H5AC_cache_config_t *config_ptr); 364 365 H5_DLL herr_t H5AC_validate_config(H5AC_cache_config_t * config_ptr); 366 367 H5_DLL herr_t H5AC_close_trace_file( H5AC_t * cache_ptr); 368 369 H5_DLL herr_t H5AC_open_trace_file(H5AC_t * cache_ptr, 370 const char * trace_file_name); 371 372 #ifdef H5_HAVE_PARALLEL 373 H5_DLL herr_t H5AC_add_candidate(H5AC_t * cache_ptr, haddr_t addr); 374 #endif /* H5_HAVE_PARALLEL */ 375 376 #endif /* !_H5ACprivate_H */ 377 378