#include <db_cxx.h>

int
DbEnv::memp_stat(DB_MPOOL_STAT **gsp,
    DB_MPOOL_FSTAT *(*fsp)[], u_int32_t flags);

int
DbEnv::memp_stat_print(u_int32_t flags);

The DbEnv::memp_stat method returns the memory pool (that is, the buffer cache) subsystem statistics.

The DbEnv::memp_stat method creates statistical structures of type DB_MPOOL_STAT and DB_MPOOL_FSTAT, and copy pointers to them into user-specified memory locations. The cache statistics are stored in the DB_MPOOL_STAT structure and the per-file cache statistics are stored the DB_MPOOL_FSTAT structure.

Statistical structures are stored in allocated memory. If application-specific allocation routines have been declared (see DbEnv::set_alloc for more information), they are used to allocate the memory; otherwise, the standard C library malloc(3) is used. The caller is responsible for deallocating the memory. To deallocate the memory, free the memory reference; references inside the returned memory need not be individually freed.

If gsp is non-NULL, the global statistics for the cache mp are copied into the memory location to which it refers. The following DB_MPOOL_STAT fields will be filled in:

• Gigabytes of cache (total cache size is st_gbytes + st_bytes).

• Bytes of cache (total cache size is st_gbytes + st_bytes).

• Number of caches.

• Maximum number of caches, as configured with the DbEnv::set_cache_max method.

• Individual cache size, in bytes.

• Maximum memory-mapped file size.

• Maximum open file descriptors.

• Maximum sequential buffer writes.

• Microseconds to pause after writing maximum sequential buffers.

• Requested pages mapped into the process' address space (there is no available information about whether or not this request caused disk I/O, although examining the application page fault rate may be helpful).

• Requested pages found in the cache.

• Requested pages not found in the cache.

• Pages created in the cache.

• Pages read into the cache.

• Pages written from the cache to the backing file.

• Clean pages forced from the cache.

• Dirty pages forced from the cache.

• Dirty pages written using the DbEnv::memp_trickle method.

• Pages in the cache.

• Clean pages currently in the cache.

• Dirty pages currently in the cache.

• Number of hash buckets in buffer hash table.

• Total number of buffer hash table lookups.

• Longest chain ever encountered in buffer hash table lookups.

• Total number of hash elements traversed during hash table lookups.

• Number of times that a thread of control was able to obtain a hash bucket lock without waiting.

• Number of times that a thread of control was forced to wait before obtaining a hash bucket lock.

• The number of times a thread of control was able to obtain the hash bucket lock without waiting on the bucket which had the maximum number of times that a thread of control needed to wait.

• Maximum number of times any hash bucket lock was waited for by a thread of control.

• Number of times that a thread of control was forced to wait before obtaining a cache region mutex.

• Number of times that a thread of control was able to obtain a cache region mutex without waiting.

• Number of buffers frozen.

• Number of buffers thawed.

• Number of frozen buffers freed.

• Number of page allocations.

• Number of hash buckets checked during allocation.

• Maximum number of hash buckets checked during an allocation.

• Number of pages checked during allocation.

• Maximum number of pages checked during an allocation.

• Number of operations blocked waiting for I/O to complete.

If fsp is non-NULL, a pointer to a NULL-terminated variable length array of statistics for individual files, in the cache mp, is copied into the memory location to which it refers. If no individual files currently exist in the cache, fsp will be set to NULL.

The per-file statistics are stored in structures of type DB_MPOOL_FSTAT. The following DB_MPOOL_FSTAT fields will be filled in for each file in the cache; that is, each element of the array:

• The name of the file.

• Page size in bytes.

• Requested pages found in the cache.

• Requested pages not found in the cache.

• Requested pages mapped into the process' address space.

• Pages created in the cache.

• Pages read into the cache.

• Pages written from the cache to the backing file.

The DbEnv::memp_stat method may not be called before the DbEnv::open method is called.

The DbEnv::memp_stat method either returns a non-zero error value or throws an exception that encapsulates a non-zero error value on failure, and returns 0 on success.

• The flags parameter must be set to 0 or the following value:
  DB_STAT_CLEAR
  • Reset statistics after returning their values.
  
  

• The fsp parameter references memory into which a pointer to the allocated per-file statistics structures is copied.

• The gsp parameter references memory into which a pointer to the allocated global statistics structure is copied.

The DbEnv::memp_stat method may fail and throw DbException, encapsulating one of the following non-zero errors, or return one of the following non-zero errors:

• An invalid flag value or parameter was specified.

The DbEnv::memp_stat_print method displays the memory pool subsystem statistical information, as described for the DbEnv::memp_stat method. The information is printed to a specified output channel (see the DbEnv::set_msgfile method for more information), or passed to an application callback function (see the DbEnv::set_msgcall method for more information).

The DbEnv::memp_stat_print method may not be called before the DbEnv::open method is called.

The DbEnv::memp_stat_print method either returns a non-zero error value or throws an exception that encapsulates a non-zero error value on failure, and returns 0 on success.

• The flags parameter must be set to 0 or by bitwise inclusively OR'ing together one or more of the following values:
  DB_STAT_ALL
  • Display all available information.
  DB_STAT_CLEAR
  • Reset statistics after displaying their values.
  DB_STAT_MEMP_HASH
  • Display the buffers with hash chains.