Copyright (c) 1990, 1993, 1994, 1995
The Regents of the University of California. All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
3. All advertising materials mentioning features or use of this software
must display the following acknowledgement:
This product includes software developed by the University of
California, Berkeley and its contributors.
4. Neither the name of the University nor the names of its contributors
may be used to endorse or promote products derived from this software
without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.

@(#)db_mpool.3 8.14 (Berkeley) 8/1/95

C 7 db_mpool - general purpose shared memory buffer pool

#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);

.so db.so .GN 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.

.CR "memory pool" mpool

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.

.OP "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 . .RT 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 . .RT mpool_fclose
.PP
int
mpool_fd (MPOOLFILE *mpf);

.PP
The function
.I mpool_fd
takes an MPOOLFILE pointer and returns the file descriptor being
used to read/write that file
to/from the pool.

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:

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

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

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

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

5 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:

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

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

.RT mpool_put

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. .RT mpool_sync

N "memory pool" mpool

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.

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:

5 [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:

5 [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:

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

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