lib/libc/db/man/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.5.2.5 2003/02/23 19:45:52 trhodes Exp $
  34 .\" $DragonFly: src/lib/libc/db/man/mpool.3,v 1.2 2003/06/17 04:26:41 dillon Exp $
  35 .\"
  36 .Dd June 4, 1993
  37 .Dt MPOOL 3
  38 .Os
  39 .Sh NAME
  40 .Nm mpool
  41 .Nd "shared memory buffer pool"
  42 .Sh SYNOPSIS
  43 .In db.h
  44 .In mpool.h
  45 .Ft MPOOL *
  46 .Fn mpool_open "void *key" "int fd" "pgno_t pagesize" "pgno_t maxcache"
  47 .Ft void
  48 .Fo mpool_filter
  49 .Fa "MPOOL *mp"
  50 .Fa "void (*pgin)(void *, pgno_t, void *)"
  51 .Fa "void (*pgout)(void *, pgno_t, void *)"
  52 .Fa "void *pgcookie"
  53 .Fc
  54 .Ft void *
  55 .Fn mpool_new "MPOOL *mp" "pgno_t *pgnoaddr"
  56 .Ft void *
  57 .Fn mpool_get "MPOOL *mp" "pgno_t pgno" "u_int flags"
  58 .Ft int
  59 .Fn mpool_put "MPOOL *mp" "void *pgaddr" "u_int flags"
  60 .Ft int
  61 .Fn mpool_sync "MPOOL *mp"
  62 .Ft int
  63 .Fn mpool_close "MPOOL *mp"
  64 .Sh DESCRIPTION
  65 The
  66 .Nm mpool
  67 library interface is intended to provide page oriented buffer management
  68 of files.
  69 The buffers may be shared between processes.
  70 .Pp
  71 The
  72 .Fn mpool_open
  73 function initializes a memory pool.
  74 The
  75 .Fa key
  76 argument is the byte string used to negotiate between multiple
  77 processes wishing to share buffers.
  78 If the file buffers are mapped in shared memory, all processes using
  79 the same key will share the buffers.
  80 If
  81 .Fa key
  82 is
  83 .Dv NULL ,
  84 the buffers are mapped into private memory.
  85 The
  86 .Fa fd
  87 argument is a file descriptor for the underlying file, which must be seekable.
  88 If
  89 .Fa key
  90 is
  91 .No non\- Ns Dv NULL
  92 and matches a file already being mapped, the
  93 .Fa fd
  94 argument is ignored.
  95 .Pp
  96 The
  97 .Fa pagesize
  98 argument is the size, in bytes, of the pages into which the file is broken up.
  99 The
 100 .Fa maxcache
 101 argument is the maximum number of pages from the underlying file to cache
 102 at any one time.
 103 This value is not relative to the number of processes which share a file's
 104 buffers, but will be the largest value specified by any of the processes
 105 sharing the file.
 106 .Pp
 107 The
 108 .Fn mpool_filter
 109 function is intended to make transparent input and output processing of the
 110 pages possible.
 111 If the
 112 .Fa pgin
 113 function is specified, it is called each time a buffer is read into the memory
 114 pool from the backing file.
 115 If the
 116 .Fa pgout
 117 function is specified, it is called each time a buffer is written into the
 118 backing file.
 119 Both functions are called with the
 120 .Fa pgcookie
 121 pointer, the page number and a pointer to the page to being read or written.
 122 .Pp
 123 The
 124 .Fn mpool_new
 125 function takes an
 126 .Ft MPOOL
 127 pointer and an address as arguments.
 128 If a new page can be allocated, a pointer to the page is returned and
 129 the page number is stored into the
 130 .Fa pgnoaddr
 131 address.
 132 Otherwise,
 133 .Dv NULL
 134 is returned and
 135 .Va errno
 136 is set.
 137 .Pp
 138 The
 139 .Fn mpool_get
 140 function takes a
 141 .Ft MPOOL
 142 pointer and a page number as arguments.
 143 If the page exists, a pointer to the page is returned.
 144 Otherwise,
 145 .Dv NULL
 146 is returned and
 147 .Va errno
 148 is set.
 149 The
 150 .Fa flags
 151 argument is not currently used.
 152 .Pp
 153 The
 154 .Fn mpool_put
 155 function unpins the page referenced by
 156 .Fa pgaddr .
 157 The
 158 .Fa pgaddr
 159 argument
 160 must be an address previously returned by
 161 .Fn mpool_get
 162 or
 163 .Fn mpool_new .
 164 The
 165 .Fa flags
 166 argument is specified by
 167 .Em or Ns 'ing
 168 any of the following values:
 169 .Bl -tag -width indent
 170 .It Dv MPOOL_DIRTY
 171 The page has been modified and needs to be written to the backing file.
 172 .El
 173 .Pp
 174 The
 175 .Fn mpool_put
 176 function
 177 returns 0 on success and -1 if an error occurs.
 178 .Pp
 179 The
 180 .Fn mpool_sync
 181 function writes all modified pages associated with the
 182 .Ft MPOOL
 183 pointer to the
 184 backing file.
 185 The
 186 .Fn mpool_sync
 187 function
 188 returns 0 on success and -1 if an error occurs.
 189 .Pp
 190 The
 191 .Fn mpool_close
 192 function free's up any allocated memory associated with the memory pool
 193 cookie.
 194 Modified pages are
 195 .Em not
 196 written to the backing file.
 197 The
 198 .Fn mpool_close
 199 function
 200 returns 0 on success and -1 if an error occurs.
 201 .Sh ERRORS
 202 The
 203 .Fn mpool_open
 204 function may fail and set
 205 .Va errno
 206 for any of the errors specified for the library routine
 207 .Xr malloc 3 .
 208 .Pp
 209 The
 210 .Fn mpool_get
 211 function may fail and set
 212 .Va errno
 213 for the following:
 214 .Bl -tag -width Er
 215 .It Bq Er EINVAL
 216 The requested record doesn't exist.
 217 .El
 218 .Pp
 219 The
 220 .Fn mpool_new
 221 and
 222 .Fn mpool_get
 223 functions may fail and set
 224 .Va errno
 225 for any of the errors specified for the library routines
 226 .Xr read 2 ,
 227 .Xr write 2 ,
 228 and
 229 .Xr malloc 3 .
 230 .Pp
 231 The
 232 .Fn mpool_sync
 233 function may fail and set
 234 .Va errno
 235 for any of the errors specified for the library routine
 236 .Xr write 2 .
 237 .Pp
 238 The
 239 .Fn mpool_close
 240 function may fail and set
 241 .Va errno
 242 for any of the errors specified for the library routine
 243 .Xr free 3 .
 244 .Sh SEE ALSO
 245 .Xr btree 3 ,
 246 .Xr dbopen 3 ,
 247 .Xr hash 3 ,
 248 .Xr recno 3