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>DbEnv::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 9. The DbMpoolFile Handle" /> 11 <link rel="prev" href="mempfcreate.html" title="DbEnv::memp_fcreate()" /> 12 <link rel="next" href="mempstat.html" title="DbEnv::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">DbEnv::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 9. 23 The DbMpoolFile 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>DbEnv::memp_register()</h2> 35 </div> 36 </div> 37 </div> 38 <pre class="programlisting">#include <db_cxx.h> 39 40extern "C" { 41 typedef int (*pgin_fcn_type)(DB_ENV *dbenv, 42 db_pgno_t pgno, void *pgaddr, DBT *pgcookie); 43 typedef int (*pgout_fcn_type)(DB_ENV *dbenv, 44 db_pgno_t pgno, void *pgaddr, DBT *pgcookie); 45}; 46int 47DbEnv::memp_register(int ftype, 48 pgin_fcn_type pgin_fcn, pgout_fcn_type pgout_fcn);</pre> 49 <p> 50 The <code class="methodname">DbEnv::memp_register()</code> method registers page-in and page-out 51 functions for files of type <span class="bold"><strong>ftype</strong></span> in the cache. 52 </p> 53 <p> 54 If the <span class="bold"><strong>pgin_fcn</strong></span> function is non-NULL, 55 it is called each time a page is read into the cache from a file 56 of type <span class="bold"><strong>ftype</strong></span>, or a page is created 57 for a file of type <span class="bold"><strong>ftype</strong></span> (see the 58 DB_MPOOL_CREATE flag for the 59 <a class="xref" href="mempfget.html" title="DbMpoolFile::get()">DbMpoolFile::get()</a> method). 60 </p> 61 <p> 62 If the <span class="bold"><strong>pgout_fcn</strong></span> function is 63 non-NULL, it is called each time a page is written to a file of type 64 <span class="bold"><strong>ftype</strong></span>. 65 </p> 66 <p> 67 The purpose of the <code class="methodname">DbEnv::memp_register()</code> function is to support 68 processing when pages are entered into, or flushed from, the cache. For example, this 69 functionality might be used to do byte-endian conversion as pages are read from, or written 70 to, the underlying file. 71 </p> 72 <p> 73 A file type must be specified to make it possible for unrelated 74 threads or processes that are sharing a cache, to evict each other's 75 pages from the cache. During initialization, applications should call 76 <code class="methodname">DbEnv::memp_register()</code> for each type of file requiring input or 77 output processing that will be sharing the underlying cache. (No 78 registry is necessary for the standard Berkeley DB access method types 79 because <a class="xref" href="dbopen.html" title="Db::open()">Db::open()</a> 80 registers them separately.) 81 </p> 82 <p> 83 If a thread or process does not call <code class="methodname">DbEnv::memp_register()</code> for a 84 file type, it is impossible for it to evict pages for any file 85 requiring input or output processing from the cache. For this reason, 86 <code class="methodname">DbEnv::memp_register()</code> should always be called by each application 87 sharing a cache for each type of file included in the cache, regardless 88 of whether or not the application itself uses files of that type. 89 </p> 90 <p> 91 The <code class="methodname">DbEnv::memp_register()</code> <span> 92 93 <span> 94 method either returns a non-zero error value or throws an 95 exception that encapsulates a non-zero error value on 96 failure, and returns 0 on success. 97 </span> 98 </span> 99 </p> 100 <div class="sect2" lang="en" xml:lang="en"> 101 <div class="titlepage"> 102 <div> 103 <div> 104 <h3 class="title"><a id="id1690639"></a>Parameters</h3> 105 </div> 106 </div> 107 </div> 108 <div class="sect3" lang="en" xml:lang="en"> 109 <div class="titlepage"> 110 <div> 111 <div> 112 <h4 class="title"><a id="id1690751"></a>ftype</h4> 113 </div> 114 </div> 115 </div> 116 <p> 117 The <span class="bold"><strong>ftype</strong></span> parameter specifies the 118 type of file for which the page-in and page-out functions will be 119 called. 120 </p> 121 <p> 122 The <span class="bold"><strong>ftype</strong></span> value for a file must be a 123 non-zero positive number less than 128 (0 and negative numbers are 124 reserved for internal use by the Berkeley DB library). 125 </p> 126 </div> 127 <div class="sect3" lang="en" xml:lang="en"> 128 <div class="titlepage"> 129 <div> 130 <div> 131 <h4 class="title"><a id="id1690902"></a>pgin_fcn, pgout_fcn</h4> 132 </div> 133 </div> 134 </div> 135 <p> 136 The page-in and page-out functions. 137 </p> 138 <p> 139 The <span class="bold"><strong>pgin_fcn</strong></span> and <span class="bold"><strong>pgout_fcn</strong></span> functions are called with a reference 140 to the current database environment, the page number being read or 141 written, a pointer to the page being read or written, and any 142 parameter <span class="bold"><strong>pgcookie</strong></span> that was specified 143 to the <a class="xref" href="mempset_pgcookie.html" title="DbMpoolFile::set_pgcookie()">DbMpoolFile::set_pgcookie()</a> 144 method. 145 </p> 146 <p> 147 The <span class="bold"><strong>pgin_fcn</strong></span> and <span class="bold"><strong>pgout_fcn</strong></span> functions should return 0 on success, 148 and a non-zero value on failure, in which case the shared Berkeley DB 149 library function calling it will also fail, returning that non-zero 150 value. The non-zero value should be selected from values outside of 151 the Berkeley DB library namespace. 152 </p> 153 </div> 154 </div> 155 <div class="sect2" lang="en" xml:lang="en"> 156 <div class="titlepage"> 157 <div> 158 <div> 159 <h3 class="title"><a id="id1690900"></a>Class</h3> 160 </div> 161 </div> 162 </div> 163 <p> 164 <a class="link" href="env.html" title="Chapter 5. The DbEnv Handle">DbEnv</a>, <a class="link" href="memp.html" title="Chapter 9. The DbMpoolFile Handle">DbMpoolFile</a> 165 </p> 166 </div> 167 <div class="sect2" lang="en" xml:lang="en"> 168 <div class="titlepage"> 169 <div> 170 <div> 171 <h3 class="title"><a id="id1690640"></a>See Also</h3> 172 </div> 173 </div> 174 </div> 175 <p> 176 <a class="xref" href="memp.html#memplist" title="Memory Pools and Related Methods">Memory Pools and Related Methods</a> 177 </p> 178 </div> 179 </div> 180 <div class="navfooter"> 181 <hr /> 182 <table width="100%" summary="Navigation footer"> 183 <tr> 184 <td width="40%" align="left"><a accesskey="p" href="mempfcreate.html">Prev</a> </td> 185 <td width="20%" align="center"> 186 <a accesskey="u" href="memp.html">Up</a> 187 </td> 188 <td width="40%" align="right"> <a accesskey="n" href="mempstat.html">Next</a></td> 189 </tr> 190 <tr> 191 <td width="40%" align="left" valign="top">DbEnv::memp_fcreate() </td> 192 <td width="20%" align="center"> 193 <a accesskey="h" href="index.html">Home</a> 194 </td> 195 <td width="40%" align="right" valign="top"> DbEnv::memp_stat()</td> 196 </tr> 197 </table> 198 </div> 199 </body> 200</html> 201