1<?xml version="1.0" encoding="UTF-8" standalone="no"?> 2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 3<html xmlns="http://www.w3.org/1999/xhtml"> 4 <head> 5 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> 6 <title>DbEnv::memp_stat()</title> 7 <link rel="stylesheet" href="apiReference.css" type="text/css" /> 8 <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /> 9 <link rel="start" href="index.html" title="Berkeley DB C++ API Reference" /> 10 <link rel="up" href="memp.html" title="Chapter 9. The DbMpoolFile Handle" /> 11 <link rel="prev" href="mempregister.html" title="DbEnv::memp_register()" /> 12 <link rel="next" href="mempstat_print.html" title="DbEnv::memp_stat_print()" /> 13 </head> 14 <body> 15 <div class="navheader"> 16 <table width="100%" summary="Navigation header"> 17 <tr> 18 <th colspan="3" align="center">DbEnv::memp_stat()</th> 19 </tr> 20 <tr> 21 <td width="20%" align="left"><a accesskey="p" href="mempregister.html">Prev</a> </td> 22 <th width="60%" align="center">Chapter 9. 23 The DbMpoolFile Handle 24 </th> 25 <td width="20%" align="right"> <a accesskey="n" href="mempstat_print.html">Next</a></td> 26 </tr> 27 </table> 28 <hr /> 29 </div> 30 <div class="sect1" lang="en" xml:lang="en"> 31 <div class="titlepage"> 32 <div> 33 <div> 34 <h2 class="title" style="clear: both"><a id="mempstat"></a>DbEnv::memp_stat()</h2> 35 </div> 36 </div> 37 </div> 38 <pre class="programlisting">#include <db_cxx.h> 39 40int 41DbEnv::memp_stat(DB_MPOOL_STAT **gsp, 42 DB_MPOOL_FSTAT *(*fsp)[], u_int32_t flags); </pre> 43 <p> 44 The <code class="methodname">DbEnv::memp_stat()</code> method returns the memory pool (that is, the 45 buffer cache) subsystem statistics. 46 </p> 47 <p> 48 The <code class="methodname">DbEnv::memp_stat()</code> method creates statistical structures of 49 type <code class="literal">DB_MPOOL_STAT</code> and <code class="literal">DB_MPOOL_FSTAT</code>, and copy 50 pointers to them into user-specified memory locations. The cache statistics are stored in 51 the <code class="literal">DB_MPOOL_STAT</code> structure and the per-file cache statistics are stored 52 the <code class="literal">DB_MPOOL_FSTAT</code> structure. 53 </p> 54 <p> 55 Statistical structures are stored in allocated memory. If 56 application-specific allocation routines have been declared (see 57 <a class="xref" href="envset_alloc.html" title="DbEnv::set_alloc()">DbEnv::set_alloc()</a> 58 for more information), they are used to allocate the memory; 59 otherwise, the standard C library <span class="bold"><strong>malloc</strong></span>(3) is used. The caller is responsible 60 for deallocating the memory. To deallocate the memory, free the 61 memory reference; references inside the returned memory need not be 62 individually freed. 63 </p> 64 <p> 65 If <span class="bold"><strong>gsp</strong></span> is non-NULL, the global 66 statistics for the cache <span class="bold"><strong>mp</strong></span> are 67 copied into the memory location to which it refers. The following 68 <code class="literal">DB_MPOOL_STAT</code> fields will be filled in: 69 </p> 70 <div class="itemizedlist"> 71 <ul type="disc"> 72 <li> 73 <p> 74 <span class="bold"><strong>u_int32_t st_gbytes;</strong></span> 75 </p> 76 <p> 77 Gigabytes of cache (total cache size is st_gbytes + st_bytes). 78 </p> 79 </li> 80 <li> 81 <p> 82 <span class="bold"><strong>u_int32_t st_bytes;</strong></span> 83 </p> 84 <p> 85 Bytes of cache (total cache size is st_gbytes + st_bytes). 86 </p> 87 </li> 88 <li> 89 <p> 90 <span class="bold"><strong>u_int32_t st_ncache;</strong></span> 91 </p> 92 <p> 93 Number of caches. 94 </p> 95 </li> 96 <li> 97 <p> 98 <span class="bold"><strong>u_int32_t st_max_ncache;</strong></span> 99 </p> 100 <p> 101 Maximum number of caches, as configured with the 102 <a class="xref" href="envset_cache_max.html" title="DbEnv::set_cache_max()">DbEnv::set_cache_max()</a> 103 method. 104 </p> 105 </li> 106 <li> 107 <p> 108 <span class="bold"><strong>roff_t st_regsize;</strong></span> 109 </p> 110 <p> 111 Individual cache size, in bytes. 112 </p> 113 </li> 114 <li> 115 <p> 116 <span class="bold"><strong>size_t st_mmapsize;</strong></span> 117 </p> 118 <p> 119 Maximum memory-mapped file size. 120 </p> 121 </li> 122 <li> 123 <p> 124 <span class="bold"><strong>int st_maxopenfd;</strong></span> 125 </p> 126 <p> 127 Maximum open file descriptors. 128 </p> 129 </li> 130 <li> 131 <p> 132 <span class="bold"><strong>int st_maxwrite;</strong></span> 133 </p> 134 <p> 135 Maximum sequential buffer writes. 136 </p> 137 </li> 138 <li> 139 <p> 140 <span class="bold"><strong>db_timeout_t st_maxwrite_sleep;</strong></span> 141 </p> 142 <p> 143 Microseconds to pause after writing maximum sequential buffers. 144 </p> 145 </li> 146 <li> 147 <p> 148 <span class="bold"><strong>u_int32_t st_map;</strong></span> 149 </p> 150 <p> 151 Requested pages mapped into the process' address space (there is no 152 available information about whether or not this request caused disk 153 I/O, although examining the application page fault rate may be 154 helpful). 155 </p> 156 </li> 157 <li> 158 <p> 159 <span class="bold"><strong>uintmax_t st_cache_hit;</strong></span> 160 </p> 161 <p> 162 Requested pages found in the cache. 163 </p> 164 </li> 165 <li> 166 <p> 167 <span class="bold"><strong>uintmax_t st_cache_miss;</strong></span> 168 </p> 169 <p> 170 Requested pages not found in the cache. 171 </p> 172 </li> 173 <li> 174 <p> 175 <span class="bold"><strong>uintmax_t st_page_create;</strong></span> 176 </p> 177 <p> 178 Pages created in the cache. 179 </p> 180 </li> 181 <li> 182 <p> 183 <span class="bold"><strong>uintmax_t st_page_in;</strong></span> 184 </p> 185 <p> 186 Pages read into the cache. 187 </p> 188 </li> 189 <li> 190 <p> 191 <span class="bold"><strong>uintmax_t st_page_out;</strong></span> 192 </p> 193 <p> 194 Pages written from the cache to the backing file. 195 </p> 196 </li> 197 <li> 198 <p> 199 <span class="bold"><strong>uintmax_t st_ro_evict;</strong></span> 200 </p> 201 <p> 202 Clean pages forced from the cache. 203 </p> 204 </li> 205 <li> 206 <p> 207 <span class="bold"><strong>uintmax_t st_rw_evict;</strong></span> 208 </p> 209 <p> 210 Dirty pages forced from the cache. 211 </p> 212 </li> 213 <li> 214 <p> 215 <span class="bold"><strong>uintmax_t st_page_trickle;</strong></span> 216 </p> 217 <p> 218 Dirty pages written using the 219 <a class="xref" href="memptrickle.html" title="DbEnv::memp_trickle()">DbEnv::memp_trickle()</a> 220 method. 221 </p> 222 </li> 223 <li> 224 <p> 225 <span class="bold"><strong>u_int32_t st_pages;</strong></span> 226 </p> 227 <p> 228 Pages in the cache. 229 </p> 230 </li> 231 <li> 232 <p> 233 <span class="bold"><strong>uintmax_t st_page_clean;</strong></span> 234 </p> 235 <p> 236 Clean pages currently in the cache. 237 </p> 238 </li> 239 <li> 240 <p> 241 <span class="bold"><strong>uintmax_t st_page_dirty;</strong></span> 242 </p> 243 <p> 244 Dirty pages currently in the cache. 245 </p> 246 </li> 247 <li> 248 <p> 249 <span class="bold"><strong>uintmax_t st_hash_buckets;</strong></span> 250 </p> 251 <p> 252 Number of hash buckets in buffer hash table. 253 </p> 254 </li> 255 <li> 256 <p> 257 <span class="bold"><strong>uintmax_t st_hash_searches;</strong></span> 258 </p> 259 <p> 260 Total number of buffer hash table lookups. 261 </p> 262 </li> 263 <li> 264 <p> 265 <span class="bold"><strong>uintmax_t st_hash_longest;</strong></span> 266 </p> 267 <p> 268 Longest chain ever encountered in buffer hash table lookups. 269 </p> 270 </li> 271 <li> 272 <p> 273 <span class="bold"><strong>uintmax_t st_hash_examined;</strong></span> 274 </p> 275 <p> 276 Total number of hash elements traversed during hash table lookups. 277 </p> 278 </li> 279 <li> 280 <p> 281 <span class="bold"><strong>uintmax_t st_hash_nowait;</strong></span> 282 </p> 283 <p> 284 Number of times that a thread of control was able to obtain a hash 285 bucket lock without waiting. 286 </p> 287 </li> 288 <li> 289 <p> 290 <span class="bold"><strong>uintmax_t st_hash_wait;</strong></span> 291 </p> 292 <p> 293 Number of times that a thread of control was forced to wait before 294 obtaining a hash bucket lock. 295 </p> 296 </li> 297 <li> 298 <p> 299 <span class="bold"><strong>uintmax_t st_hash_max_nowait;</strong></span> 300 </p> 301 <p> 302 The number of times a thread of control was able to obtain the hash 303 bucket lock without waiting on the bucket which had the maximum number 304 of times that a thread of control needed to wait. 305 </p> 306 </li> 307 <li> 308 <p> 309 <span class="bold"><strong>uintmax_t st_hash_max_wait;</strong></span> 310 </p> 311 <p> 312 Maximum number of times any hash bucket lock was waited for by a 313 thread of control. 314 </p> 315 </li> 316 <li> 317 <p> 318 <span class="bold"><strong>uintmax_t st_region_wait;</strong></span> 319 </p> 320 <p> 321 Number of times that a thread of control was forced to wait before 322 obtaining a cache region mutex. 323 </p> 324 </li> 325 <li> 326 <p> 327 <span class="bold"><strong>uintmax_t st_region_nowait;</strong></span> 328 </p> 329 <p> 330 Number of times that a thread of control was able to obtain a cache 331 region mutex without waiting. 332 </p> 333 </li> 334 <li> 335 <p> 336 <span class="bold"><strong>uintmax_t st_mvcc_frozen;</strong></span> 337 </p> 338 <p> 339 Number of buffers frozen. 340 </p> 341 </li> 342 <li> 343 <p> 344 <span class="bold"><strong>uintmax_t st_mvcc_thawed;</strong></span> 345 </p> 346 <p> 347 Number of buffers thawed. 348 </p> 349 </li> 350 <li> 351 <p> 352 <span class="bold"><strong>uintmax_t st_mvcc_freed;</strong></span> 353 </p> 354 <p> 355 Number of frozen buffers freed. 356 </p> 357 </li> 358 <li> 359 <p> 360 <span class="bold"><strong>uintmax_t st_alloc;</strong></span> 361 </p> 362 <p> 363 Number of page allocations. 364 </p> 365 </li> 366 <li> 367 <p> 368 <span class="bold"><strong>uintmax_t st_alloc_buckets;</strong></span> 369 </p> 370 <p> 371 Number of hash buckets checked during allocation. 372 </p> 373 </li> 374 <li> 375 <p> 376 <span class="bold"><strong>uintmax_t st_alloc_max_buckets;</strong></span> 377 </p> 378 <p> 379 Maximum number of hash buckets checked during an allocation. 380 </p> 381 </li> 382 <li> 383 <p> 384 <span class="bold"><strong>uintmax_t st_alloc_pages;</strong></span> 385 </p> 386 <p> 387 Number of pages checked during allocation. 388 </p> 389 </li> 390 <li> 391 <p> 392 <span class="bold"><strong>uintmax_t st_alloc_max_pages;</strong></span> 393 </p> 394 <p> 395 Maximum number of pages checked during an allocation. 396 </p> 397 </li> 398 <li> 399 <p> 400 <span class="bold"><strong>uintmax_t st_io_wait;</strong></span> 401 </p> 402 <p> 403 Number of operations blocked waiting for I/O to complete. 404 </p> 405 </li> 406 <li> 407 <p> 408 <span class="bold"><strong>uintmax_t st_sync_interrupted;</strong></span> 409 </p> 410 <p> 411 Number of mpool sync operations interrupted. 412 </p> 413 </li> 414 </ul> 415 </div> 416 <p> 417 If <span class="bold"><strong>fsp</strong></span> is non-NULL, a pointer to a 418 NULL-terminated variable length array of statistics for individual 419 files, in the cache <span class="bold"><strong>mp</strong></span>, is copied 420 into the memory location to which it refers. If no individual files 421 currently exist in the cache, <span class="bold"><strong>fsp</strong></span> 422 will be set to NULL. 423 </p> 424 <p> 425 The per-file statistics are stored in structures of type <code class="literal">DB_MPOOL_FSTAT</code>. 426 The following <code class="literal">DB_MPOOL_FSTAT</code> fields will be filled in for each file in 427 the cache; that is, each element of the array: 428 </p> 429 <div class="itemizedlist"> 430 <ul type="disc"> 431 <li> 432 <p> 433 <span class="bold"><strong>char * file_name;</strong></span> 434 </p> 435 <p> 436 The name of the file. 437 </p> 438 </li> 439 <li> 440 <p> 441 <span class="bold"><strong>size_t st_pagesize;</strong></span> 442 </p> 443 <p> 444 Page size in bytes. 445 </p> 446 </li> 447 <li> 448 <p> 449 <span class="bold"><strong>uintmax_t st_cache_hit;</strong></span> 450 </p> 451 <p> 452 Requested pages found in the cache. 453 </p> 454 </li> 455 <li> 456 <p> 457 <span class="bold"><strong>uintmax_t st_cache_miss;</strong></span> 458 </p> 459 <p> 460 Requested pages not found in the cache. 461 </p> 462 </li> 463 <li> 464 <p> 465 <span class="bold"><strong>u_int32_t st_map;</strong></span> 466 </p> 467 <p> 468 Requested pages mapped into the process' address space. 469 </p> 470 </li> 471 <li> 472 <p> 473 <span class="bold"><strong>uintmax_t st_page_create;</strong></span> 474 </p> 475 <p> 476 Pages created in the cache. 477 </p> 478 </li> 479 <li> 480 <p> 481 <span class="bold"><strong>uintmax_t st_page_in;</strong></span> 482 </p> 483 <p> 484 Pages read into the cache. 485 </p> 486 </li> 487 <li> 488 <p> 489 <span class="bold"><strong>uintmax_t st_page_out;</strong></span> 490 </p> 491 <p> 492 Pages written from the cache to the backing file. 493 </p> 494 </li> 495 </ul> 496 </div> 497 <p> 498 The <code class="methodname">DbEnv::memp_stat()</code> method may not be called before the 499 <a class="xref" href="envopen.html" title="DbEnv::open()">DbEnv::open()</a> method is called. 500 </p> 501 <p> 502 The <code class="methodname">DbEnv::memp_stat()</code> <span> 503 504 <span> 505 method either returns a non-zero error value or throws an 506 exception that encapsulates a non-zero error value on 507 failure, and returns 0 on success. 508 </span> 509 </span> 510 </p> 511 <div class="sect2" lang="en" xml:lang="en"> 512 <div class="titlepage"> 513 <div> 514 <div> 515 <h3 class="title"><a id="id1691319"></a>Parameters</h3> 516 </div> 517 </div> 518 </div> 519 <div class="sect3" lang="en" xml:lang="en"> 520 <div class="titlepage"> 521 <div> 522 <div> 523 <h4 class="title"><a id="id1691740"></a>flags</h4> 524 </div> 525 </div> 526 </div> 527 <p> 528 The <span class="bold"><strong>flags</strong></span> parameter must be set to 0 529 or the following value: 530 </p> 531 <div class="itemizedlist"> 532 <ul type="disc"> 533 <li> 534 <p><a id="stat_DB_STAT_CLEAR"></a> 535 <code class="literal">DB_STAT_CLEAR</code> 536 </p> 537 <p> 538 Reset statistics after returning their values. 539 </p> 540 </li> 541 </ul> 542 </div> 543 </div> 544 <div class="sect3" lang="en" xml:lang="en"> 545 <div class="titlepage"> 546 <div> 547 <div> 548 <h4 class="title"><a id="id1691839"></a>fsp</h4> 549 </div> 550 </div> 551 </div> 552 <p> 553 The <span class="bold"><strong>fsp</strong></span> parameter references memory 554 into which a pointer to the allocated per-file statistics structures 555 is copied. 556 </p> 557 </div> 558 <div class="sect3" lang="en" xml:lang="en"> 559 <div class="titlepage"> 560 <div> 561 <div> 562 <h4 class="title"><a id="id1691108"></a>gsp</h4> 563 </div> 564 </div> 565 </div> 566 <p> 567 The <span class="bold"><strong>gsp</strong></span> parameter references memory 568 into which a pointer to the allocated global statistics structure is 569 copied. 570 </p> 571 </div> 572 </div> 573 <div class="sect2" lang="en" xml:lang="en"> 574 <div class="titlepage"> 575 <div> 576 <div> 577 <h3 class="title"><a id="id1691960"></a>Errors</h3> 578 </div> 579 </div> 580 </div> 581 <p> 582 The <code class="methodname">DbEnv::memp_stat()</code> <span> 583 584 <span> 585 method may fail and throw a <a class="link" href="dbexception.html" title="Chapter 6. The DbException Class">DbException</a> 586 exception, encapsulating one of the following non-zero errors, or return one 587 of the following non-zero errors: 588 </span> 589 </span> 590 </p> 591 <div class="sect3" lang="en" xml:lang="en"> 592 <div class="titlepage"> 593 <div> 594 <div> 595 <h4 class="title"><a id="id1692010"></a>EINVAL</h4> 596 </div> 597 </div> 598 </div> 599 <p> 600 An invalid flag value or parameter was specified. 601 </p> 602 </div> 603 </div> 604 <div class="sect2" lang="en" xml:lang="en"> 605 <div class="titlepage"> 606 <div> 607 <div> 608 <h3 class="title"><a id="id1691634"></a>Class</h3> 609 </div> 610 </div> 611 </div> 612 <p> 613 <a class="link" href="env.html" title="Chapter 5. The DbEnv Handle">DbEnv</a>, <a class="link" href="memp.html" title="Chapter 9. The DbMpoolFile Handle">DbMpoolFile</a> 614 </p> 615 </div> 616 <div class="sect2" lang="en" xml:lang="en"> 617 <div class="titlepage"> 618 <div> 619 <div> 620 <h3 class="title"><a id="id1691690"></a>See Also</h3> 621 </div> 622 </div> 623 </div> 624 <p> 625 <a class="xref" href="memp.html#memplist" title="Memory Pools and Related Methods">Memory Pools and Related Methods</a> 626 </p> 627 </div> 628 </div> 629 <div class="navfooter"> 630 <hr /> 631 <table width="100%" summary="Navigation footer"> 632 <tr> 633 <td width="40%" align="left"><a accesskey="p" href="mempregister.html">Prev</a> </td> 634 <td width="20%" align="center"> 635 <a accesskey="u" href="memp.html">Up</a> 636 </td> 637 <td width="40%" align="right"> <a accesskey="n" href="mempstat_print.html">Next</a></td> 638 </tr> 639 <tr> 640 <td width="40%" align="left" valign="top">DbEnv::memp_register() </td> 641 <td width="20%" align="center"> 642 <a accesskey="h" href="index.html">Home</a> 643 </td> 644 <td width="40%" align="right" valign="top"> DbEnv::memp_stat_print()</td> 645 </tr> 646 </table> 647 </div> 648 </body> 649</html> 650