1<?xml version="1.0" encoding="UTF-8" standalone="no"?> 2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 3<html xmlns="http://www.w3.org/1999/xhtml"> 4 <head> 5 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> 6 <title>DB_ENV->memp_register()</title> 7 <link rel="stylesheet" href="apiReference.css" type="text/css" /> 8 <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /> 9 <link rel="start" href="index.html" title="Berkeley DB C API Reference" /> 10 <link rel="up" href="memp.html" title="Chapter 8. The DB_MPOOLFILE Handle" /> 11 <link rel="prev" href="mempfcreate.html" title="DB_ENV->memp_fcreate()" /> 12 <link rel="next" href="mempstat.html" title="DB_ENV->memp_stat()" /> 13 </head> 14 <body> 15 <div class="navheader"> 16 <table width="100%" summary="Navigation header"> 17 <tr> 18 <th colspan="3" align="center">DB_ENV->memp_register()</th> 19 </tr> 20 <tr> 21 <td width="20%" align="left"><a accesskey="p" href="mempfcreate.html">Prev</a> </td> 22 <th width="60%" align="center">Chapter 8. 23 The DB_MPOOLFILE Handle 24 </th> 25 <td width="20%" align="right"> <a accesskey="n" href="mempstat.html">Next</a></td> 26 </tr> 27 </table> 28 <hr /> 29 </div> 30 <div class="sect1" lang="en" xml:lang="en"> 31 <div class="titlepage"> 32 <div> 33 <div> 34 <h2 class="title" style="clear: both"><a id="mempregister"></a>DB_ENV->memp_register()</h2> 35 </div> 36 </div> 37 </div> 38 <pre class="programlisting">#include <db.h> 39 40int 41DB_ENV->memp_register(DB_ENV *env, int ftype, 42 int (*pgin_fcn)(DB_ENV *env, db_pgno_t pgno, void *pgaddr, 43 DBT *pgcookie), int (*pgout_fcn)(DB_ENV *env, db_pgno_t pgno, 44 void *pgaddr, DBT *pgcookie)); </pre> 45 <p> 46 The <code class="methodname">DB_ENV->memp_register()</code> method registers page-in and page-out 47 functions for files of type <span class="bold"><strong>ftype</strong></span> in the cache. 48 </p> 49 <p> 50 If the <span class="bold"><strong>pgin_fcn</strong></span> function is non-NULL, 51 it is called each time a page is read into the cache from a file 52 of type <span class="bold"><strong>ftype</strong></span>, or a page is created 53 for a file of type <span class="bold"><strong>ftype</strong></span> (see the 54 DB_MPOOL_CREATE flag for the 55 <a class="xref" href="mempfget.html" title="DB_MPOOLFILE->get()">DB_MPOOLFILE->get()</a> method). 56 </p> 57 <p> 58 If the <span class="bold"><strong>pgout_fcn</strong></span> function is 59 non-NULL, it is called each time a page is written to a file of type 60 <span class="bold"><strong>ftype</strong></span>. 61 </p> 62 <p> 63 The purpose of the <code class="methodname">DB_ENV->memp_register()</code> function is to support 64 processing when pages are entered into, or flushed from, the cache. For example, this 65 functionality might be used to do byte-endian conversion as pages are read from, or written 66 to, the underlying file. 67 </p> 68 <p> 69 A file type must be specified to make it possible for unrelated 70 threads or processes that are sharing a cache, to evict each other's 71 pages from the cache. During initialization, applications should call 72 <code class="methodname">DB_ENV->memp_register()</code> for each type of file requiring input or 73 output processing that will be sharing the underlying cache. (No 74 registry is necessary for the standard Berkeley DB access method types 75 because <a class="xref" href="dbopen.html" title="DB->open()">DB->open()</a> 76 registers them separately.) 77 </p> 78 <p> 79 If a thread or process does not call <code class="methodname">DB_ENV->memp_register()</code> for a 80 file type, it is impossible for it to evict pages for any file 81 requiring input or output processing from the cache. For this reason, 82 <code class="methodname">DB_ENV->memp_register()</code> should always be called by each application 83 sharing a cache for each type of file included in the cache, regardless 84 of whether or not the application itself uses files of that type. 85 </p> 86 <p> 87 The <code class="methodname">DB_ENV->memp_register()</code> <span> 88 <span> 89 method returns a non-zero error value on failure and 0 on success. 90 </span> 91 92 </span> 93 </p> 94 <div class="sect2" lang="en" xml:lang="en"> 95 <div class="titlepage"> 96 <div> 97 <div> 98 <h3 class="title"><a id="id1686562"></a>Parameters</h3> 99 </div> 100 </div> 101 </div> 102 <div class="sect3" lang="en" xml:lang="en"> 103 <div class="titlepage"> 104 <div> 105 <div> 106 <h4 class="title"><a id="id1686498"></a>ftype</h4> 107 </div> 108 </div> 109 </div> 110 <p> 111 The <span class="bold"><strong>ftype</strong></span> parameter specifies the 112 type of file for which the page-in and page-out functions will be 113 called. 114 </p> 115 <p> 116 The <span class="bold"><strong>ftype</strong></span> value for a file must be a 117 non-zero positive number less than 128 (0 and negative numbers are 118 reserved for internal use by the Berkeley DB library). 119 </p> 120 </div> 121 <div class="sect3" lang="en" xml:lang="en"> 122 <div class="titlepage"> 123 <div> 124 <div> 125 <h4 class="title"><a id="id1686550"></a>pgin_fcn, pgout_fcn</h4> 126 </div> 127 </div> 128 </div> 129 <p> 130 The page-in and page-out functions. 131 </p> 132 <p> 133 The <span class="bold"><strong>pgin_fcn</strong></span> and <span class="bold"><strong>pgout_fcn</strong></span> functions are called with a reference 134 to the current database environment, the page number being read or 135 written, a pointer to the page being read or written, and any 136 parameter <span class="bold"><strong>pgcookie</strong></span> that was specified 137 to the <a class="xref" href="mempset_pgcookie.html" title="DB_MPOOLFILE->set_pgcookie()">DB_MPOOLFILE->set_pgcookie()</a> 138 method. 139 </p> 140 <p> 141 The <span class="bold"><strong>pgin_fcn</strong></span> and <span class="bold"><strong>pgout_fcn</strong></span> functions should return 0 on success, 142 and a non-zero value on failure, in which case the shared Berkeley DB 143 library function calling it will also fail, returning that non-zero 144 value. The non-zero value should be selected from values outside of 145 the Berkeley DB library namespace. 146 </p> 147 </div> 148 </div> 149 <div class="sect2" lang="en" xml:lang="en"> 150 <div class="titlepage"> 151 <div> 152 <div> 153 <h3 class="title"><a id="id1686563"></a>Class</h3> 154 </div> 155 </div> 156 </div> 157 <p> 158 <a class="link" href="env.html" title="Chapter 5. The DB_ENV Handle">DB_ENV</a>, <a class="link" href="memp.html" title="Chapter 8. The DB_MPOOLFILE Handle">DB_MPOOLFILE</a> 159 </p> 160 </div> 161 <div class="sect2" lang="en" xml:lang="en"> 162 <div class="titlepage"> 163 <div> 164 <div> 165 <h3 class="title"><a id="id1686644"></a>See Also</h3> 166 </div> 167 </div> 168 </div> 169 <p> 170 <a class="xref" href="memp.html#memplist" title="Memory Pools and Related Methods">Memory Pools and Related Methods</a> 171 </p> 172 </div> 173 </div> 174 <div class="navfooter"> 175 <hr /> 176 <table width="100%" summary="Navigation footer"> 177 <tr> 178 <td width="40%" align="left"><a accesskey="p" href="mempfcreate.html">Prev</a> </td> 179 <td width="20%" align="center"> 180 <a accesskey="u" href="memp.html">Up</a> 181 </td> 182 <td width="40%" align="right"> <a accesskey="n" href="mempstat.html">Next</a></td> 183 </tr> 184 <tr> 185 <td width="40%" align="left" valign="top">DB_ENV->memp_fcreate() </td> 186 <td width="20%" align="center"> 187 <a accesskey="h" href="index.html">Home</a> 188 </td> 189 <td width="40%" align="right" valign="top"> DB_ENV->memp_stat()</td> 190 </tr> 191 </table> 192 </div> 193 </body> 194</html> 195