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>DbMpoolFile::get()</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="mempfclose.html" title="DbMpoolFile::close()" /> 12 <link rel="next" href="mempfopen.html" title="DbMpoolFile::open()" /> 13 </head> 14 <body> 15 <div class="navheader"> 16 <table width="100%" summary="Navigation header"> 17 <tr> 18 <th colspan="3" align="center">DbMpoolFile::get()</th> 19 </tr> 20 <tr> 21 <td width="20%" align="left"><a accesskey="p" href="mempfclose.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="mempfopen.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="mempfget"></a>DbMpoolFile::get()</h2> 35 </div> 36 </div> 37 </div> 38 <pre class="programlisting">#include <db_cxx.h> 39 40int 41DbMpoolFile::get(db_pgno_t *pgnoaddr, 42 DbTxn *txnid, u_int32_t flags, void **pagep);</pre> 43 <p> 44 The <code class="methodname">DbMpoolFile::get()</code> method returns pages from the cache. 45 </p> 46 <p> 47 All pages returned by <code class="methodname">DbMpoolFile::get()</code> will be retained (that is, 48 <span class="emphasis"><em>latched</em></span>) in the cache until a subsequent call to 49 <a class="xref" href="mempput.html" title="DbMpoolFile::put()">DbMpoolFile::put()</a>. 50 There is no deadlock detection amoung latches so care must be taken in the application if the DB_MPOOL_DIRTY 51 or DB_MPOOL_EDIT flags are used as these get exlusive latches on the pages. 52 </p> 53 <p> 54 The returned page is <span class="bold"><strong>size_t</strong></span> type 55 aligned. 56 </p> 57 <p> 58 Fully or partially created pages have all their bytes set to a nul 59 byte, unless the 60 <a class="xref" href="mempset_clear_len.html" title="DbMpoolFile::set_clear_len()">DbMpoolFile::set_clear_len()</a> 61 method was called to specify other behavior before the file was 62 opened. 63 </p> 64 <p><a id="fget_DB_PAGE_NOTFOUND"></a> 65 The <code class="methodname">DbMpoolFile::get()</code> method will return 66 <code class="literal">DB_PAGE_NOTFOUND</code> if the requested page does not exist and DB_MPOOL_CREATE 67 was not set. Unless otherwise specified, the <code class="methodname">DbMpoolFile::get()</code> 68 <span> 69 70 <span> 71 method either returns a non-zero error value or throws an 72 exception that encapsulates a non-zero error value on 73 failure, and returns 0 on success. 74 </span> 75 </span> 76 </p> 77 <div class="sect2" lang="en" xml:lang="en"> 78 <div class="titlepage"> 79 <div> 80 <div> 81 <h3 class="title"><a id="id1693648"></a>Parameters</h3> 82 </div> 83 </div> 84 </div> 85 <div class="sect3" lang="en" xml:lang="en"> 86 <div class="titlepage"> 87 <div> 88 <div> 89 <h4 class="title"><a id="id1693785"></a>flags</h4> 90 </div> 91 </div> 92 </div> 93 <p> 94 The <span class="bold"><strong>flags</strong></span> parameter must be set to 0 95 or by bitwise inclusively <span class="bold"><strong>OR</strong></span>'ing 96 together one or more of the following values: 97 </p> 98 <div class="itemizedlist"> 99 <ul type="disc"> 100 <li> 101 <p><a id="mpoolfget_DB_MPOOL_CREATE"></a> 102 <code class="literal">DB_MPOOL_CREATE</code> 103 </p> 104 <p> 105 If the specified page does not exist, create it. In this case, the 106 <a class="link" href="mempregister.html" title="DbEnv::memp_register()">pgin</a> method, if 107 specified, is called. 108 </p> 109 </li> 110 <li> 111 <p><a id="fget_DB_MPOOL_DIRTY"></a> 112 <code class="literal">DB_MPOOL_DIRTY</code> 113 </p> 114 <p> 115 The page will be modified and must be written to the source file 116 before being evicted from the cache. For files open with the 117 <a class="link" href="dbopen.html#dbopen_DB_MULTIVERSION">DB_MULTIVERSION</a> 118 flag set, a new copy of the page will be made if this is the first 119 time the specified transaction is modifying it. 120 A page fetched with the <code class="literal">DB_MPOOL_DIRTY</code> flag will be 121 <span class="bold"><strong>excluively latched</strong></span> until 122 a subsequent call to <a class="xref" href="mempput.html" title="DbMpoolFile::put()">DbMpoolFile::put()</a>. 123 </p> 124 </li> 125 <li> 126 <p><a id="fget_DB_MPOOL_EDIT"></a> 127 <code class="literal">DB_MPOOL_EDIT</code> 128 </p> 129 <p> 130 The page will be modified and must be written to the source file 131 before being evicted from the cache. No copy of the page will be made, 132 regardless of the 133 <a class="link" href="dbopen.html#dbopen_DB_MULTIVERSION">DB_MULTIVERSION</a> 134 setting. This flag is only intended for use in situations where a 135 transaction handle is not available, such as during aborts or 136 recovery. 137 A page fetched with the <code class="literal">DB_MPOOL_EDIT</code> flag will be 138 <span class="bold"><strong>excluively latched</strong></span> until 139 a subsequent call to <a class="xref" href="mempput.html" title="DbMpoolFile::put()">DbMpoolFile::put()</a>. 140 </p> 141 </li> 142 <li> 143 <p><a id="fget_DB_MPOOL_LAST"></a> 144 <code class="literal">DB_MPOOL_LAST</code> 145 </p> 146 <p> 147 Return the last page of the source file, and copy its page number into 148 the memory location to which <span class="bold"><strong>pgnoaddr</strong></span> 149 refers. 150 </p> 151 </li> 152 <li> 153 <p><a id="mpoolfget_DB_MPOOL_NEW"></a> 154 <code class="literal">DB_MPOOL_NEW</code> 155 </p> 156 <p> 157 Create a new page in the file, and copy its page number into the 158 memory location to which <span class="bold"><strong>pgnoaddr</strong></span> 159 refers. In this case, the <code class="literal">pgin_fcn</code> callback, if specified on 160 <a class="xref" href="mempregister.html" title="DbEnv::memp_register()">DbEnv::memp_register()</a>, is 161 <span class="bold"><strong>not</strong></span> called. 162 </p> 163 </li> 164 </ul> 165 </div> 166 <p> 167 The <code class="literal">DB_MPOOL_CREATE</code>, <code class="literal">DB_MPOOL_LAST</code>, and 168 <code class="literal">DB_MPOOL_NEW</code> flags are mutually exclusive. 169 </p> 170 </div> 171 <div class="sect3" lang="en" xml:lang="en"> 172 <div class="titlepage"> 173 <div> 174 <div> 175 <h4 class="title"><a id="id1694103"></a>pagep</h4> 176 </div> 177 </div> 178 </div> 179 <p> 180 The <span class="bold"><strong>pagep</strong></span> parameter references memory 181 into which a pointer to the returned page is copied. 182 </p> 183 </div> 184 <div class="sect3" lang="en" xml:lang="en"> 185 <div class="titlepage"> 186 <div> 187 <div> 188 <h4 class="title"><a id="id1694212"></a>pgnoaddr</h4> 189 </div> 190 </div> 191 </div> 192 <p> 193 If the <span class="bold"><strong>flags</strong></span> parameter is set to 194 <code class="literal">DB_MPOOL_LAST</code> or <code class="literal">DB_MPOOL_NEW</code>, the 195 page number of the created page is copied into the memory location to 196 which the <span class="bold"><strong>pgnoaddr</strong></span> parameter refers. 197 Otherwise, the <span class="bold"><strong>pgnoaddr</strong></span> parameter is the 198 page to create or retrieve. 199 </p> 200 <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> 201 <h3 class="title">Note</h3> 202 <p> 203 Page numbers begin at 0; that is, the first page in the file is page number 0, 204 not page number 1. 205 </p> 206 </div> 207 </div> 208 <div class="sect3" lang="en" xml:lang="en"> 209 <div class="titlepage"> 210 <div> 211 <div> 212 <h4 class="title"><a id="id1694152"></a>txnid</h4> 213 </div> 214 </div> 215 </div> 216 <p> 217 If the operation is part of an application-specified transaction, the 218 <span class="bold"><strong>txnid</strong></span> parameter is a transaction 219 handle returned from <a class="xref" href="txnbegin.html" title="DbEnv::txn_begin()">DbEnv::txn_begin()</a>; 220 otherwise NULL. A transaction is required if the file is open for multiversion 221 concurrency control by passing 222 <a class="link" href="dbopen.html#dbopen_DB_MULTIVERSION">DB_MULTIVERSION</a> 223 to 224 <a class="xref" href="mempfopen.html" title="DbMpoolFile::open()">DbMpoolFile::open()</a> 225 and the DB_MPOOL_DIRTY, DB_MPOOL_CREATE or DB_MPOOL_NEW flags were 226 specified. Otherwise it is ignored. 227 </p> 228 </div> 229 </div> 230 <div class="sect2" lang="en" xml:lang="en"> 231 <div class="titlepage"> 232 <div> 233 <div> 234 <h3 class="title"><a id="id1694225"></a>Errors</h3> 235 </div> 236 </div> 237 </div> 238 <p> 239 The <code class="methodname">DbMpoolFile::get()</code> <span> 240 241 <span> 242 method may fail and throw a <a class="link" href="dbexception.html" title="Chapter 6. The DbException Class">DbException</a> 243 exception, encapsulating one of the following non-zero errors, or return one 244 of the following non-zero errors: 245 </span> 246 </span> 247 </p> 248 <div class="sect3" lang="en" xml:lang="en"> 249 <div class="titlepage"> 250 <div> 251 <div> 252 <h4 class="title"><a id="id1693772"></a>EACCES</h4> 253 </div> 254 </div> 255 </div> 256 <p> 257 The <code class="literal">DB_MPOOL_DIRTY</code> or 258 <code class="literal">DB_MPOOL_EDIT</code> flag was set and the source file was 259 not opened for writing. 260 </p> 261 </div> 262 <div class="sect3" lang="en" xml:lang="en"> 263 <div class="titlepage"> 264 <div> 265 <div> 266 <h4 class="title"><a id="id1693858"></a>EAGAIN</h4> 267 </div> 268 </div> 269 </div> 270 <p> 271 The page reference count has overflowed. (This should never happen 272 unless there is a bug in the application.) 273 </p> 274 </div> 275 <div class="sect3" lang="en" xml:lang="en"> 276 <div class="titlepage"> 277 <div> 278 <div> 279 <h4 class="title"><a id="id1693749"></a>EINVAL</h4> 280 </div> 281 </div> 282 </div> 283 <p> 284 If the <code class="literal">DB_MPOOL_NEW</code> flag was set, and the source 285 file was not opened for writing; more than one of 286 <code class="literal">DB_MPOOL_CREATE</code>, <code class="literal">DB_MPOOL_LAST</code>, 287 and <code class="literal">DB_MPOOL_NEW</code> was set; or if an invalid flag 288 value or parameter was specified. 289 </p> 290 </div> 291 <div class="sect3" lang="en" xml:lang="en"> 292 <div class="titlepage"> 293 <div> 294 <div> 295 <h4 class="title"><a id="id1694352"></a>DB_LOCK_DEADLOCK</h4> 296 </div> 297 </div> 298 </div> 299 <p> 300 For transactions configured with 301 <a class="link" href="txnbegin.html#txnbegin_DB_TXN_SNAPSHOT">DB_TXN_SNAPSHOT</a>, 302 the page has been modified since the transaction began. 303 </p> 304 </div> 305 <div class="sect3" lang="en" xml:lang="en"> 306 <div class="titlepage"> 307 <div> 308 <div> 309 <h4 class="title"><a id="id1694315"></a>ENOMEM</h4> 310 </div> 311 </div> 312 </div> 313 <p> 314 The cache is full, and no more pages will fit in the cache. 315 </p> 316 </div> 317 </div> 318 <div class="sect2" lang="en" xml:lang="en"> 319 <div class="titlepage"> 320 <div> 321 <div> 322 <h3 class="title"><a id="id1694139"></a>Class</h3> 323 </div> 324 </div> 325 </div> 326 <p> 327 <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> 328 </p> 329 </div> 330 <div class="sect2" lang="en" xml:lang="en"> 331 <div class="titlepage"> 332 <div> 333 <div> 334 <h3 class="title"><a id="id1693781"></a>See Also</h3> 335 </div> 336 </div> 337 </div> 338 <p> 339 <a class="xref" href="memp.html#memplist" title="Memory Pools and Related Methods">Memory Pools and Related Methods</a> 340 </p> 341 </div> 342 </div> 343 <div class="navfooter"> 344 <hr /> 345 <table width="100%" summary="Navigation footer"> 346 <tr> 347 <td width="40%" align="left"><a accesskey="p" href="mempfclose.html">Prev</a> </td> 348 <td width="20%" align="center"> 349 <a accesskey="u" href="memp.html">Up</a> 350 </td> 351 <td width="40%" align="right"> <a accesskey="n" href="mempfopen.html">Next</a></td> 352 </tr> 353 <tr> 354 <td width="40%" align="left" valign="top">DbMpoolFile::close() </td> 355 <td width="20%" align="center"> 356 <a accesskey="h" href="index.html">Home</a> 357 </td> 358 <td width="40%" align="right" valign="top"> DbMpoolFile::open()</td> 359 </tr> 360 </table> 361 </div> 362 </body> 363</html> 364