path: root/src/plugins/kdb/db2/libdb2/man/db_mpool.3

.\" 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
.\"
.TH DB_MPOOL 3 "August 1, 1995"
.UC 7
.SH NAME
db_mpool \- general purpose shared memory buffer pool
.SH SYNOPSIS
.nf
.ft B
#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,
.ti +5
int (*pgin)(MPOOLFILE *mpf,
.ti +8
pgno_t pgno, void *pgaddr, void *pgcookie),
.ti +5
int (*pgout)(MPOOLFILE *mpf,
.ti +8
pgno_t pgno, void *pgaddr, void *pgcookie);

int
mpool_fclose(MPOOLFILE *mpf);

void *
mpool_get(MPOOLFILE *mpf, pgno_t *pgnoaddr, u_long flags,
.ti +5
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);
.ft R
.fi
.SH DESCRIPTION
.so db.so
.GN
specific details of the memory pool interface.
.PP
The
.I 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
.I mpool_get
are ``pinned'' in memory, by default,
until they are returned to the pool using the
.I mpool_put
function.
.PP
.CR "memory pool" mpool
.PP
The
.I 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
.IR cachesize ,
the
.I db_mpool
functions will attempt to allocate more memory and do not necessarily fail,
although they may suffer performance degradation.
.PP
The
.I flags
argument is set by
.IR or 'ing
any of the following values:
.TP
MPOOL_PRIVATE
The pool is not shared by other processes or threads,
so no locking of pool resources is required.
.PP
.OP "memory pool" mpool
.PP
The
.I mpool_close
function closes the pool indicated by the MPOOL pointer
.IR mp ,
as returned by
.IR mpool_open .
This function does
.B not
imply a call to
.I mpool_sync
(or to
.IR mpool_fclose )
i.e. no pages are written to the source file as as a result of calling
.IR mpool_close .
.RT mpool_close
.PP
The function
.I mpool_fopen
opens a file for buffering in the pool specified by the MPOOL
argument.
The
.I path
argument is the name of the file to be opened.
The
.I 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
.IR mpool_fopen .
.PP
If the
.I pgin
function is specified, it is called each time a page is read into
the memory pool from the source file.
If the
.I 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
.IR mpool_fopen ,
the page number, a pointer to the page being read or written, and
the argument
.IR pgcookie .
If either function fails, it should return non-zero and set
.IR errno ,
in which case the
.I db_mpool
function calling it will also fail, leaving
.I errno
intact.
.PP
The
.I mpool_fclose
function closes the source file indicated by the MPOOLFILE pointer
.IR mpf .
This function does
.B not
imply a call to
.IR mpool_sync ,
i.e. no pages are written to the source file as as a result of calling
.IR 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.
.PP
The function
.I mpool_get
returns a pointer to the page with the page number specified by
.IR pgnoaddr ,
from the source file specified by the MPOOLFILE pointer
.IR mpf .
If the page does not exist or cannot be retrieved,
.I mpool_get
returns NULL and sets errno.
.PP
The
.I flags
argument is set by 
.IR or 'ing
any of the following values:
.TP 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
.I callback
argument is called.
If the function fails, it should return non-zero and set
.IR errno ,
in which case
.I mpool_get
will also fail, leaving
.I errno
intact.
The
.I callback
function is called with the MPOOLFILE pointer returned from
.I 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.
.TP 5
MPOOL_CREATE
If the specified page does not exist, create it.
.TP 5
MPOOL_LAST
Return the last page of the source file and copy its page number
to the location referenced by
.IR pgnoaddr .
.TP 5
MPOOL_NEW
Create a new page in the file and copy its page number to the location
referenced by
.IR pgnoaddr .
.TP 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
.B not
be specified as arguments to the
.IR mpool_put
routine.)
.PP
Created pages have all their bytes set to 0.
.PP
All pages returned by
.I mpool_get
(unless the MPOOL_NOPIN flag is specified),
will be retained (i.e. ``pinned'') in the pool until a subsequent
call to
.IR mpool_put .
.PP
The function
.I mpool_put
indicates that the page referenced by
.I pgaddr
can be evicted from the pool.
.I Pgaddr
must be an address previously returned by
.IR mpool_get .
.PP
The flag value is specified by
.IR or 'ing
any of the following values:
.TP 5
MPOOL_DIRTY
The page has been modified and must be written to the source file
before being evicted from the pool.
.TP 5
MPOOL_DISCARD
The page is unlikely to be useful in the near future, and should be
discarded before other pages in the pool.
.PP
.RT mpool_put
.PP
The function
.I mpool_sync
writes all pages associated with the MPOOLFILE pointer
.IR mpf ,
which were specified as arguments to the
.I mpool_put
function with an associated flag of
MPOOL_DIRTY,
to the source file.
.RT mpool_sync
.PP
.UN "memory pool" mpool
.PP
The function
.I mpool_stat
writes statistics for the memory pool
.I mp
to the file specified by
.IR 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.
.SH ERRORS
The
.IR mpool_create ,
.I mpool_open
and
.I mpool_fopen
functions may fail and set
.I errno
for any of the errors specified for the library functions
.IR open (2),
.IR read (2),
and
.IR malloc (3).
.PP
The
.I mpool_close
and
.I mpool_fclose
functions may fail and set
.I errno
for any of the errors specified for the library functions
.IR close (2)
and
.IR free (3).
.PP
The
.I mpool_get
function may fail and set
.I errno
for any of the errors specified for the library functions
.IR read (2),
.IR write (2),
and
.IR malloc (3)
or the following:
.TP 5
[EINVAL]
The requested page does not exist and MPOOL_CREATE was not set.
.PP
The
.I mpool_put
function may fail and set
.I errno
for any of the errors specified for the library function
.IR write (2)
or the following:
.TP 5
[EACCES]
The source file was not opened for writing.
.PP
The
.I mpool_sync
function may fail and set
.I errno
for any of the errors specified for the library function
.IR write (2).
.PP
The
.I mpool_unlink
function may fail and set
.I errno
for any of the errors specified for the library function
.IR unlink (2)
or the following:
.TP 5
[EBUSY]
The memory pool was in use and the force flag was not set.
.SH "SEE ALSO"
.IR db_btree (3),
.IR db_hash (3),
.IR db_lock (3),
.IR db_log (3),
.IR db_open (3),
.IR db_recno (3),
.IR db_txn (3)