Chapter 7. Standard Template Library API

Table of Contents

Dbstl introduction
Standards compatible
Performance overhead
Portability
Dbstl typical use cases
Dbstl examples
Berkeley DB configuration
Registering database and environment handles
Truncate requirements
Auto commit support
Database and environment identity checks
Products, constructors and configurations
Using advanced Berkeley DB features with dbstl
Using bulk retrieval iterators
Using the DB_RMW flag
Using secondary index database and secondary containers
Using transactions in dbstl
Using dbstl in multithreaded applications
Working with primitive types
Storing strings
Store and Retrieve data or objects of complex types
Storing varying length objects
Storing arbitrary sequences
Notes
Dbstl persistence
Direct database get
Change persistence
Object life time and persistence
Dbstl container specific notes
db_vector specific notes
Associative container specific notes
Using dbstl efficiently
Using iterators efficiently
Using containers efficiently
Dbstl memory management
Freeing memory
Type specific notes
Dbstl miscellaneous notes
Special notes about trivial methods
Using correct container and iterator public types
Dbstl known issues

Dbstl introduction

Dbstl is a C++ STL style API that provides for Berkeley DB usage. It allows for the storage and retrieval of data/objects of any type using Berkeley DB databases, but with an interface that mimics that of C++ STL containers. Dbstl provides access to all of the functionality of Berkeley DB available via this STL-style API.

With proper configuration, dbstl is able to store/retrieve any complex data types. There is no need to perform repetitive marshalling and unmarshalling of data. Dbstl also properly manages the life-cycle of all Berkeley DB structures and objects. All example methods referred to in this chapter can be found in the StlAdvancedFeaturesExample class in the $DbSrc/examples/stl/StlAdvancedFeatures.cpp file, and you can build the example in $DbSrc/build_unix directory like this: make exstl_advancedfeatures, where DbSrc is the source directory for Berkeley DB.

Standards compatible

Dbstl is composed of many container and iterator class templates. These containers and iterators correspond exactly to each container and iterator available in the C++ STL API, including identical sets of methods. This allows existing algorithms, functions and container-adapters for C++ STL to use dbstl containers through its standard iterators. This means that existing STL code can manipulate Berkeley DB databases. As a result, existing C++ STL code can very easily use dbstl to gain persistence and transaction guarantees.

Performance overhead

Because dbstl uses C++ template technologies, its performance overhead is minimal.

The dbstl API performs almost equally to the C API, as measured by two different implementations of the TPC-B benchmark: ex_tpcb and exstl_tpcb.

Portability

The degree to which dbstl is portable to a new platform is determined by whether Berkeley DB is available on the platform, as well as whether an appropriate C++ compiler is available on the platform.

For information on porting Berkeley DB to new platforms, see the Berkeley DB Porting Guide.

Almost all the advanced C++ template features are used in dbstl, including:

  • member function templates

  • member function template overloads

  • partial specialization

  • default template parameters.

For this reason, you need a standards-compatible C++ compiler to build dbstl. As of this writing, the following compilers are known to build dbstl successfully:

  • MSVC8

  • gcc3.4.4 and above

  • Intel C++ 9 and above

For *nix platforms, if you can successfully configure your Berkeley DB build script with --enable-stl, then you should be able to successfully build dbstl library and application code using it.

Besides its own test suite, dbstl has also been tested against, and passes, the following test suites:

  • MS STL test suite

  • SGI STL test suite