diff options
Diffstat (limited to 'docs/programmer_reference/stl_db_advanced_usage.html')
| -rw-r--r-- | docs/programmer_reference/stl_db_advanced_usage.html | 243 |
1 files changed, 132 insertions, 111 deletions
diff --git a/docs/programmer_reference/stl_db_advanced_usage.html b/docs/programmer_reference/stl_db_advanced_usage.html index 6405dded..9046bdee 100644 --- a/docs/programmer_reference/stl_db_advanced_usage.html +++ b/docs/programmer_reference/stl_db_advanced_usage.html @@ -14,11 +14,12 @@ <body> <div xmlns="" class="navheader"> <div class="libver"> - <p>Library Version 11.2.5.3</p> + <p>Library Version 12.1.6.1</p> </div> <table width="100%" summary="Navigation header"> <tr> - <th colspan="3" align="center">Using advanced Berkeley DB features with dbstl</th> + <th colspan="3" align="center">Using advanced Berkeley DB + features with dbstl</th> </tr> <tr> <td width="20%" align="left"><a accesskey="p" href="stl_db_usage.html">Prev</a> </td> @@ -32,7 +33,8 @@ <div class="titlepage"> <div> <div> - <h2 class="title" style="clear: both"><a id="stl_db_advanced_usage"></a>Using advanced Berkeley DB features with dbstl</h2> + <h2 class="title" style="clear: both"><a id="stl_db_advanced_usage"></a>Using advanced Berkeley DB + features with dbstl</h2> </div> </div> </div> @@ -40,158 +42,177 @@ <dl> <dt> <span class="sect2"> - <a href="stl_db_advanced_usage.html#idp1232296">Using bulk retrieval iterators</a> + <a href="stl_db_advanced_usage.html#idp672128">Using bulk retrieval iterators</a> </span> </dt> <dt> <span class="sect2"> - <a href="stl_db_advanced_usage.html#idp1232520">Using the DB_RMW flag</a> + <a href="stl_db_advanced_usage.html#idp794736">Using the DB_RMW flag</a> </span> </dt> <dt> <span class="sect2"> - <a href="stl_db_advanced_usage.html#idp1199288">Using secondary index database and secondary containers</a> + <a href="stl_db_advanced_usage.html#idp773392">Using secondary index database and secondary containers</a> </span> </dt> </dl> </div> <p> - This section describes advanced Berkeley DB features that are - available through dbstl. + This section describes advanced Berkeley DB features that + are available through dbstl. </p> <div class="sect2" lang="en" xml:lang="en"> <div class="titlepage"> <div> <div> - <h3 class="title"><a id="idp1232296"></a>Using bulk retrieval iterators</h3> + <h3 class="title"><a id="idp672128"></a>Using bulk retrieval iterators</h3> </div> </div> </div> <p> - Bulk retrieval is an optimization option for const iterators and - nonconst but read-only iterators. Bulk retrieval can minimize the - number of database accesses performed by your application. It does this - by reading multiple entries at a time, which reduces read overhead. - Note that non-sequential reads will benefit less from, or even be hurt - by, this behavior, because it might result in unneeded data being read - from the database. Also, non-serializable reads may read obsolete - data, because part of the data read from the bulk read buffer may have - been updated since the retrieval. -</p> + Bulk retrieval is an optimization option for const + iterators and nonconst but read-only iterators. Bulk + retrieval can minimize the number of database accesses + performed by your application. It does this by reading + multiple entries at a time, which reduces read overhead. + Note that non-sequential reads will benefit less from, or + even be hurt by, this behavior, because it might result in + unneeded data being read from the database. Also, + non-serializable reads may read obsolete data, because + part of the data read from the bulk read buffer may have + been updated since the retrieval. + </p> <p> - When using the default transaction isolation, iterators will perform - serializable reads. In this situation, the bulk-retrieved data cannot - be updated until the iterator's cursor is closed. -</p> + When using the default transaction isolation, iterators + will perform serializable reads. In this situation, the + bulk-retrieved data cannot be updated until the iterator's + cursor is closed. + </p> <p> - Iterators using a different isolation levels, such as - <a href="../api_reference/C/dbcget.html#dbcget_DB_READ_COMMITTED" class="olink">DB_READ_COMMITTED</a> or <a href="../api_reference/C/dbopen.html#dbopen_DB_READ_UNCOMMITTED" class="olink">DB_READ_UNCOMMITTED</a> will not perform - serializable reads. The same is true for any iterators that do not use - transactions. -</p> + Iterators using a different isolation levels, such as + <a href="../api_reference/C/dbcget.html#dbcget_DB_READ_COMMITTED" class="olink">DB_READ_COMMITTED</a> or <a href="../api_reference/C/dbopen.html#dbopen_DB_READ_UNCOMMITTED" class="olink">DB_READ_UNCOMMITTED</a> will not + perform serializable reads. The same is true for any + iterators that do not use transactions. + </p> + <p> + A bulk retrieval iterator can only move in a singled + direction, from beginning to end. This means that + iterators only support operator++, and reverse iterators + only support operator--. + </p> + <p> + Iterator objects that use bulk retrieval might contain + hundreds of kilobytes of data, which makes copying the + iterator object an expensive operation. If possible, use + ++iterator rather than iterator++. This can save a useless + copy construction of the iterator, as well as an + unnecessary dup/close of the cursor. + </p> + <p> + You can configure bulk retrieval for each container + using both in the const and non-const version of the + <code class="methodname">begin()</code> method. The non-const + version of <code class="methodname">begin()</code> will return a + read-only cursor. Note that read-only means something + different in C++ than it does when referring to an + iterator. The latter only means that it cannot be used to + update the database. + </p> + <p> + To configure the bulk retrieval buffer for an iterator + when calling the <code class="methodname">begin()</code> method, + use the + <code class="function">BulkRetrievelItrOpt::bulk_retrieval(u_int32_t + bulk_buffer_size)</code> function. + </p> <p> - A bulk retrieval iterator can only move in a singled direction, from - beginning to end. This means that iterators only support operator++, - and reverse iterators only support operator--. -</p> - <p> - Iterator objects that use bulk retrieval might contain hundreds of - kilobytes of data, which makes copying the iterator object an expensive - operation. If possible, use ++iterator rather than iterator++. This - can save a useless copy construction of the iterator, as well as an - unnecessary dup/close of the cursor. -</p> - <p> - You can configure bulk retrieval for each container using both in the - const and non-const version of the <code class="methodname">begin()</code> - method. The non-const version of <code class="methodname">begin()</code> will - return a read-only cursor. Note that read-only means something - different in C++ than it does when referring to an iterator. The latter - only means that it cannot be used to update the database. -</p> - <p> - To configure the bulk retrieval buffer for an iterator when calling the - <code class="methodname">begin()</code> method, use the - <code class="function">BulkRetrievelItrOpt::bulk_retrieval(u_int32_t bulk_buffer_size)</code> - function. -</p> - <p> - If you move a <code class="classname">db_vector_iterator</code> randomly rather - than sequentially, then dbstl will not perform bulk retrieval because - there is little performance gain from bulk retrieval in such an access - pattern. -</p> - <p> - You can call <code class="function">iterator::set_bulk_buffer()</code> to modify - the iterator's bulk buffer size. Note that once bulk read is enabled, - only the bulk buffer size can be modified. This means that bulk read - cannot be disabled. Also, if bulk read was not enabled when you created - the iterator, you can't enable it after creation. -</p> - <p> - Example code using this feature can be found in the - <code class="methodname">StlAdvancedFeaturesExample::bulk_retrieval_read()</code> method. -</p> + If you move a <code class="classname">db_vector_iterator</code> + randomly rather than sequentially, then dbstl will not + perform bulk retrieval because there is little performance + gain from bulk retrieval in such an access pattern. + </p> + <p> + You can call + <code class="function">iterator::set_bulk_buffer()</code> to + modify the iterator's bulk buffer size. Note that once + bulk read is enabled, only the bulk buffer size can be + modified. This means that bulk read cannot be disabled. + Also, if bulk read was not enabled when you created the + iterator, you can't enable it after creation. + </p> + <p> + Example code using this feature can be found in the + <code class="methodname">StlAdvancedFeaturesExample::bulk_retrieval_read()</code> + method. + </p> </div> <div class="sect2" lang="en" xml:lang="en"> <div class="titlepage"> <div> <div> - <h3 class="title"><a id="idp1232520"></a>Using the DB_RMW flag</h3> + <h3 class="title"><a id="idp794736"></a>Using the DB_RMW flag</h3> </div> </div> </div> <p> - The <a href="../api_reference/C/dbcget.html#dbcget_DB_RMW" class="olink">DB_RMW</a> flag is an optimization for non-const (read-write) - iterators. This flag causes the underlying cursor to acquire a write - lock when reading so as to avoid deadlocks. Passing - <code class="function">ReadModifyWriteOption::read_modify_write()</code> to a - container's <code class="methodname">begin()</code> method creates an iterator - whose cursor has this behavior. -</p> + The <a href="../api_reference/C/dbcget.html#dbcget_DB_RMW" class="olink">DB_RMW</a> flag is an optimization for non-const + (read-write) iterators. This flag causes the underlying + cursor to acquire a write lock when reading so as to avoid + deadlocks. Passing + <code class="function">ReadModifyWriteOption::read_modify_write()</code> + to a container's <code class="methodname">begin()</code> method + creates an iterator whose cursor has this behavior. + </p> </div> <div class="sect2" lang="en" xml:lang="en"> <div class="titlepage"> <div> <div> - <h3 class="title"><a id="idp1199288"></a>Using secondary index database and secondary containers</h3> + <h3 class="title"><a id="idp773392"></a>Using secondary index database and secondary containers</h3> </div> </div> </div> + <p> + Because duplicate keys are forbidden in primary + databases, only <code class="classname">db_map</code>, + <code class="classname">db_set</code> and + <code class="classname">db_vector</code> are allowed to use + primary databases. For this reason, they are called + <span class="bold"><strong>primary containers</strong></span>. A + secondary database that supports duplicate keys can be + used with <code class="classname">db_multimap</code> containers. + These are called <span class="bold"><strong>secondary + containers</strong></span>. Finally, a secondary database + that forbids duplicate keys can back a + <code class="classname">db_map</code> container. + </p> + <p> + The <span class="bold"><strong>data_type</strong></span> of this + <code class="classname">db_multimap</code> secondary container + is the <span class="bold"><strong>data_type</strong></span> for the + primary container. For example, a + <code class="classname">db_map<int, Person></code> + object where the <code class="classname">Person</code> class has + an <code class="literal">age</code> property of type + <code class="literal">size_t</code>, a + <code class="classname">db_multimap<size_t, + Person></code> using a secondary database + allows access to a person by age. + </p> <p> - Because duplicate keys are forbidden in primary databases, only - <code class="classname">db_map</code>, <code class="classname">db_set</code> and - <code class="classname">db_vector</code> are allowed to use primary databases. - For this reason, they are called - <span class="bold"><strong>primary containers</strong></span>. - A secondary database that supports duplicate keys can be used with - <code class="classname">db_multimap</code> containers. These are called - <span class="bold"><strong>secondary containers</strong></span>. Finally, a - secondary database that forbids duplicate keys can back a - <code class="classname">db_map</code> container. -</p> - <p> - The <span class="bold"><strong>data_type</strong></span> of this - <code class="classname">db_multimap</code> secondary container is the - <span class="bold"><strong>data_type</strong></span> for the primary container. For - example, a <code class="classname">db_map<int, Person></code> object - where the <code class="classname">Person</code> class has an - <code class="literal">age</code> property of type <code class="literal">size_t</code>, a - <code class="classname">db_multimap<size_t, Person></code> using a - secondary database allows access to a person by age. -</p> - <p> - - A container created from a secondary database can only be used to - iterate, search or delete. It can not be used to update or insert. - While dbstl does expose the update and insert operations, Berkeley DB - does not, and an exception will be thrown if attempts are made to - insert objects into or update objects of a secondary container. -</p> + A container created from a secondary database can only + be used to iterate, search or delete. It can not be used + to update or insert. While dbstl does expose the update + and insert operations, Berkeley DB does not, and an + exception will be thrown if attempts are made to insert + objects into or update objects of a secondary container. + </p> <p> - Example code demonstrating this feature is available in the - <code class="methodname">StlAdvancedFeaturesExample::secondary_containers()</code> method. -</p> + Example code demonstrating this feature is available in + the + <code class="methodname">StlAdvancedFeaturesExample::secondary_containers()</code> + method. + </p> </div> </div> <div class="navfooter"> |