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 .\" 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$
  30 .\"
  31 .Dd June 17, 2011
  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" "u_int flags"
  51 .Ft int
  52 .Fn mpool_delete "MPOOL *mp" "void *page"
  53 .Ft void *
  54 .Fn mpool_get "MPOOL *mp" "pgno_t pgno" "u_int flags"
  55 .Ft int
  56 .Fn mpool_put "MPOOL *mp" "void *pgaddr" "u_int flags"
  57 .Ft int
  58 .Fn mpool_sync "MPOOL *mp"
  59 .Ft int
  60 .Fn mpool_close "MPOOL *mp"
  61 .Sh DESCRIPTION
  62 The
  63 .Nm mpool
  64 library interface is intended to provide page oriented buffer management
  65 of files.
  66 .Pp
  67 The
  68 .Fn mpool_open
  69 function initializes a memory pool.
  70 The
  71 .Fa key
  72 argument is currently ignored.
  73 The
  74 .Fa fd
  75 argument is a file descriptor for the underlying file, which must be seekable.
  76 .Pp
  77 The
  78 .Fa pagesize
  79 argument is the size, in bytes, of the pages into which the file is broken up.
  80 The
  81 .Fa maxcache
  82 argument is the maximum number of pages from the underlying file to cache
  83 at any one time.
  84 This value is not relative to the number of processes which share a file's
  85 buffers, but will be the largest value specified by any of the processes
  86 sharing the file.
  87 .Pp
  88 The
  89 .Fn mpool_filter
  90 function is intended to make transparent input and output processing of the
  91 pages possible.
  92 If the
  93 .Fa pgin
  94 function is specified, it is called each time a buffer is read into the memory
  95 pool from the backing file.
  96 If the
  97 .Fa pgout
  98 function is specified, it is called each time a buffer is written into the
  99 backing file.
 100 Both functions are called with the
 101 .Fa pgcookie
 102 pointer, the page number and a pointer to the page to being read or written.
 103 .Pp
 104 The function
 105 .Fn mpool_new
 106 takes an
 107 .Dv MPOOL
 108 pointer, an address, and a set of flags as arguments.
 109 If a new page can be allocated, a pointer to the page is returned and
 110 the page number is stored into the
 111 .Fa pgnoaddr
 112 address.
 113 Otherwise,
 114 .Dv NULL
 115 is returned and
 116 .Va errno
 117 is set.
 118 The flags value is formed by
 119 .Tn OR Ns 'ing
 120 the following values:
 121 .Bl -tag -width Ds
 122 .It Dv MPOOL_PAGE_REQUEST
 123 Allocate a new page with a specific page number.
 124 .It Dv MPOOL_PAGE_NEXT
 125 Allocate a new page with the next page number.
 126 .El
 127 .Pp
 128 The function
 129 .Fn mpool_delete
 130 deletes the specified page from a pool and frees the page.
 131 It takes an
 132 .Dv MPOOL
 133 pointer and a page as arguments.
 134 The page must have been generated by
 135 .Fn mpool_new .
 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 specified by
 151 .Em or Ns 'ing
 152 any of the following values:
 153 .Bl -tag -width indent
 154 .It Dv MPOOL_IGNOREPIN
 155 The page returned is not pinned;
 156 page will otherwise be pinned on return.
 157 .El
 158 .Pp
 159 The
 160 .Fn mpool_put
 161 function unpins the page referenced by
 162 .Fa pgaddr .
 163 The
 164 .Fa pgaddr
 165 argument
 166 must be an address previously returned by
 167 .Fn mpool_get
 168 or
 169 .Fn mpool_new .
 170 The
 171 .Fa flags
 172 argument is specified by
 173 .Em or Ns 'ing
 174 any of the following values:
 175 .Bl -tag -width indent
 176 .It Dv MPOOL_DIRTY
 177 The page has been modified and needs to be written to the backing file.
 178 .El
 179 .Pp
 180 The
 181 .Fn mpool_put
 182 function
 183 returns 0 on success and -1 if an error occurs.
 184 .Pp
 185 The
 186 .Fn mpool_sync
 187 function writes all modified pages associated with the
 188 .Ft MPOOL
 189 pointer to the
 190 backing file.
 191 The
 192 .Fn mpool_sync
 193 function
 194 returns 0 on success and -1 if an error occurs.
 195 .Pp
 196 The
 197 .Fn mpool_close
 198 function free's up any allocated memory associated with the memory pool
 199 cookie.
 200 Modified pages are
 201 .Em not
 202 written to the backing file.
 203 The
 204 .Fn mpool_close
 205 function
 206 returns 0 on success and -1 if an error occurs.
 207 .Sh ERRORS
 208 The
 209 .Fn mpool_open
 210 function may fail and set
 211 .Va errno
 212 for any of the errors specified for the library routine
 213 .Xr malloc 3 .
 214 .Pp
 215 The
 216 .Fn mpool_get
 217 function may fail and set
 218 .Va errno
 219 for the following:
 220 .Bl -tag -width Er
 221 .It Bq Er EINVAL
 222 The requested record does not exist.
 223 .El
 224 .Pp
 225 The
 226 .Fn mpool_new
 227 and
 228 .Fn mpool_get
 229 functions may fail and set
 230 .Va errno
 231 for any of the errors specified for the library routines
 232 .Xr read 2 ,
 233 .Xr write 2 ,
 234 and
 235 .Xr malloc 3 .
 236 .Pp
 237 The
 238 .Fn mpool_sync
 239 function may fail and set
 240 .Va errno
 241 for any of the errors specified for the library routine
 242 .Xr write 2 .
 243 .Pp
 244 The
 245 .Fn mpool_close
 246 function may fail and set
 247 .Va errno
 248 for any of the errors specified for the library routine
 249 .Xr free 3 .
 250 .Sh SEE ALSO
 251 .Xr btree 3 ,
 252 .Xr dbopen 3 ,
 253 .Xr hash 3 ,
 254 .Xr recno 3