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