DbMpool



NAME

       DbMpool - shared memory buffer pool


SYNOPSIS

       #include <db_cxx.h>

       static int
       DbMpool::open(char *dir,
            int flags, int mode, DbEnv *dbenv, DbMpool **regionp);

       int
       DbMpool::close();

       static int
       DbMpool::unlink(const char *dir, int force, DbEnv *);

       int
       DbMpool::db_register(int ftype,
            int (*pgin)(db_pgno_t pgno, void *pgaddr, Dbt *pgcookie),
            int (*pgout)(db_pgno_t pgno, void *pgaddr, Dbt *pgcookie));

       int
       DbMpool::trickle(int pct, int *nwrotep);

       int
       DbMpool::sync(LSN *lsn);

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


DESCRIPTION

       The DB library is a family of classes that provides a mod-
       ular programming interface to transactions and record-ori-
       ented  file  access.   The  library  includes  support for
       transactions, locking, logging and file page  caching,  as
       well  as  various  indexed  access  methods.   Many of the
       classes (e.g., the file page  caching  class)  are  useful
       independent of the other DB classes, although some classes
       are explicitly based on other classes (e.g.,  transactions
       and  logging).   For a general description of the DB pack-
       age, see db_intro(3).

       This manual page describes the  specific  details  of  the
       memory pool interface.

       The  DbMpool(3) and DbMpoolFile(3) classes are the library
       interface intended to provide  general-purpose,  page-ori-
       ented  buffer  management  of  one  or  more files.  While
       designed to work with the other Db functions, these  func-
       tions are also useful for more general purposes.  The mem-
       ory pools (DbMpool's) are referred to in this document  as
       simply  ``pools''.  Pools may be shared between processes.
       Pools are usually filled by pages from one or  more  files

       If  the  dbenv  argument  to DbMpool::open was initialized
       using DbEnv::appinit, dir is interpreted as  described  by
       DbEnv(3).

       Otherwise,  if dir is not NULL, it is interpreted relative
       to the current working directory of the process.   If  dir
       is  NULL,  the following environment variables are checked
       in order: ``TMPDIR'', ``TEMP'', and ``TMP''.   If  one  of
       them is set, memory pool files are created relative to the
       directory it specifies.  If none  of  them  are  set,  the
       first  possible  one of the following directories is used:
       /var/tmp, /usr/tmp, /temp, /tmp, C:/temp and C:/tmp.

       All files associated with the memory pool are  created  in
       this directory.  This directory must already exist when is
       called.  If the memory pool already  exists,  the  process
       must have permission to read and write the existing files.
       If the memory pool does not already exist, it  is  option-
       ally created and initialized.

       The  flags  and  mode  arguments specify how files will be
       opened and/or created when they don't already exist.   The
       flags value is specified by or'ing together one or more of
       the following values:

       DB_CREATE
            Create any underlying files, as  necessary.   If  the
            files  do not already exist and the DB_CREATE flag is
            not specified, the call will fail.

       DB_MPOOL_PRIVATE
            Create a private MPOOL that is not  shared  with  any
            other process or thread.

       DB_NOMMAP
            Always  copy files in this memory pool into the local
            cache instead of mapping  them  into  process  memory
            (see  the description of the mp_mmapsize field of the
            DbEnv object for further information).


       DB_THREAD
            Cause  the  DbMpool  handle  returned  by  the   DbM-
            pool::open  method  to be useable by multiple threads
            within a single address space, i.e.,  to  be  ``free-
            threaded''.

       All files created by the memory pool subsystem (other than
       files created by the memp_fopen method,  which  are  sepa-
       rately specified) are created with mode mode (as described
       in chmod(2)) and modified by the process' umask  value  at
       the  time of creation (see umask(2)).  The group ownership
       of created files is based  on  the  system  and  directory

       The following fields in the DbEnv object may  be  initial-
       ized,  using  the  appropriate  set method, before calling
       DbMpool::open:


       void *(*db_errcall)(char *db_errpfx, char *buffer);
       FILE *db_errfile;
       const char *db_errpfx;
       class ostream *db_error_stream;
       int db_verbose;
            The error fields of the DbEnv behave as described for
            DbEnv(3).

       size_t mp_mmapsize;
            Files that are opened read-only in the pool (and that
            satisfy a few other criteria) are, by default, mapped
            into  the  process  address  space  instead  of being
            copied into the local cache.  This can result in bet-
            ter-than-usual performance, as available virtual mem-
            ory is normally much larger than the local cache, and
            page faults are faster than page copying on many sys-
            tems.  However, in the presence  of  limited  virtual
            memory  it  can cause resource starvation, and in the
            presence of large databases, it can result in immense
            process sizes.  If mp_mmapsize is non-zero, it speci-
            fies the maximum file size for a file  to  be  mapped
            into  the  process  address space.  By default, it is
            set to 10Mb.

       size_t mp_size;
            The suggested size  of  the  pool,  in  bytes.   This
            should  be the size of the normal working data set of
            the application, with some small amount of additional
            memory  for  unusual  situations.  (Note, the working
            set is not the same as the number  of  simultaneously
            referenced  pages, and should be quite a bit larger!)
            The default cache size is  128K  bytes  (16  8K  byte
            pages), and may not be less than 20K bytes.

       The   DbMpool::open  method  throws  a  DbException(3)  or
       returns the value of errno on failure and 0 on success.

  DbMpool::close
       The DbMpool::close method closes the pool indicated by the
       DbMpool object, as returned by DbMpool::open.  This method
       does not imply a call to  DbMpoolFile::sync  (or  to  DbM-
       poolFile::close)  i.e.  no pages are written to the source
       file as as a result of calling DbMpool::close.

       In addition, if the dir argument to DbMpool::open was NULL
       and  dbenv  was  not initialized using DbEnv::appinit, all
       files created for this shared region will be  removed,  as
       if DbMpool::unlink were called.
       implement the memory pool.   (The  directory  dir  is  not
       removed.)   If  there  are processes that have called DbM-
       pool::open without calling DbMpool::close (i.e., there are
       processes   currently   using   the   memory  pool),  DbM-
       pool::unlink will fail without further action, unless  the
       force  flag  is  set,  in  which case DbMpool::unlink will
       attempt to remove the memory pool files regardless of  any
       processes still using the memory pool.

       The  result  of  attempting to forcibly destroy the region
       when a process has the region open is  unspecified.   Pro-
       cesses  using a shared memory region maintain an open file
       descriptor for it.  On UNIX systems,  the  region  removal
       should  succeed and processes that have already joined the
       region should  continue  to  run  in  the  region  without
       change,  however  processes  attempting to join the memory
       pool will either fail or attempt to create a  new  region.
       On  other  systems,  e.g., WNT, where the unlink(2) system
       call will fail if any process has an open file  descriptor
       for the file, the region removal will fail.

       In  the  case  of catastrophic or system failure, database
       recovery must be  performed  (see  db_recovery(1)  or  the
       DB_RECOVER flags to DbEnv::appinit(3)).  Alternatively, if
       recovery is not required  because  no  database  state  is
       maintained  across  failures, it is possible to clean up a
       memory pool by removing all of the files in the  directory
       specified  to  the  DbMpool::open  method,  as memory pool
       files are never created in any directory  other  than  the
       one  specified to DbMpool::open.  Note, however, that this
       has the potential to remove files created by the other  DB
       subsystems in this database environment.

       The  DbMpool::unlink  method  throws  a  DbException(3) or
       returns the value of errno on failure and 0 on success.

       The DbMpool::db_register method throws a DbException(3) or
       returns the value of errno on failure and 0 on success.

  DbMpool::trickle
       The DbMpool::trickle method ensures that at least pct per-
       cent of the pages in the shared memory pool are  clean  by
       writing  dirty  pages  to  their  backing  files.   If the
       nwrotep argument is non-NULL, the  number  of  pages  that
       were  written  to reach the correct percentage is returned
       in the memory location it references.

       The purpose of the DbMpool::trickle method is to enable  a
       memory pool manager to ensure that a page is always avail-
       able for reading in new information without having to wait
       for a write.

       The  DbMpool::trickle  method  throws  a DbException(3) or
       returns the value of errno on failure and 0 on success.
       page which was written by DbMpool::sync  to  satisfy  this
       request.

       The  purpose  of  the  DbMpool::sync method is to enable a
       transaction manager to ensure, as part  of  a  checkpoint,
       that  all  pages  modified  by  a  certain  time have been
       written to disk.  Pages in the pool which cannot be  writ-
       ten  back to disk immediately (e.g., are currently pinned)
       are written to disk as soon as it is possible  to  do  so.
       The  expected  behavior  of  the transaction manager is to
       call the DbMpool::sync method  and  then,  if  the  return
       indicates  that  some  pages  could not be written immedi-
       ately, to wait briefly and retry again with the  same  LSN
       until the DbMpool::sync method returns that all pages have
       been written.

       To support the DbMpool::sync functionality, it  is  neces-
       sary  that the pool functions know the location of the LSN
       on the page for each file type.  This location  should  be
       specified   when   the  file  is  opened  using  the  DbM-
       poolFile::open method.  (Note, it is not required that the
       LSN be aligned on the page in any way.)

  DbMpool::stat
       The  DbMpool::stat  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 object are copied into the memory location it  refer-
       ences.  The global statistics are stored in a structure of
       type DB_MPOOL_STAT (typedef'd in <db_cxx.h>).

       The following DB_MPOOL_STAT fields will be filled in:

       size_t st_cachesize;
            Cache size in bytes.
       unsigned long st_cache_hit;
            Requested pages found in the cache.
       unsigned long st_cache_miss;
            Requested pages not found in the cache.
       unsigned long st_map;
       unsigned long st_ro_evict;
            Clean pages forced from the cache.
       unsigned long st_rw_evict;
            Dirty pages forced from the cache.
       unsigned long st_hash_buckets;
            Number of hash buckets in buffer hash table.
       unsigned long st_hash_searches;
            Total number of buffer hash table lookups.
       unsigned long st_hash_longest;
            The longest chain ever  encountered  in  buffer  hash
            table lookups.
       unsigned long st_hash_examined;
            Total  number  of hash elements traversed during hash
            table lookups.
       unsigned long st_page_clean;
            Clean pages currently in the cache.
       unsigned long st_page_dirty;
            Dirty pages currently in the cache.
       unsigned long st_page_trickle;
            Dirty pages written using the memp_trickle interface.

       If  fsp  is non-NULL, a pointer to a NULL-terminated vari-
       able length array of statistics for  individual  files  in
       the memory pool is copied into the memory location it ref-
       erences.  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 (typedef'd in <db_cxx.h>).   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.
       unsigned long st_cache_hit;
            Requested pages found in the cache.
       unsigned long st_cache_miss;
            Requested pages not found in the cache.
       unsigned long st_map;
            Requested pages  mapped  into  the  process'  address
            space.
       unsigned long st_page_create;
            Pages created in the cache.
       unsigned long st_page_in;
            Pages read into the cache.

       unsigned long st_page_out;
            Pages written from the cache to the backing file.

       The   DbMpool::stat  method  throws  a  DbException(3)  or
       returns the value of errno on failure and 0 on success.

            If  the  dbenv  argument to DbMpool::open was NULL or
            not initialized  using  db_appinit,  the  environment
            variable TMPDIR may be used as the directory in which
            to create the memory pool, as described in  the  DbM-
            pool::open section above.


ERRORS

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

       The DbMpool::open method may fail  and  throw  a  DbExcep-
       tion(3)  or  return  errno for any of the errors specified
       for the following DB and library functions:
       DBmemp->pgin(3), DBmemp->pgout(3), DbLog::compare(3),
       DbLog::flush(3), DbMpool::close(3), DbMpool::unlink(3),
       close(2), db_version(3), fcntl(2), fflush(3), fsync(2),
       lseek(2), malloc(3), memcmp(3), memcpy(3), memset(3),
       mmap(2), munmap(2), open(2), sigfillset(3),
       sigprocmask(2), stat(2), strcpy(3), strdup(3),
       strerror(3),  strlen(3), time(3), unlink(2), and write(2).

       In addition, the DbMpool::open method may fail and throw a
       DbException(3)  or  return  errno for the following condi-
       tions:

       [EAGAIN]
            The shared memory region was locked and  (repeatedly)
            unavailable.

       [EINVAL]
            An invalid flag value or parameter was specified.

            The  DB_THREAD  flag  was specified and spinlocks are
            not implemented for this architecture.


            A   NULL   pathname   was   specified   without   the
            DB_MPOOL_PRIVATE flag.

            The specified cache size was impossibly small.

       The  DbMpool::close  method  may fail and throw a DbExcep-
       tion(3) or return errno for any of  the  errors  specified
       for the following DB and library functions:
       DbMpoolFile::close(3), close(2), fcntl(2), fflush(3),
       munmap(2), and strerror(3).

       The  DbMpool::unlink  method may fail and throw a DbExcep-
       tion(3) or return errno for any of  the  errors  specified
       for the following DB and library functions: close(2),
       fcntl(2), fflush(3), malloc(3), memcpy(3), memset(3),
       mmap(2), munmap(2), open(2), sigfillset(3),
       sigprocmask(2), stat(2), strcpy(3), strdup(3),
       for the following DB and library functions: fcntl(2), and
       malloc(3).

       The  DbMpool::trickle method may fail and throw a DbExcep-
       tion(3) or return errno for any of  the  errors  specified
       for the following DB and library functions:
       DBmemp->pgin(3), DBmemp->pgout(3), DbLog::compare(3),
       DbLog::flush(3), close(2), fcntl(2), fflush(3), fsync(2),
       lseek(2), malloc(3), memcmp(3), memcpy(3), memset(3),
       mmap(2), open(2), sigfillset(3), sigprocmask(2), stat(2),
       strcpy(3), strdup(3), strerror(3), strlen(3), time(3),
       unlink(2), and write(2).

       In  addition,  the  DbMpool::trickle  method  may fail and
       throw a DbException(3) or return errno for  the  following
       conditions:

       [EINVAL]
            An invalid flag value or parameter was specified.

       The  DbMpool::sync  method  may  fail and throw a DbExcep-
       tion(3) or return errno for any of  the  errors  specified
       for the following DB and library functions:
       DBmemp->pgin(3), DBmemp->pgout(3), DbLog::compare(3),
       DbLog::flush(3), close(2), fcntl(2), fflush(3), fsync(2),
       lseek(2), malloc(3), memcmp(3), memcpy(3), memset(3),
       mmap(2), open(2), qsort(3), realloc(3), sigfillset(3),
       sigprocmask(2), stat(2), strcpy(3), strdup(3),
       strerror(3),  strlen(3), time(3), unlink(2), and write(2).

       In addition, the DbMpool::sync method may fail and throw a
       DbException(3)  or  return  errno for the following condi-
       tions:

       [EINVAL]
            An invalid flag value or parameter was specified.

            The DbMpool::sync method was called  without  logging
            having been initialized in the environment.

       The  DbMpool::stat  method  may  fail and throw a DbExcep-
       tion(3) or return errno for any of  the  errors  specified
       for the following DB and library functions: fcntl(2),
       malloc(3), memcpy(3), and strlen(3).


SEE ALSO

       db_archive(1), db_checkpoint(1), db_deadlock(1), db_dump(1),
       db_load(1), db_recover(1), db_stat(1), db_intro(3), db_jump(3),
       db_thread(3), Db(3), Dbc(3), DbEnv(3), DbException(3), DbInfo(3),
       DbLock(3), DbLocktab(3), DbLog(3), DbLsn(3), DbMpool(3),
       DbMpoolFile(3), Dbt(3), DbTxn(3), DbTxnMgr(3)