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