NVML C++ bindings 1.0.0
This is the C++ bindings documentation for NVML's libpmemobj.
This is the C++ API for libpmemobj.
During the development of libpmemobj, many difficulties were encountered and compromises were made to make the C API as much user-friendly as possible. This is mostly due to the semantics of the C language. Since C++ is a more expressive language, it was natural to try and bridge the gap using native C++ features.
There are three main features of the C++ bindings:
transaction, which comes in two flavours - scoped and closure,
The main issue with the C API is the generic PMEMoid and its typed counterpart, the TOID. For them to be conveniently used in transactions, a large set of macros has been defined. This made using the generic pointer easier, yet still unintuitive. In C++, the
persistent_ptr<> template makes it a lot easier providing well known smart pointer semantics and built-in transactions support.
The other drawback of the C API is the transaction semantics. Manual usage of
jmpbuf is error prone, so they were once again wrapped in macros. They themselves have issues with undefined values of automatic variables (see the libpmemobj manpage for more details). The transactions defined in the C++ bindings try to fix the inadequacies of their C counterparts.
p<>, which is called the persistent property, was designed with seamless persistent memory integration in mind. It is designed to be used with basic types within classes, to signify that these members in fact reside in persistent memory and need to be handled appropriately.
Please remember to take extra care when using static class members. They are not stored in persistent memory, therefore their value will not always be consistent across subsequent executions or compilations of user applications.
The C++ bindings implement an experimental, standard compliant memory allocator which can be used in the C++ standard library's containers. This is an experimental feature that should work with a custom libc++ implementation found here https://github.com/pmem/libcxx. Please refer to the official LLVM documentation on how to compile and install libc++. Also please note that the allocator along with the changes in the implementation of libc++ are considered experimental and are subject to change without prior notice.
If you find any issues or have suggestion about these bindings please file an issue in https://github.com/pmem/issues. There are also blog articles in http://pmem.io/blog/ which you might find helpful.
Have fun! The NVML team
The C++ bindings require a C++11 compliant compiler, therefore the minimal versions of GCC and Clang are 4.8.1 and 3.3 respectively. However the nvml::obj::transaction::automatic class requires C++17, so you need a more recent version for this to be available(GCC 6.1/Clang 3.7). It is recommended to use these or newer versions of GCC or Clang.