docs/programmer_reference/stl.html

   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>Chapter 7. Standard Template Library API</title>
   7     <link rel="stylesheet" href="gettingStarted.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 Programmer's Reference Guide" />
  10     <link rel="up" href="index.html" title="Berkeley DB Programmer's Reference Guide" />
  11     <link rel="prev" href="csharp.html" title="Chapter 6. C# API" />
  12     <link rel="next" href="stl_usecase.html" title="Dbstl typical use cases" />
  13   </head>
  14   <body>
  15     <div xmlns="" class="navheader">
  16       <div class="libver">
  17         <p>Library Version 11.2.5.3</p>
  18       </div>
  19       <table width="100%" summary="Navigation header">
  20         <tr>
  21           <th colspan="3" align="center">Chapter 7. Standard Template Library API</th>
  22         </tr>
  23         <tr>
  24           <td width="20%" align="left"><a accesskey="p" href="csharp.html">Prev</a> </td>
  25           <th width="60%" align="center"> </th>
  26           <td width="20%" align="right"> <a accesskey="n" href="stl_usecase.html">Next</a></td>
  27         </tr>
  28       </table>
  29       <hr />
  30     </div>
  31     <div class="chapter" lang="en" xml:lang="en">
  32       <div class="titlepage">
  33         <div>
  34           <div>
  35             <h2 class="title"><a id="stl"></a>Chapter 7. Standard Template Library API</h2>
  36           </div>
  37         </div>
  38       </div>
  39       <div class="toc">
  40         <p>
  41           <b>Table of Contents</b>
  42         </p>
  43         <dl>
  44           <dt>
  45             <span class="sect1">
  46               <a href="stl.html#stl_intro">Dbstl introduction</a>
  47             </span>
  48           </dt>
  49           <dd>
  50             <dl>
  51               <dt>
  52                 <span class="sect2">
  53                   <a href="stl.html#stl_intro_stdcompat">Standards compatible</a>
  54                 </span>
  55               </dt>
  56               <dt>
  57                 <span class="sect2">
  58                   <a href="stl.html#stl_intro_performance">Performance overhead</a>
  59                 </span>
  60               </dt>
  61               <dt>
  62                 <span class="sect2">
  63                   <a href="stl.html#stl_intro_portability">Portability</a>
  64                 </span>
  65               </dt>
  66             </dl>
  67           </dd>
  68           <dt>
  69             <span class="sect1">
  70               <a href="stl_usecase.html">Dbstl typical use cases</a>
  71             </span>
  72           </dt>
  73           <dt>
  74             <span class="sect1">
  75               <a href="stl_examples.html">Dbstl examples</a>
  76             </span>
  77           </dt>
  78           <dt>
  79             <span class="sect1">
  80               <a href="stl_db_usage.html">Berkeley DB configuration</a>
  81             </span>
  82           </dt>
  83           <dd>
  84             <dl>
  85               <dt>
  86                 <span class="sect2">
  87                   <a href="stl_db_usage.html#idp1202384">Registering database and environment handles</a>
  88                 </span>
  89               </dt>
  90               <dt>
  91                 <span class="sect2">
  92                   <a href="stl_db_usage.html#idp1225928">Truncate requirements</a>
  93                 </span>
  94               </dt>
  95               <dt>
  96                 <span class="sect2">
  97                   <a href="stl_db_usage.html#idp1236168">Auto commit support</a>
  98                 </span>
  99               </dt>
 100               <dt>
 101                 <span class="sect2">
 102                   <a href="stl_db_usage.html#idp1239792">Database and environment identity checks</a>
 103                 </span>
 104               </dt>
 105               <dt>
 106                 <span class="sect2">
 107                   <a href="stl_db_usage.html#idp1236512">Products, constructors and configurations</a>
 108                 </span>
 109               </dt>
 110             </dl>
 111           </dd>
 112           <dt>
 113             <span class="sect1">
 114               <a href="stl_db_advanced_usage.html">Using advanced Berkeley DB features with dbstl</a>
 115             </span>
 116           </dt>
 117           <dd>
 118             <dl>
 119               <dt>
 120                 <span class="sect2">
 121                   <a href="stl_db_advanced_usage.html#idp1232296">Using bulk retrieval iterators</a>
 122                 </span>
 123               </dt>
 124               <dt>
 125                 <span class="sect2">
 126                   <a href="stl_db_advanced_usage.html#idp1232520">Using the DB_RMW flag</a>
 127                 </span>
 128               </dt>
 129               <dt>
 130                 <span class="sect2">
 131                   <a href="stl_db_advanced_usage.html#idp1199288">Using secondary index database and secondary containers</a>
 132                 </span>
 133               </dt>
 134             </dl>
 135           </dd>
 136           <dt>
 137             <span class="sect1">
 138               <a href="stl_txn_usage.html">Using transactions in dbstl</a>
 139             </span>
 140           </dt>
 141           <dt>
 142             <span class="sect1">
 143               <a href="stl_mt_usage.html">Using dbstl in multithreaded applications</a>
 144             </span>
 145           </dt>
 146           <dt>
 147             <span class="sect1">
 148               <a href="stl_primitive_rw.html">Working with primitive types </a>
 149             </span>
 150           </dt>
 151           <dd>
 152             <dl>
 153               <dt>
 154                 <span class="sect2">
 155                   <a href="stl_primitive_rw.html#idp1288424">Storing strings</a>
 156                 </span>
 157               </dt>
 158             </dl>
 159           </dd>
 160           <dt>
 161             <span class="sect1">
 162               <a href="stl_complex_rw.html">Store and Retrieve data or objects of complex types </a>
 163             </span>
 164           </dt>
 165           <dd>
 166             <dl>
 167               <dt>
 168                 <span class="sect2">
 169                   <a href="stl_complex_rw.html#idp1279008">Storing varying length objects</a>
 170                 </span>
 171               </dt>
 172               <dt>
 173                 <span class="sect2">
 174                   <a href="stl_complex_rw.html#idp1278616">Storing arbitrary sequences</a>
 175                 </span>
 176               </dt>
 177               <dt>
 178                 <span class="sect2">
 179                   <a href="stl_complex_rw.html#idp1344912">Notes</a>
 180                 </span>
 181               </dt>
 182             </dl>
 183           </dd>
 184           <dt>
 185             <span class="sect1">
 186               <a href="stl_persistence.html">Dbstl persistence</a>
 187             </span>
 188           </dt>
 189           <dd>
 190             <dl>
 191               <dt>
 192                 <span class="sect2">
 193                   <a href="stl_persistence.html#directdbget">Direct database get</a>
 194                 </span>
 195               </dt>
 196               <dt>
 197                 <span class="sect2">
 198                   <a href="stl_persistence.html#chg_persistence">Change persistence</a>
 199                 </span>
 200               </dt>
 201               <dt>
 202                 <span class="sect2">
 203                   <a href="stl_persistence.html#obj_life_persistence">Object life time and persistence </a>
 204                 </span>
 205               </dt>
 206             </dl>
 207           </dd>
 208           <dt>
 209             <span class="sect1">
 210               <a href="stl_container_specific.html">Dbstl container specific notes</a>
 211             </span>
 212           </dt>
 213           <dd>
 214             <dl>
 215               <dt>
 216                 <span class="sect2">
 217                   <a href="stl_container_specific.html#idp1313840">db_vector specific notes</a>
 218                 </span>
 219               </dt>
 220               <dt>
 221                 <span class="sect2">
 222                   <a href="stl_container_specific.html#idp1381768">Associative container specific notes</a>
 223                 </span>
 224               </dt>
 225             </dl>
 226           </dd>
 227           <dt>
 228             <span class="sect1">
 229               <a href="stl_efficienct_use.html">Using dbstl efficiently</a>
 230             </span>
 231           </dt>
 232           <dd>
 233             <dl>
 234               <dt>
 235                 <span class="sect2">
 236                   <a href="stl_efficienct_use.html#idp1350664">Using iterators efficiently</a>
 237                 </span>
 238               </dt>
 239               <dt>
 240                 <span class="sect2">
 241                   <a href="stl_efficienct_use.html#idp1350448">Using containers efficiently</a>
 242                 </span>
 243               </dt>
 244             </dl>
 245           </dd>
 246           <dt>
 247             <span class="sect1">
 248               <a href="stl_memory_mgmt.html">Dbstl memory management</a>
 249             </span>
 250           </dt>
 251           <dd>
 252             <dl>
 253               <dt>
 254                 <span class="sect2">
 255                   <a href="stl_memory_mgmt.html#idp1384984">Freeing memory</a>
 256                 </span>
 257               </dt>
 258               <dt>
 259                 <span class="sect2">
 260                   <a href="stl_memory_mgmt.html#idp1389512">Type specific notes</a>
 261                 </span>
 262               </dt>
 263             </dl>
 264           </dd>
 265           <dt>
 266             <span class="sect1">
 267               <a href="stl_misc.html">Dbstl miscellaneous notes</a>
 268             </span>
 269           </dt>
 270           <dd>
 271             <dl>
 272               <dt>
 273                 <span class="sect2">
 274                   <a href="stl_misc.html#idp1407848">Special notes about trivial methods</a>
 275                 </span>
 276               </dt>
 277               <dt>
 278                 <span class="sect2">
 279                   <a href="stl_misc.html#idp1421568">Using correct container and iterator public types</a>
 280                 </span>
 281               </dt>
 282             </dl>
 283           </dd>
 284           <dt>
 285             <span class="sect1">
 286               <a href="stl_known_issues.html">Dbstl known issues</a>
 287             </span>
 288           </dt>
 289         </dl>
 290       </div>
 291       <div class="sect1" lang="en" xml:lang="en">
 292         <div class="titlepage">
 293           <div>
 294             <div>
 295               <h2 class="title" style="clear: both"><a id="stl_intro"></a>Dbstl introduction</h2>
 296             </div>
 297           </div>
 298         </div>
 299         <div class="toc">
 300           <dl>
 301             <dt>
 302               <span class="sect2">
 303                 <a href="stl.html#stl_intro_stdcompat">Standards compatible</a>
 304               </span>
 305             </dt>
 306             <dt>
 307               <span class="sect2">
 308                 <a href="stl.html#stl_intro_performance">Performance overhead</a>
 309               </span>
 310             </dt>
 311             <dt>
 312               <span class="sect2">
 313                 <a href="stl.html#stl_intro_portability">Portability</a>
 314               </span>
 315             </dt>
 316           </dl>
 317         </div>
 318         <p>
 319     Dbstl is a C++ STL style API that provides for Berkeley DB usage.  It
 320     allows for the storage and retrieval of data/objects of any type using
 321     Berkeley DB databases, but with an interface that mimics that of C++
 322     STL containers. Dbstl provides access to all of the functionality of
 323     Berkeley DB available via this STL-style API.
 324 </p>
 325         <p>
 326     With proper configuration, dbstl is able to store/retrieve any complex
 327     data types. There is no need to perform repetitive marshalling and
 328     unmarshalling of data. Dbstl also properly manages the life-cycle of
 329     all Berkeley DB structures and objects. All example methods referred to in this chapter
 330 can be found in the StlAdvancedFeaturesExample class in the $DbSrc/examples_stl/StlAdvancedFeatures.cpp file, and you can
 331 build the example in $DbSrc/build_unix directory like this:
 332 make exstl_advancedfeatures,
 333 where DbSrc is the source directory for Berkeley DB.
 334 </p>
 335         <div class="sect2" lang="en" xml:lang="en">
 336           <div class="titlepage">
 337             <div>
 338               <div>
 339                 <h3 class="title"><a id="stl_intro_stdcompat"></a>Standards compatible</h3>
 340               </div>
 341             </div>
 342           </div>
 343           <p>
 344     Dbstl is composed of many container and iterator class templates. These
 345     containers and iterators correspond exactly to each container and
 346     iterator available in the C++ STL API, including identical sets of
 347     methods. This allows existing algorithms, functions and
 348     container-adapters for C++ STL to use dbstl containers through its
 349     standard iterators. This means that existing STL code can manipulate
 350     Berkeley DB databases. As a result, existing C++ STL code can very
 351     easily use dbstl to gain persistence and transaction guarantees.
 352 </p>
 353         </div>
 354         <div class="sect2" lang="en" xml:lang="en">
 355           <div class="titlepage">
 356             <div>
 357               <div>
 358                 <h3 class="title"><a id="stl_intro_performance"></a>Performance overhead</h3>
 359               </div>
 360             </div>
 361           </div>
 362           <p>
 363     Because dbstl uses C++ template technologies, its performance overhead
 364     is minimal.
 365 </p>
 366           <p>
 367     The dbstl API performs almost equally to the C API, as measured by two
 368     different implementations of the TPC-B benchmark:
 369     <code class="literal">ex_tpcb</code> and <code class="literal">exstl_tpcb</code>.
 370 </p>
 371         </div>
 372         <div class="sect2" lang="en" xml:lang="en">
 373           <div class="titlepage">
 374             <div>
 375               <div>
 376                 <h3 class="title"><a id="stl_intro_portability"></a>Portability</h3>
 377               </div>
 378             </div>
 379           </div>
 380           <p>
 381     The degree to which dbstl is portable to a new platform is determined
 382     by whether Berkeley DB is available on the platform, as well as whether
 383     an appropriate C++ compiler is available on the platform.
 384 </p>
 385           <p>
 386     For information on porting Berkeley DB to new platforms, see the
 387     <em class="citetitle">Berkeley DB Porting Guide</em>.
 388 </p>
 389           <p>
 390     Almost all the advanced C++ template features are used in dbstl, including:
 391 </p>
 392           <div class="itemizedlist">
 393             <ul type="disc">
 394               <li>
 395                 <p>
 396                 member function templates
 397             </p>
 398               </li>
 399               <li>
 400                 <p>
 401                 member function template overloads
 402             </p>
 403               </li>
 404               <li>
 405                 <p>
 406                 partial specialization
 407             </p>
 408               </li>
 409               <li>
 410                 <p>
 411                 default template parameters.
 412             </p>
 413               </li>
 414             </ul>
 415           </div>
 416           <p>
 417         For this reason, you need a standards-compatible C++ compiler to
 418         build dbstl. As of this writing, the following compilers are known
 419         to build dbstl successfully:
 420     </p>
 421           <div class="itemizedlist">
 422             <ul type="disc">
 423               <li>
 424                 <p>
 425                 MSVC8
 426             </p>
 427               </li>
 428               <li>
 429                 <p>
 430                 gcc3.4.4 and above
 431             </p>
 432               </li>
 433               <li>
 434                 <p>
 435                 Intel C++ 9 and above
 436             </p>
 437               </li>
 438             </ul>
 439           </div>
 440           <p>
 441         For *nix platforms, if you can successfully configure your Berkeley
 442         DB build script with <code class="literal">--enable-stl</code>, then you
 443         should be able to successfully build dbstl library and application
 444         code using it.
 445     </p>
 446           <p>
 447         Besides its own test suite, dbstl has also been tested against,
 448         and passes, the following test suites:
 449     </p>
 450           <div class="itemizedlist">
 451             <ul type="disc">
 452               <li>
 453                 <p>
 454                 MS STL test suite
 455             </p>
 456               </li>
 457               <li>
 458                 <p>
 459                 SGI STL test suite
 460             </p>
 461               </li>
 462             </ul>
 463           </div>
 464         </div>
 465       </div>
 466     </div>
 467     <div class="navfooter">
 468       <hr />
 469       <table width="100%" summary="Navigation footer">
 470         <tr>
 471           <td width="40%" align="left"><a accesskey="p" href="csharp.html">Prev</a> </td>
 472           <td width="20%" align="center"> </td>
 473           <td width="40%" align="right"> <a accesskey="n" href="stl_usecase.html">Next</a></td>
 474         </tr>
 475         <tr>
 476           <td width="40%" align="left" valign="top">Chapter 6. C# API </td>
 477           <td width="20%" align="center">
 478             <a accesskey="h" href="index.html">Home</a>
 479           </td>
 480           <td width="40%" align="right" valign="top"> Dbstl typical use cases</td>
 481         </tr>
 482       </table>
 483     </div>
 484   </body>
 485 </html>