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