EIC code displayed by LXR |
|
|
|
|||
File indexing completed on 2025-09-18 09:39:15
0001 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * 0002 * Copyright by The HDF Group. * 0003 * All rights reserved. * 0004 * * 0005 * This file is part of HDF5. The full HDF5 copyright notice, including * 0006 * terms governing use, modification, and redistribution, is contained in * 0007 * the COPYING file, which can be found at the root of the source code * 0008 * distribution tree, or in https://www.hdfgroup.org/licenses. * 0009 * If you do not have access to either file, you may request a copy from * 0010 * help@hdfgroup.org. * 0011 * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ 0012 0013 /* 0014 * Purpose: The public header file for the log virtual file driver (VFD) 0015 */ 0016 #ifndef H5FDlog_H 0017 #define H5FDlog_H 0018 0019 /** Initializer for the log VFD */ 0020 #define H5FD_LOG (H5FDperform_init(H5FD_log_init)) 0021 0022 /** Identifier for the log VFD */ 0023 #define H5FD_LOG_VALUE H5_VFD_LOG 0024 0025 /* Flags for H5Pset_fapl_log() */ 0026 0027 /** Flag for tracking truncate operation \since 1.10.1 */ 0028 #define H5FD_LOG_TRUNCATE 0x00000001 0029 /** Flag for tracking meta IO operations \since 1.10.1 */ 0030 #define H5FD_LOG_META_IO (H5FD_LOG_TRUNCATE) 0031 /** Flag for tracking where reads occur \since 1.6.0 */ 0032 #define H5FD_LOG_LOC_READ 0x00000002 0033 /** Flag for tracking where writes occur \since 1.6.0 */ 0034 #define H5FD_LOG_LOC_WRITE 0x00000004 0035 /** Flag for tracking where seeks occur \since 1.6.0 */ 0036 #define H5FD_LOG_LOC_SEEK 0x00000008 0037 /** Flag for tracking where IO operations occur \since 1.6.0 */ 0038 #define H5FD_LOG_LOC_IO (H5FD_LOG_LOC_READ | H5FD_LOG_LOC_WRITE | H5FD_LOG_LOC_SEEK) 0039 /** Flag for tracking number of times each byte is read \since 1.6.0 */ 0040 #define H5FD_LOG_FILE_READ 0x00000010 0041 /** Flag for tracking number of times each byte is written \since 1.6.0 */ 0042 #define H5FD_LOG_FILE_WRITE 0x00000020 0043 /** Flag for tracking number of times each byte is read/written \since 1.6.0 */ 0044 #define H5FD_LOG_FILE_IO (H5FD_LOG_FILE_READ | H5FD_LOG_FILE_WRITE) 0045 /** Flag for tracking "flavor" (type) of information stored at each byte \since 1.6.0 */ 0046 #define H5FD_LOG_FLAVOR 0x00000040 0047 /** Flag for tracking total number of reads \since 1.6.0 */ 0048 #define H5FD_LOG_NUM_READ 0x00000080 0049 /** Flag for tracking total number of writes \since 1.6.0 */ 0050 #define H5FD_LOG_NUM_WRITE 0x00000100 0051 /** Flag for tracking total number of seeks \since 1.6.0 */ 0052 #define H5FD_LOG_NUM_SEEK 0x00000200 0053 /** Flag for tracking total number of truncates \since 1.8.7 */ 0054 #define H5FD_LOG_NUM_TRUNCATE 0x00000400 0055 /** Flag for tracking total number of IO operations \since 1.6.0 */ 0056 #define H5FD_LOG_NUM_IO (H5FD_LOG_NUM_READ | H5FD_LOG_NUM_WRITE | H5FD_LOG_NUM_SEEK | H5FD_LOG_NUM_TRUNCATE) 0057 /** Flag for tracking time spent in open \since 1.8.7 */ 0058 #define H5FD_LOG_TIME_OPEN 0x00000800 0059 /** Flag for tracking time spent in stat \since 1.8.7 */ 0060 #define H5FD_LOG_TIME_STAT 0x00001000 0061 /** Flag for tracking time spent in read \since 1.8.7 */ 0062 #define H5FD_LOG_TIME_READ 0x00002000 0063 /** Flag for tracking time spent in write \since 1.6.0 */ 0064 #define H5FD_LOG_TIME_WRITE 0x00004000 0065 /** Flag for tracking time spent in seek \since 1.6.0 */ 0066 #define H5FD_LOG_TIME_SEEK 0x00008000 0067 /** Flag for tracking time spent in truncate \since 1.10.1 */ 0068 #define H5FD_LOG_TIME_TRUNCATE 0x00010000 0069 /** Flag for tracking time spent in close \since 1.6.0 */ 0070 #define H5FD_LOG_TIME_CLOSE 0x00020000 0071 /** Flag for tracking time spent in IO operations \since 1.6.0 */ 0072 #define H5FD_LOG_TIME_IO \ 0073 (H5FD_LOG_TIME_OPEN | H5FD_LOG_TIME_STAT | H5FD_LOG_TIME_READ | H5FD_LOG_TIME_WRITE | \ 0074 H5FD_LOG_TIME_SEEK | H5FD_LOG_TIME_TRUNCATE | H5FD_LOG_TIME_CLOSE) 0075 /** Flag for tracking allocation of space in file \since 1.6.0 */ 0076 #define H5FD_LOG_ALLOC 0x00040000 0077 /** Flag for tracking release of space in file \since 1.10.1 */ 0078 #define H5FD_LOG_FREE 0x00080000 0079 /** Flag for tracking all info \since 1.6.0 */ 0080 #define H5FD_LOG_ALL \ 0081 (H5FD_LOG_FREE | H5FD_LOG_ALLOC | H5FD_LOG_TIME_IO | H5FD_LOG_NUM_IO | H5FD_LOG_FLAVOR | \ 0082 H5FD_LOG_FILE_IO | H5FD_LOG_LOC_IO | H5FD_LOG_META_IO) 0083 0084 #ifdef __cplusplus 0085 extern "C" { 0086 #endif 0087 0088 /** @private 0089 * 0090 * \brief Private initializer for the log VFD 0091 */ 0092 H5_DLL hid_t H5FD_log_init(void); 0093 0094 /** 0095 * \ingroup FAPL 0096 * 0097 * \brief Sets up the logging virtual file driver (#H5FD_LOG) for use 0098 * 0099 * \fapl_id 0100 * \param[in] logfile Name of the log file 0101 * \param[in] flags Flags specifying the types of logging activity 0102 * \param[in] buf_size The size of the logging buffers, in bytes (see description) 0103 * \returns \herr_t 0104 * 0105 * \details H5Pset_fapl_log() modifies the file access property list to use the 0106 * logging driver, #H5FD_LOG. The logging virtual file driver (VFD) is 0107 * a clone of the standard SEC2 (#H5FD_SEC2) driver with additional 0108 * facilities for logging VFD metrics and activity to a file. 0109 * 0110 * \p logfile is the name of the file in which the logging entries are 0111 * to be recorded. 0112 * 0113 * The actions to be logged are specified in the parameter \p flags 0114 * using the pre-defined constants described in the following 0115 * table. Multiple flags can be set through the use of a logical \c OR 0116 * contained in parentheses. For example, logging read and write 0117 * locations would be specified as 0118 * \TText{(H5FD_LOG_LOC_READ|H5FD_LOG_LOC_WRITE)}. 0119 * 0120 * <table> 0121 * <caption>Table1: Logging Flags</caption> 0122 * <tr> 0123 * <td> 0124 * #H5FD_LOG_LOC_READ 0125 * </td> 0126 * <td rowspan="3"> 0127 * Track the location and length of every read, write, or seek operation. 0128 * </td> 0129 * </tr> 0130 * <tr><td>#H5FD_LOG_LOC_WRITE</td></tr> 0131 * <tr><td>#H5FD_LOG_LOC_SEEK</td></tr> 0132 * <tr> 0133 * <td> 0134 * #H5FD_LOG_LOC_IO 0135 * </td> 0136 * <td> 0137 * Track all I/O locations and lengths. The logical equivalent of the following: 0138 * \TText{(#H5FD_LOG_LOC_READ | #H5FD_LOG_LOC_WRITE | #H5FD_LOG_LOC_SEEK)} 0139 * </td> 0140 * </tr> 0141 * <tr> 0142 * <td> 0143 * #H5FD_LOG_FILE_READ 0144 * </td> 0145 * <td rowspan="2"> 0146 * Track the number of times each byte is read or written. 0147 * </td> 0148 * </tr> 0149 * <tr><td>#H5FD_LOG_FILE_WRITE</td></tr> 0150 * <tr> 0151 * <td> 0152 * #H5FD_LOG_FILE_IO 0153 * </td> 0154 * <td> 0155 * Track the number of times each byte is read and written. The logical 0156 * equivalent of the following: 0157 * \TText{(#H5FD_LOG_FILE_READ | #H5FD_LOG_FILE_WRITE)} 0158 * </td> 0159 * </tr> 0160 * <tr> 0161 * <td> 0162 * #H5FD_LOG_FLAVOR 0163 * </td> 0164 * <td> 0165 * Track the type, or flavor, of information stored at each byte. 0166 * </td> 0167 * </tr> 0168 * <tr> 0169 * <td> 0170 * #H5FD_LOG_NUM_READ 0171 * </td> 0172 * <td rowspan="4"> 0173 * Track the total number of read, write, seek, or truncate operations that occur. 0174 * </td> 0175 * </tr> 0176 * <tr><td>#H5FD_LOG_NUM_WRITE</td></tr> 0177 * <tr><td>#H5FD_LOG_NUM_SEEK</td></tr> 0178 * <tr><td>#H5FD_LOG_NUM_TRUNCATE</td></tr> 0179 * <tr> 0180 * <td> 0181 * #H5FD_LOG_NUM_IO 0182 * </td> 0183 * <td> 0184 * Track the total number of all types of I/O operations. The logical equivalent 0185 * of the following: 0186 * \TText{(#H5FD_LOG_NUM_READ | #H5FD_LOG_NUM_WRITE | #H5FD_LOG_NUM_SEEK | #H5FD_LOG_NUM_TRUNCATE)} 0187 * </td> 0188 * </tr> 0189 * <tr> 0190 * <td> 0191 * #H5FD_LOG_TIME_OPEN 0192 * </td> 0193 * <td rowspan="6"> 0194 * Track the time spent in open, stat, read, write, seek, or close operations. 0195 * </td> 0196 * </tr> 0197 * <tr><td>#H5FD_LOG_TIME_STAT</td></tr> 0198 * <tr><td>#H5FD_LOG_TIME_READ</td></tr> 0199 * <tr><td>#H5FD_LOG_TIME_WRITE</td></tr> 0200 * <tr><td>#H5FD_LOG_TIME_SEEK</td></tr> 0201 * <tr><td>#H5FD_LOG_TIME_CLOSE</td></tr> 0202 * <tr> 0203 * <td> 0204 * #H5FD_LOG_TIME_IO 0205 * </td> 0206 * <td> 0207 * Track the time spent in each of the above operations. The logical equivalent 0208 * of the following: 0209 * \TText{(#H5FD_LOG_TIME_OPEN | #H5FD_LOG_TIME_STAT | #H5FD_LOG_TIME_READ | #H5FD_LOG_TIME_WRITE | 0210 * #H5FD_LOG_TIME_SEEK | #H5FD_LOG_TIME_CLOSE)} 0211 * </td> 0212 * </tr> 0213 * <tr> 0214 * <td> 0215 * #H5FD_LOG_ALLOC 0216 * </td> 0217 * <td> 0218 * Track the allocation of space in the file. 0219 * </td> 0220 * </tr> 0221 * <tr> 0222 * <td> 0223 * #H5FD_LOG_ALL 0224 * </td> 0225 * <td> 0226 * Track everything. The logical equivalent of the following: 0227 * \TText{(#H5FD_LOG_ALLOC | #H5FD_LOG_TIME_IO | #H5FD_LOG_NUM_IO | #H5FD_LOG_FLAVOR | #H5FD_LOG_FILE_IO | 0228 * #H5FD_LOG_LOC_IO)} 0229 * </td> 0230 * </tr> 0231 * </table> 0232 * The logging driver can track the number of times each byte in the file is 0233 * read from or written to (using #H5FD_LOG_FILE_READ and #H5FD_LOG_FILE_WRITE) 0234 * and what kind of data is at that location (e.g., metadata, raw data; using 0235 * #H5FD_LOG_FLAVOR). This information is tracked in internal buffers of size 0236 * buf_size, which must be at least the maximum size in bytes of the file to be 0237 * logged while the log driver is in use.\n 0238 * One buffer of size buf_size will be created for each of #H5FD_LOG_FILE_READ, 0239 * #H5FD_LOG_FILE_WRITE and #H5FD_LOG_FLAVOR when those flags are set; these 0240 * buffers will not grow as the file increases in size. 0241 * 0242 * \par Output: 0243 * This section describes the logging driver (LOG VFD) output.\n 0244 * The table, immediately below, describes output of the various logging driver 0245 * flags and function calls. A list of valid flavor values, describing the type 0246 * of data stored, follows the table. 0247 * <table> 0248 * <caption>Table2: Logging Output</caption> 0249 * <tr> 0250 * <th>Flag</th><th>VFD Call</th><th>Output and Comments</th> 0251 * </th> 0252 * </tr> 0253 * <tr> 0254 * <td>#H5FD_LOG_LOC_READ</td> 0255 * <td>Read</td> 0256 * <td> 0257 * \TText{%10a-%10a (%10Zu bytes) (%s) Read}\n\n 0258 * Start position\n 0259 * End position\n 0260 * Number of bytes\n 0261 * Flavor of read\n\n 0262 * Adds \TText{(\%f s)} and seek time if #H5FD_LOG_TIME_SEEK is also set. 0263 * </td> 0264 * </tr> 0265 * <tr> 0266 * <td>#H5FD_LOG_LOC_READ</td> 0267 * <td>Read Error</td> 0268 * <td> 0269 * \TText{Error! Reading: %10a-%10a (%10Zu bytes)}\n\n 0270 * Same parameters as non-error entry. 0271 * </td> 0272 * </tr> 0273 * <tr> 0274 * <td>#H5FD_LOG_LOC_WRITE</td> 0275 * <td>Write</td> 0276 * <td> 0277 * \TText{%10a-%10a (%10Zu bytes) (%s) Written}\n\n 0278 * Start position\n 0279 * End position\n 0280 * Number of bytes\n 0281 * Flavor of write\n\n 0282 * Adds \TText{(\%f s)} and seek time if #H5FD_LOG_TIME_SEEK is also set. 0283 * </td> 0284 * </tr> 0285 * <tr> 0286 * <td>#H5FD_LOG_LOC_WRITE</td> 0287 * <td>Write Error</td> 0288 * <td> 0289 * \TText{Error! Writing: %10a-%10a (%10Zu bytes)}\n\n 0290 * Same parameters as non-error entry. 0291 * </td> 0292 * </tr> 0293 * <tr> 0294 * <td>#H5FD_LOG_LOC_SEEK</td> 0295 * <td>Read, Write</td> 0296 * <td> 0297 * \TText{Seek: From %10a-%10a}\n\n 0298 * Start position\n 0299 * End position\n\n 0300 * Adds \TText{(\%f s)} and seek time if #H5FD_LOG_TIME_SEEK is also set. 0301 * </td> 0302 * </tr> 0303 * <tr> 0304 * <td>#H5FD_LOG_FILE_READ</td> 0305 * <td>Close</td> 0306 * <td> 0307 * Begins with:\n 0308 * Dumping read I/O information\n\n 0309 * Then, for each range of identical values, there is this line:\n 0310 * \TText{Addr %10-%10 (%10lu bytes) read from %3d times}\n\n 0311 * Start address\n 0312 * End address\n 0313 * Number of bytes\n 0314 * Number of times read\n\n 0315 * Note: The data buffer is scanned and each range of identical values 0316 * gets one entry in the log file to save space and make it easier to read. 0317 * </td> 0318 * </tr> 0319 * <tr> 0320 * <td>#H5FD_LOG_FILE_WRITE</td> 0321 * <td>Close</td> 0322 * <td> 0323 * Begins with:\n 0324 * Dumping read I/O information\n\n 0325 * Then, for each range of identical values, there is this line:\n 0326 * \TText{Addr %10-%10 (%10lu bytes) written to %3d times}\n\n 0327 * Start address\n 0328 * End address\n 0329 * Number of bytes\n 0330 * Number of times written\n\n 0331 * Note: The data buffer is scanned and each range of identical values 0332 * gets one entry in the log file to save space and make it easier to read. 0333 * </td> 0334 * </tr> 0335 * <tr> 0336 * <td>#H5FD_LOG_FLAVOR</td> 0337 * <td>Close</td> 0338 * <td> 0339 * Begins with:\n 0340 * Dumping I/O flavor information\n\n 0341 * Then, for each range of identical values, there is this line:\n 0342 * \TText{Addr %10-%10 (%10lu bytes) flavor is %s}\n\n 0343 * Start address\n 0344 * End address\n 0345 * Number of bytes\n 0346 * Flavor\n\n 0347 * Note: The data buffer is scanned and each range of identical values 0348 * gets one entry in the log file to save space and make it easier to read. 0349 * </td> 0350 * </tr> 0351 * <tr> 0352 * <td>#H5FD_LOG_NUM_READ</td> 0353 * <td>Close</td> 0354 * <td> 0355 * Total number of read operations: \TText{%11u} 0356 * </td> 0357 * </tr> 0358 * <tr> 0359 * <td>#H5FD_LOG_NUM_WRITE</td> 0360 * <td>Close</td> 0361 * <td> 0362 * Total number of write operations: \TText{%11u} 0363 * </td> 0364 * </tr> 0365 * <tr> 0366 * <td>#H5FD_LOG_NUM_SEEK</td> 0367 * <td>Close</td> 0368 * <td> 0369 * Total number of seek operations: \TText{%11u} 0370 * </td> 0371 * </tr> 0372 * <tr> 0373 * <td>#H5FD_LOG_NUM_TRUNCATE</td> 0374 * <td>Close</td> 0375 * <td> 0376 * Total number of truncate operations: \TText{%11u} 0377 * </td> 0378 * </tr> 0379 * <tr> 0380 * <td>#H5FD_LOG_TIME_OPEN</td> 0381 * <td>Open</td> 0382 * <td> 0383 * Open took: \TText{(\%f s)} 0384 * </td> 0385 * </tr> 0386 * <tr> 0387 * <td>#H5FD_LOG_TIME_READ</td> 0388 * <td>Close, Read</td> 0389 * <td> 0390 * Total time in read operations: \TText{\%f s}\n\n 0391 * See also: #H5FD_LOG_LOC_READ 0392 * </td> 0393 * </tr> 0394 * </tr> 0395 * <tr> 0396 * <td>#H5FD_LOG_TIME_WRITE</td> 0397 * <td>Close, Write</td> 0398 * <td> 0399 * Total time in write operations: \TText{\%f s}\n\n 0400 * See also: #H5FD_LOG_LOC_WRITE 0401 * </td> 0402 * </tr> 0403 * <tr> 0404 * <td>#H5FD_LOG_TIME_SEEK</td> 0405 * <td>Close, Read, Write</td> 0406 * <td> 0407 * Total time in write operations: \TText{\%f s}\n\n 0408 * See also: #H5FD_LOG_LOC_SEEK or #H5FD_LOG_LOC_WRITE 0409 * </td> 0410 * </tr> 0411 * <tr> 0412 * <td>#H5FD_LOG_TIME_CLOSE</td> 0413 * <td>Close</td> 0414 * <td> 0415 * Close took: \TText{(\%f s)} 0416 * </td> 0417 * </tr> 0418 * <tr> 0419 * <td>#H5FD_LOG_TIME_STAT</td> 0420 * <td>Open</td> 0421 * <td> 0422 * Stat took: \TText{(\%f s)} 0423 * </td> 0424 * </tr> 0425 * <tr> 0426 * <td>#H5FD_LOG_ALLOC</td> 0427 * <td>Alloc</td> 0428 * <td> 0429 * \TText{%10-%10 (%10Hu bytes) (\%s) Allocated}\n\n 0430 * Start of address space\n 0431 * End of address space\n 0432 * Total size allocation\n 0433 * Flavor of allocation 0434 * </td> 0435 * </tr> 0436 * </table> 0437 * 0438 * \par Flavors: 0439 * The \Emph{flavor} describes the type of stored information. The following 0440 * table lists the flavors that appear in log output and briefly describes each. 0441 * These terms are provided here to aid in the construction of log message 0442 * parsers; a full description is beyond the scope of this document. 0443 * <table> 0444 * <caption>Table3: Flavors of logged data</caption> 0445 * <tr> 0446 * <th>Flavor</th><th>Description</th> 0447 * </th> 0448 * </tr> 0449 * <tr> 0450 * <td>#H5FD_MEM_NOLIST</td> 0451 * <td>Error value</td> 0452 * </tr> 0453 * <tr> 0454 * <td>#H5FD_MEM_DEFAULT</td> 0455 * <td>Value not yet set.\n 0456 * May also be a datatype set in a larger allocation that will be 0457 * suballocated by the library.</td> 0458 * </tr> 0459 * <tr> 0460 * <td>#H5FD_MEM_SUPER</td> 0461 * <td>Superblock data</td> 0462 * </tr> 0463 * <tr> 0464 * <td>#H5FD_MEM_BTREE</td> 0465 * <td>B-tree data</td> 0466 * </tr> 0467 * <tr> 0468 * <td>#H5FD_MEM_DRAW</td> 0469 * <td>Raw data (for example, contents of a dataset)</td> 0470 * </tr> 0471 * <tr> 0472 * <td>#H5FD_MEM_GHEAP</td> 0473 * <td>Global heap data</td> 0474 * </tr> 0475 * <tr> 0476 * <td>#H5FD_MEM_LHEAP</td> 0477 * <td>Local heap data</td> 0478 * </tr> 0479 * <tr> 0480 * <td>#H5FD_MEM_OHDR</td> 0481 * <td>Object header data</td> 0482 * </tr> 0483 * </table> 0484 * 0485 * \version 1.8.7 The flags parameter has been changed from \TText{unsigned int} 0486 * to \TText{unsigned long long}. 0487 * The implementation of the #H5FD_LOG_TIME_OPEN, #H5FD_LOG_TIME_READ, 0488 * #H5FD_LOG_TIME_WRITE, and #H5FD_LOG_TIME_SEEK flags has been finished. 0489 * New flags were added: #H5FD_LOG_NUM_TRUNCATE and #H5FD_LOG_TIME_STAT. 0490 * \version 1.6.0 The \c verbosity parameter has been removed. 0491 * Two new parameters have been added: \p flags of type \TText{unsigned} and 0492 * \p buf_size of type \TText{size_t}. 0493 * \since 1.4.0 0494 * 0495 */ 0496 H5_DLL herr_t H5Pset_fapl_log(hid_t fapl_id, const char *logfile, unsigned long long flags, size_t buf_size); 0497 0498 #ifdef __cplusplus 0499 } 0500 #endif 0501 0502 #endif
| [ Source navigation ] | [ Diff markup ] | [ Identifier search ] | [ general search ] |
|
This page was automatically generated by the 2.3.7 LXR engine. The LXR team |
|