Berkeley DB: DbMpool::stat
Description: Berkeley DB: An embedded database programmatic toolkit.
Keywords: embedded,database,programmatic,toolkit,b+tree,btr ee,hash,hashing,transaction,transactions,locking,logging,access method,access me thods,java,C,C++

# DbMpool::stat

`

###

    #include <db_cxx.h>

    int
    DbMpool::stat(DB_MPOOL_STAT **gsp,
        DB_MPOOL_FSTAT *(*fsp)[], void *(*db_malloc)(size_t));

# Description

The DbMpool::stat method method creates statistical structures and copies pointers to them into user-specified memory locations. The statistics include the number of files participating in the pool, the active pages in the pool, and information as to how effective the cache has been.

Statistical structures are created in allocated memory. If db_malloc is non-NULL, it is called to allocate the memory, otherwise, the library function malloc(3)) is used. The function db_malloc must match the calling conventions of the malloc(3)) library routine. Regardless, the caller is responsible for deallocating the returned memory. To deallocate the returned memory, free each returned memory pointer; pointers inside the memory do not need to be individually freed.

If gsp is non-NULL, the global statistics for the memory pool mp are copied into the memory location it references. The global statistics are stored in a structure of type DB_MPOOL_STAT.

The following DB_MPOOL_STAT fields will be filled in:

u_int32_t st_refcnt;
  The number of references to the region.
u_int32_t st_regsize;
  The size of the region.
size_t st_cachesize;
  Cache 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 (there is no available information as to whether or not this request caused disk I/O, although examining the application page fault rate may be helpful).
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_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_page_clean;
  Clean pages currently in the cache.
u_int32_t st_page_dirty;
  Dirty pages currently in the cache.
u_int32_t st_page_trickle;
  Dirty pages written using the DbMpool::trickle interface.
u_int32_t st_region_wait;
  The number of times that a thread of control was forced to wait before obtaining the region lock.
u_int32_t st_region_nowait;
  The number of times that a thread of control was able to obtain the region lock without waiting.

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 it references. 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, i.e., 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 DbMpool::stat method either returns errno or throws an exception that encapsulates an errno on failure, and 0 on success.

# Errors

If a fatal error occurs in Berkeley DB, the DbMpool::stat method may fail and either return DB_RUNRECOVERY or throw an exception encapsulating DB_RUNRECOVERY, at which point all subsequent database calls will also fail in the same way. Methods marked as returning errno will, by default, throw an exception that encapsulates the error information. The default error behavior can be changed, see DbException.

The DbMpool::stat method may fail and throw an exception for any of the errors specified for the following Berkeley DB and C library functions: abort(3), fcntl(3), fprintf(3), getpid(3), malloc(3), memcpy(3), memset(3), and strlen(3). In addition, the DbMpool::stat method may fail and throw an exception or return errno for the following conditions:

EINVAL
  An invalid flag value or parameter was specified.

# Class

DbMpool

# See Also

DbMpool::close, DbMpool::open, DbMpool::db_register, DbMpool::stat, DbMpool::sync, DbMpool::trickle and DbMpool::unlink.`