Berkeley DB Reference Version 5.3.33

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

Standards compatible

Performance overhead

Portability

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:

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:

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: