.\" Copyright (c) 1990, 1993
.\"	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.
.\"
.\"	@(#)mpool.3	8.1 (Berkeley) 6/4/93
.\" %FreeBSD: src/lib/libc/db/man/mpool.3,v 1.5.2.4 2001/12/14 18:33:49 ru Exp %
.\" $FreeBSD$
.\"
.Dd June 4, 1993
.Dt MPOOL 3
.Os
.Sh 名称
.Nm mpool
.Nd 共有メモリバッファプール
.Sh 書式
.In db.h
.In mpool.h
.Ft MPOOL *
.Fn mpool_open "void *key" "int fd" "pgno_t pagesize" "pgno_t maxcache"
.Ft void
.Fo mpool_filter
.Fa "MPOOL *mp"
.Fa "void (*pgin)(void *, pgno_t, void *)"
.Fa "void (*pgout)(void *, pgno_t, void *)"
.Fa "void *pgcookie"
.Fc
.Ft void *
.Fn mpool_new "MPOOL *mp" "pgno_t *pgnoaddr"
.Ft void *
.Fn mpool_get "MPOOL *mp" "pgno_t pgno" "u_int flags"
.Ft int
.Fn mpool_put "MPOOL *mp" "void *pgaddr" "u_int flags"
.Ft int
.Fn mpool_sync "MPOOL *mp"
.Ft int
.Fn mpool_close "MPOOL *mp"
.Sh 解説
.Nm mpool
は、ページを基準にした、ファイルのバッファ管理を行なう
ライブラリインタフェースです。バッファはプロセス間で共有できます。
.Pp
関数
.Fn mpool_open
はメモリプールを初期化します。引数
.Fa key
は、バッファ
を共有する複数のプロセス間でネゴシエートするために使われる
バイトストリングです。
ファイルバッファが共有メモリにマップされた場合は、同じキーを
使用しているすべてのプロセスがバッファを共有します。
.Fa key
が
.Dv NULL
である場合、バッファはプライベートメモリにマップされます。
引数
.Fa fd
は、基礎となる
ファイルのファイル記述子で、検索可能になっている必要があります。
.Fa key
が
.Dv NULL
ではなく、すでにマップされているファイルと一致する場合、引数
.Fa fd
は無視されます。
.Pp
引数
.Fa pagesize
は、ファイルを分割するページのサイズ (バイト単位) です。引数
.Fa maxcache
は、一度にキャッシュする、基礎となるファイルの最大ページ数です。
この値は、ファイルのバッファを共有するプロセス数とは
関係ありませんが、ファイルを共有するプロセスが指定した最大値になります。
.Pp
関数
.Fn mpool_filter
は、ページの透過的入出力処理を行ないます。
.Fa pgin
関数が指定されると、保存ファイルからメモリプールにバッファを
読み込むたびに呼び出されます。
.Fa pgout
関数が指定されると、保存ファイルにバッファが書き込まれるたびに
呼び出されます。どちらの関数も、
.Fa pgcookie
ポインタ、ページ番号、読み書きを行なうページのポインタで呼び出されます。
.Pp
関数
.Fn mpool_new
は、
.Ft MPOOL
ポインタとアドレスを引数として取ります。
新しいページを割り振ることができる場合は、ページのポインタが返され、
ページ番号が
.Fa pgnoaddr
アドレスに保存されます。割り振ることができない場合は
.Dv NULL
が返され、
.Va errno
が設定されます。
.Pp
関数
.Fn mpool_get
は、
.Ft MPOOL
ポインタとページ番号を引数として取ります。
ページが存在する場合は、ページのポインタが返されます。
ページが存在しない場合は
.Dv NULL
が返され、
.Va errno
がセットされます。
.Fa flags
パラメータは、今のところ使用されていません。
.Pp
関数
.Fn mpool_put
は、
.Fa pgaddr
が参照するページを解放します。
.Fa pgaddr
は、あらかじめ
.Fn mpool_get
または
.Fn mpool_new
が返したアドレスでなければなりません。
.Fa flags
パラメータは以下の値の論理和 (
.Em or
) によって指定されます。
.Bl -tag -width indent
.It Dv MPOOL_DIRTY
ページが修正されており、保存ファイルに書き込む必要があります。
.El
.Pp
関数
.Fn mpool_put
は、正常終了時には 0 を返し、エラーのときは -1 を返します。
.Pp
関数
.Fn mpool_sync
は、
.Ft MPOOL
ポインタに対して、変更されたすべてのページを
保存ファイルに書き込みます。
.Fn mpool_sync
は、正常終了時には 0 を返し、エラーのときは -1 を返します。
.Pp
関数
.Fn mpool_close
は、メモリプールクッキーに対して割り振られたメモリを解放します。
修正されたページは、保存ファイルに書き込まれ
.Em ません
。
.Fn mpool_close
は、正常終了時には 0 を返し、エラーのときは -1 を返します。
.Sh エラー
関数
.Fn mpool_open
でエラーが発生すると、ライブラリルーチン
.Xr malloc 3
で指定されたエラーの
.Va errno
がセットされます。
.Pp
関数
.Fn mpool_get
でエラーが発生すると、以下の
.Va errno
がセットされます。
.Bl -tag -width Er
.It Bq Er EINVAL
要求されたレコードが存在しない。
.El
.Pp
関数
.Fn mpool_new
と
.Fn mpool_get
でエラーが発生すると、ライブラリルーチン
.Xr read 2 ,
.Xr write 2 ,
.Xr malloc 3
で指定されたエラーの
.Va errno
がセットされます。
.Pp
関数
.Fn mpool_sync
でエラーが発生すると、ライブラリルーチン
.Xr write 2
で指定されたエラーの
.Va errno
がセットされます。
.Pp
関数
.Fn mpool_close
でエラーが発生すると、ライブラリルーチン
.Xr free 3
で
指定したエラーの
.Va errno
がセットされます。
.Sh 関連項目
.Xr btree 3 ,
.Xr dbopen 3 ,
.Xr hash 3 ,
.Xr recno 3