#include <db_cxx.h>

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

Description

The DbEnv::memp_stat and DbEnv::memp_fstat methods return the memory pool subsystem statistics.

The flags value must be set to 0 or the following value:

DB_STAT_CLEAR

Reset statistics after returning their values.

The DbEnv::memp_stat and DbEnv::memp_fstat methods create statistical structures of type DB_MPOOL_STAT and DB_MPOOL_FSTAT, and copy pointers to them into user-specified memory locations. The memory pool region statistics are stored in the DB_MPOOL_STAT structure and the per-file memory pool statistics are stored the DB_MPOOL_FSTAT structure.

Statistical structures are created 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 library malloc(3) interface 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 memory pool mp are copied into the memory location to which it refers. The following DB_MPOOL_STAT fields will be filled in:

size_t st_gbytes;

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

size_t st_bytes;

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

u_int32_t st_ncache;

Number of caches.

u_int32_t st_regsize;

Individual cache size.

u_int32_t st_map;

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).

u_int32_t st_cache_hit;

Requested pages found in the cache.

u_int32_t st_cache_miss;

Requested pages not found in the cache.

u_int32_t st_page_create;

Pages created in the cache.

u_int32_t st_page_in;

Pages read into the cache.

u_int32_t st_page_out;

Pages written from the cache to the backing file.

u_int32_t st_ro_evict;

Clean pages forced from the cache.

u_int32_t st_rw_evict;

Dirty pages forced from the cache.

u_int32_t st_page_trickle;

Dirty pages written using the DbEnv::memp_trickle interface.

u_int32_t st_pages;

Pages in the cache.

u_int32_t st_page_clean;

Clean pages currently in the cache.

u_int32_t st_page_dirty;

Dirty pages currently in the cache.

u_int32_t st_hash_buckets;

Number of hash buckets in buffer hash table.

u_int32_t st_hash_searches;

Total number of buffer hash table lookups.

u_int32_t st_hash_longest;

The longest chain ever encountered in buffer hash table lookups.

u_int32_t st_hash_examined;

Total number of hash elements traversed during hash table lookups.

u_int32_t st_hash_nowait;

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

u_int32_t st_hash_wait;

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

u_int32_t st_hash_max_wait;

The maximum number of times any hash bucket lock was waited for by a thread of control.

u_int32_t st_region_wait;

The number of times that a thread of control was forced to wait before obtaining a region lock.

u_int32_t st_region_nowait;

The number of times that a thread of control was able to obtain a region lock without waiting.

u_int32_t st_alloc;

Number of page allocations.

u_int32_t st_alloc_buckets;

Number of hash buckets checked during allocation.

u_int32_t st_alloc_max_buckets;

Maximum number of hash buckets checked during an allocation.

u_int32_t st_alloc_pages;

Number of pages checked during allocation.

u_int32_t st_alloc_max_pages;

Maximum number of pages checked during an allocation.

If fsp is non-NULL, a pointer to a NULL-terminated variable length array of statistics for individual files, in the memory pool mp, is copied into the memory location to which it refers. If no individual files currently exist in the memory pool, 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 pool; that is, each element of the array:

char *file_name;

The name of the file.

size_t st_pagesize;

Page size in bytes.

u_int32_t st_cache_hit;

Requested pages found in the cache.

u_int32_t st_cache_miss;

Requested pages not found in the cache.

u_int32_t st_map;

Requested pages mapped into the process' address space.

u_int32_t st_page_create;

Pages created in the cache.

u_int32_t st_page_in;

Pages read into the cache.

u_int32_t st_page_out;

Pages written from the cache to the backing file.

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.

Errors

The DbEnv::memp_stat method may fail and throw an exception or return a non-zero error for the following conditions:

EINVAL

An invalid flag value or parameter was specified.

The DbEnv::memp_stat method may fail and throw an exception or return a non-zero error for errors specified for other Berkeley DB and C library or system methods. If a catastrophic error has occurred, the DbEnv::memp_stat method may fail and either return DB_RUNRECOVERY or throw a DbRunRecoveryException, in which case all subsequent Berkeley DB calls will fail in the same way.

Class

See Also