DB_MPOOL(3)

NAME
db_mpool - general purpose shared memory buffer pool

SYNOPSIS
#include <db.h>
#include <mpool.h>
int
mpool_create(char *path, mode_t mode, size_t cachesize, u_long flags);
MPOOL *
mpool_open(char *path);
int
mpool_close(MPOOL *mp);
MPOOLFILE *
mpool_fopen(MPOOL *mp, char *path, size_t pagesize, void *pgcookie,
int (*pgin)(MPOOLFILE *mpf,
pgno_t pgno, void *pgaddr, void *pgcookie),
int (*pgout)(MPOOLFILE *mpf,
pgno_t pgno, void *pgaddr, void *pgcookie);
int
mpool_fclose(MPOOLFILE *mpf);
void *
mpool_get(MPOOLFILE *mpf, pgno_t *pgnoaddr, u_long flags,
int (*callback)(MPOOLFILE *mpf, pgno_t pgno));
int
mpool_put(MPOOLFILE *mpf, void *pgaddr, u_long flags);
int
mpool_sync(MPOOLFILE *mpf);
int
mpool_unlink(const char *path, int force);
void
mpool_stat(MPOOL *mp, FILE *fp);

DESCRIPTION
specific details of the memory pool interface.

The db_mpool function is the library interface intended to provide general-purpose, page-oriented buffer management of one or more files. While designed to work with the other DB functions, these functions are also useful for more general purposes. The memory pools (MPOOL'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 (MPOOLFILE's). Pages in the pool are replaced in LRU (least-recently-used) order, with each new page replacing the page which has been unused the longest. Pages retrieved from the pool using mpool_get are ``pinned'' in memory, by default, until they are returned to the pool using the mpool_put function.

The cachesize argument specifies the size of the pool in bytes, and should be the size of the normal working set of the application with some small amount of additional memory for unusual situations. If the number of bytes currently ``pinned'' in memory exceeds cachesize, the db_mpool functions will attempt to allocate more memory and do not necessarily fail, although they may suffer performance degradation.

The flags argument is set by or'ing any of the following values:

MPOOL_PRIVATE
    The pool is not shared by other processes or threads, so no locking of pool resources is required.

[memory pool mpool]

The mpool_close function closes the pool indicated by the MPOOL pointer mp, as returned by mpool_open. This function does not imply a call to mpool_sync (or to mpool_fclose) i.e. no pages are written to the source file as as a result of calling mpool_close.

The function mpool_fopen opens a file for buffering in the pool specified by the MPOOL argument. The path argument is the name of the file to be opened. The pagesize argument is the size, in bytes, of the unit of transfer between the application and the pool, although not necessarily the unit of transfer between the pool and the source file. Applications not knowing the page size of the source file should retrieve the metadata from the file using a page size that is correct for the metadata, then close and reopen the file, or, otherwise determine the page size before calling mpool_fopen.

If the pgin function is specified, it is called each time a page is read into the memory pool from the source file. If the pgout function is specified, it is called each time a page is written to the source file. Both functions are called with the MPOOLFILE pointer returned from mpool_fopen, the page number, a pointer to the page being read or written, and the argument pgcookie. If either function fails, it should return non-zero and set errno, in which case the db_mpool function calling it will also fail, leaving errno intact.

The mpool_fclose function closes the source file indicated by the MPOOLFILE pointer mpf. This function does not imply a call to mpool_sync, i.e. no pages are written to the source file as as a result of calling mpool_fclose.

The function mpool_get returns a pointer to the page with the page number specified by pgnoaddr, from the source file specified by the MPOOLFILE pointer mpf. If the page does not exist or cannot be retrieved, mpool_get returns NULL and sets errno.

The flags argument is set by or'ing any of the following values:

MPOOL_CALLBACK
    After the page number has been determined, but before any other process or thread can access the page, the function specified by the callback argument is called. If the function fails, it should return non-zero and set errno, in which case mpool_get will also fail, leaving errno intact. The callback function is called with the MPOOLFILE pointer returned from mpool_fopen and the page number. This functionality is commonly used when page locking is required, but the page number of the page being retrieved is not known.

MPOOL_CREATE
    If the specified page does not exist, create it.

MPOOL_LAST
    Return the last page of the source file and copy its page number to the location referenced by pgnoaddr.

MPOOL_NEW
    Create a new page in the file and copy its page number to the location referenced by pgnoaddr.

MPOOL_NOPIN
    Don't pin the page into memory. (This flag is intended for debugging purposes, when it's often useful to examine pages which are currently held by other parts of the application. Pages retrieved in this manner don't need to be returned to the memory pool, i.e. they should not be specified as arguments to the mpool_put routine.)

Created pages have all their bytes set to 0.

All pages returned by mpool_get (unless the MPOOL_NOPIN flag is specified), will be retained (i.e. ``pinned'') in the pool until a subsequent call to mpool_put.

The function mpool_put indicates that the page referenced by pgaddr can be evicted from the pool. Pgaddr must be an address previously returned by mpool_get.

The flag value is specified by or'ing any of the following values:

MPOOL_DIRTY
    The page has been modified and must be written to the source file before being evicted from the pool.

MPOOL_DISCARD
    The page is unlikely to be useful in the near future, and should be discarded before other pages in the pool.

The function mpool_sync writes all pages associated with the MPOOLFILE pointer mpf, which were specified as arguments to the mpool_put function with an associated flag of MPOOL_DIRTY, to the source file.

The function mpool_stat writes statistics for the memory pool mp to the file specified by fp. These statistics include the number of files participating in the pool, the active pages in the pool, and numbers as to how effective the cache has been.

ERRORS
The mpool_create, mpool_open and mpool_fopen functions may fail and set errno for any of the errors specified for the library functions open(2), read(2), and malloc(3).

The mpool_close and mpool_fclose functions may fail and set errno for any of the errors specified for the library functions close(2) and free(3).

The mpool_get function may fail and set errno for any of the errors specified for the library functions read(2), write(2), and malloc(3) or the following:

[EINVAL]
    The requested page does not exist and MPOOL_CREATE was not set.

The mpool_put function may fail and set errno for any of the errors specified for the library function write(2) or the following:

[EACCES]
    The source file was not opened for writing.

The mpool_sync function may fail and set errno for any of the errors specified for the library function write(2).

The mpool_unlink function may fail and set errno for any of the errors specified for the library function unlink(2) or the following:

[EBUSY]
    The memory pool was in use and the force flag was not set.

SEE ALSO
db_btree(3), db_hash(3), db_lock(3), db_log(3), db_open(3), db_recno(3), db_txn(3)