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