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