db/man/FreeBSD/mpool.3

   1 .\" Copyright (c) 1990, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 4. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\"     @(#)mpool.3     8.1 (Berkeley) 6/4/93
  29 .\" $FreeBSD: src/lib/libc/db/man/mpool.3,v 1.15 2007/01/09 00:27:51 imp Exp $
  30 .\"
  31 .Dd June 4, 1993
  32 .Dt MPOOL 3
  33 .Os
  34 .Sh NAME
  35 .Nm mpool
  36 .Nd "shared memory buffer pool"
  37 .Sh SYNOPSIS
  38 .In db.h
  39 .In mpool.h
  40 .Ft MPOOL *
  41 .Fn mpool_open "void *key" "int fd" "pgno_t pagesize" "pgno_t maxcache"
  42 .Ft void
  43 .Fo mpool_filter
  44 .Fa "MPOOL *mp"
  45 .Fa "void (*pgin)(void *, pgno_t, void *)"
  46 .Fa "void (*pgout)(void *, pgno_t, void *)"
  47 .Fa "void *pgcookie"
  48 .Fc
  49 .Ft void *
  50 .Fn mpool_new "MPOOL *mp" "pgno_t *pgnoaddr"
  51 .Ft void *
  52 .Fn mpool_get "MPOOL *mp" "pgno_t pgno" "u_int flags"
  53 .Ft int
  54 .Fn mpool_put "MPOOL *mp" "void *pgaddr" "u_int flags"
  55 .Ft int
  56 .Fn mpool_sync "MPOOL *mp"
  57 .Ft int
  58 .Fn mpool_close "MPOOL *mp"
  59 .Sh DESCRIPTION
  60 The
  61 .Nm mpool
  62 library interface is intended to provide page oriented buffer management
  63 of files.
  64 .Pp
  65 The
  66 .Fn mpool_open
  67 function initializes a memory pool.
  68 The
  69 .Fa key
  70 argument is currently ignored.
  71 The
  72 .Fa fd
  73 argument is a file descriptor for the underlying file, which must be seekable.
  74 .Pp
  75 The
  76 .Fa pagesize
  77 argument is the size, in bytes, of the pages into which the file is broken up.
  78 The
  79 .Fa maxcache
  80 argument is the maximum number of pages from the underlying file to cache
  81 at any one time.
  82 This value is not relative to the number of processes which share a file's
  83 buffers, but will be the largest value specified by any of the processes
  84 sharing the file.
  85 .Pp
  86 The
  87 .Fn mpool_filter
  88 function is intended to make transparent input and output processing of the
  89 pages possible.
  90 If the
  91 .Fa pgin
  92 function is specified, it is called each time a buffer is read into the memory
  93 pool from the backing file.
  94 If the
  95 .Fa pgout
  96 function is specified, it is called each time a buffer is written into the
  97 backing file.
  98 Both functions are called with the
  99 .Fa pgcookie
 100 pointer, the page number and a pointer to the page to being read or written.
 101 .Pp
 102 The
 103 .Fn mpool_new
 104 function takes an
 105 .Ft MPOOL
 106 pointer and an address as arguments.
 107 If a new page can be allocated, a pointer to the page is returned and
 108 the page number is stored into the
 109 .Fa pgnoaddr
 110 address.
 111 Otherwise,
 112 .Dv NULL
 113 is returned and
 114 .Va errno
 115 is set.
 116 .Pp
 117 The
 118 .Fn mpool_get
 119 function takes a
 120 .Ft MPOOL
 121 pointer and a page number as arguments.
 122 If the page exists, a pointer to the page is returned.
 123 Otherwise,
 124 .Dv NULL
 125 is returned and
 126 .Va errno
 127 is set.
 128 The
 129 .Fa flags
 130 argument is not currently used.
 131 .Pp
 132 The
 133 .Fn mpool_put
 134 function unpins the page referenced by
 135 .Fa pgaddr .
 136 The
 137 .Fa pgaddr
 138 argument
 139 must be an address previously returned by
 140 .Fn mpool_get
 141 or
 142 .Fn mpool_new .
 143 The
 144 .Fa flags
 145 argument is specified by
 146 .Em or Ns 'ing
 147 any of the following values:
 148 .Bl -tag -width indent
 149 .It Dv MPOOL_DIRTY
 150 The page has been modified and needs to be written to the backing file.
 151 .El
 152 .Pp
 153 The
 154 .Fn mpool_put
 155 function
 156 returns 0 on success and -1 if an error occurs.
 157 .Pp
 158 The
 159 .Fn mpool_sync
 160 function writes all modified pages associated with the
 161 .Ft MPOOL
 162 pointer to the
 163 backing file.
 164 The
 165 .Fn mpool_sync
 166 function
 167 returns 0 on success and -1 if an error occurs.
 168 .Pp
 169 The
 170 .Fn mpool_close
 171 function free's up any allocated memory associated with the memory pool
 172 cookie.
 173 Modified pages are
 174 .Em not
 175 written to the backing file.
 176 The
 177 .Fn mpool_close
 178 function
 179 returns 0 on success and -1 if an error occurs.
 180 .Sh ERRORS
 181 The
 182 .Fn mpool_open
 183 function may fail and set
 184 .Va errno
 185 for any of the errors specified for the library routine
 186 .Xr malloc 3 .
 187 .Pp
 188 The
 189 .Fn mpool_get
 190 function may fail and set
 191 .Va errno
 192 for the following:
 193 .Bl -tag -width Er
 194 .It Bq Er EINVAL
 195 The requested record does not exist.
 196 .El
 197 .Pp
 198 The
 199 .Fn mpool_new
 200 and
 201 .Fn mpool_get
 202 functions may fail and set
 203 .Va errno
 204 for any of the errors specified for the library routines
 205 .Xr read 2 ,
 206 .Xr write 2 ,
 207 and
 208 .Xr malloc 3 .
 209 .Pp
 210 The
 211 .Fn mpool_sync
 212 function may fail and set
 213 .Va errno
 214 for any of the errors specified for the library routine
 215 .Xr write 2 .
 216 .Pp
 217 The
 218 .Fn mpool_close
 219 function may fail and set
 220 .Va errno
 221 for any of the errors specified for the library routine
 222 .Xr free 3 .
 223 .Sh SEE ALSO
 224 .Xr btree 3 ,
 225 .Xr dbopen 3 ,
 226 .Xr hash 3 ,
 227 .Xr recno 3