• This repository has been archived on 22/Mar/2023
  • Stars
    star
    107
  • Rank 323,587 (Top 7 %)
  • Language
    C++
  • License
    Other
  • Created over 6 years ago
  • Updated over 1 year ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

C++ bindings & containers for libpmemobj

libpmemobj-cpp

Build status libpmemobj-cpp version Coverity Scan Build Status Coverage Status Packaging status

⚠️ Discontinuation of the project

The libpmemobj-cpp project will no longer be maintained by Intel.

  • Intel has ceased development and contributions including, but not limited to, maintenance, bug fixes, new releases, or updates, to this project.
  • Intel no longer accepts patches to this project.
  • If you have an ongoing need to use this project, are interested in independently developing it, or would like to maintain patches for the open source software community, please create your own fork of this project.
  • You will find more information here.

Introduction

libpmemobj-cpp is a C++ binding for libpmemobj (a library which is a part of PMDK collection). More implementation details can be found in include/libpmemobj++/README.md.

Latest releases can be found on the "releases" tab. Up-to-date support/maintenance status of branches/releases is available on pmem.io.

Compatibility note

In libpmemobj 1.12 we introduced a new transaction handler type: pmem::obj::flat_transaction. By defining LIBPMEMOBJ_CPP_USE_FLAT_TRANSACTION you can make pmem::obj::transaction to be an alias to pmem::obj::flat_transaction. In 1.12 we have also changed the default behavior of containers' transactional methods. Now, in case of any failure within such method, the outer transaction (if any) will not be immediately aborted. Instead, an exception will be thrown, which will lead to transaction abort only if it's not caught before the outer tx scope ends. To change the behavior to the old one, you can set LIBPMEMOBJ_CPP_FLAT_TX_USE_FAILURE_RETURN macro to 0. Be aware that the old behavior can lead to segfaults in some cases (see tx_nested_struct_example in this file).

Table of contents

  1. Pre-built packages
  2. Dependencies
  3. Linux build
  4. Windows build
  5. Extra CMake compilation flags
  6. Contact us

Pre-built packages

The best way to install stable releases, tested on specific OS, is to use package manager.

Windows

The recommended and the easiest way to install libpmemobj-cpp on Windows is to use Microsoft's vcpkg. Vcpkg is an open source tool and ecosystem created for library management. For more information about vcpkg please see vcpkg repository.

.\vcpkg.exe install libpmemobj-cpp:x64-windows

Ubuntu/Debian

For installation on Debian-related distros please execute following commands:

# apt install libpmemobj-cpp-dev

Fedora/RHEL

To install libpmemobj-cpp on Fedora or RedHat execute:

# dnf install libpmemobj++-devel

Dependencies

You will need the following packages for compilation:

  • cmake >= 3.3
  • libpmemobj-dev(el) >= 1.9 (https://pmem.io/pmdk/)
  • compiler with C++11 support
    • gcc >= 4.8.1 1
    • clang >= 3.3
    • msbuild >= 14 2
  • for testing and development:
  • for Windows compilation:

Required packages (or their names) for some OSes may differ. Some examples or scripts in this repository may require additional dependencies, but should not interrupt the build.

See our Dockerfiles (used e.g. on our CI systems) to get an idea what packages are required to build the entire libpmemobj-cpp, with all tests and examples.

1 C++11 is supported in GCC since version 4.8.1, but it does not support expanding variadic template variables in lambda expressions, which is required to build persistent containers and is possible with GCC >= 4.9.0. If you want to build libpmemobj-cpp without testing containers, use flag TEST_XXX=OFF (separate flag for each container).

2 radix_tree is supported on Windows with MSBuild >=15 (Visual Studio at least 2017 is needed). Testing radix_tree can be disabled via CMake option (use -DTEST_RADIX_TREE=OFF).

Linux build

Standard compilation

$ mkdir build
$ cd build
$ cmake .. [-DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=<path_to_installation_dir>]
$ make
# make install

Note: By default CMake's option USE_LIBUNWIND is switched ON. If libunwind package was found in the system, it is then linked to all tests' binaries. Sometimes this may lead to failing a test, if it is run under Valgrind. To avoid this false-positive fails, you can execute tests run under Valgrind separately, without libunwind:

cmake .. -DTESTS_USE_VALGRIND=ON -DUSE_LIBUNWIND=OFF && \
ctest -R "_helgrind|_pmemcheck|_drd|_memcheck|_pmreorder"	# run only valgrind tests

or valgrind tests can be disabled in CMake build:

cmake .. -DTESTS_USE_VALGRIND=OFF && \
ctest

Developer compilation

$ mkdir build
$ cd build
$ cmake .. -DCMAKE_BUILD_TYPE=Debug -DDEVELOPER_MODE=1 -DCHECK_CPP_STYLE=1
$ make
$ ctest --output-on-failure

Distribution package build

$ mkdir build
$ cd build
$ cmake .. -DCPACK_GENERATOR="$GEN" -DCMAKE_INSTALL_PREFIX=/usr
$ make package

$GEN is type of package generator and can be RPM or DEB

CMAKE_INSTALL_PREFIX must be set to a destination were packages will be installed

Compilation with Valgrind instrumentation

In order to build your application with libpmemobj-cpp and pmemcheck / memcheck / helgrind / drd, Valgrind instrumentation must be enabled during compilation by adding flags:

  • LIBPMEMOBJ_CPP_VG_PMEMCHECK_ENABLED=1 for pmemcheck instrumentation
  • LIBPMEMOBJ_CPP_VG_MEMCHECK_ENABLED=1 for memcheck instrumentation
  • LIBPMEMOBJ_CPP_VG_HELGRIND_ENABLED=1 for helgrind instrumentation
  • LIBPMEMOBJ_CPP_VG_DRD_ENABLED=1 for drd instrumentation, or
  • LIBPMEMOBJ_CPP_VG_ENABLED=1 for all Valgrind instrumentations (including pmemcheck).

If there are no memcheck / helgrind / drd / pmemcheck headers installed on your system, build will fail.

Windows build

Install prerequisites via vcpkg

vcpkg install pmdk:x64-windows
vcpkg integrate install

Compilation with Visual Studio 2015

cmake . -Bbuild -G "Visual Studio 14 2015 Win64"
        -DCMAKE_TOOLCHAIN_FILE="c:/tools/vcpkg/scripts/buildsystems/vcpkg.cmake"
        -DTEST_RADIX_TREE=OFF

msbuild build/ALL_BUILD.vcxproj /m

Compilation with Visual Studio 2017 or above

cmake . -Bbuild -G "Visual Studio 15 2017" -A "x64"
		-DCMAKE_TOOLCHAIN_FILE="c:/tools/vcpkg/scripts/buildsystems/vcpkg.cmake"

msbuild build/ALL_BUILD.vcxproj /m

Extra CMake compilation flags

For custom build you can use CMake flags to change build type, change C++ standard, enable/disable components or features for testing purposes. To list all CMake flags use the following:

$ mkdir build
$ cd build
$ cmake ..
$ cmake -LH

or just use graphical CMake frontend like cmake-qt-gui or cmake-curses-gui.

Contact us

If you read the blog post and still have some questions (especially about discontinuation of the project), please contact us using the dedicated e-mail: [email protected].

More Repositories

1

pmdk

Persistent Memory Development Kit
C
1,336
star
2

syscall_intercept

The system call intercepting library
C
631
star
3

pmemkv

Key/Value Datastore for Persistent Memory
C++
397
star
4

ndctl

A "device memory" enabling project encompassing tools and libraries for CXL, NVDIMMs, DAX, memory tiering and other platform memory device topics.
C
262
star
5

pcj

Persistent Collections for Java
Java
221
star
6

kvdk

Key Value Development Kit
C++
201
star
7

pmem-redis

A version of Redis that uses persistent memory
C
113
star
8

valgrind

Enhanced Valgrind for Persistent Memory
C
107
star
9

rpma

Remote Persistent Memory Access Library
C
101
star
10

vltrace

Tool tracing syscalls in a fast way using eBPF linux kernel feature
C
98
star
11

llpl

Low Level Persistence Library
Java
97
star
12

pmem-rocksdb

A version of RocksDB that uses persistent memory
C++
90
star
13

linux-examples

Early (now outdated) examples. Use PMDK instead.
C
59
star
14

run_qemu

A script to create bootable OS images, and run qemu with a locally built kernel.
Shell
57
star
15

pmdk-examples

PMDK examples and tutorials
C++
57
star
16

book

Persistent Memory Programming book examples
C
39
star
17

vmemcache

Buffer based LRU cache
C
35
star
18

pmemfile

Userspace implementation of file APIs using persistent memory.
C
34
star
19

pmemkv-java

Java bindings for pmemkv
Java
28
star
20

pmse

Persistent Memory Storage Engine
C++
24
star
21

vmem

Volatile Persistent Memory Allocator
C
23
star
22

pmemkv-bench

Benchmarking tools for pmemkv
C++
22
star
23

pmem.github.io

The pmem.io Website
HTML
17
star
24

pmemkv-python

Python bindings for pmemkv
Python
13
star
25

issues

Old issues repo for PMDK.
13
star
26

pmdk-tests

Extended tests for PMDK libraries and utilities
C++
10
star
27

miniasync

C
10
star
28

docs

Persistent Memory Docbook
9
star
29

pmemstream

C++
9
star
30

libpmemobj-js

JavaScript bindings for libpmemobj
C++
8
star
31

pmemkv-nodejs

NodeJS bindings for pmemkv
JavaScript
8
star
32

pmem-rocksdb-plugin

RocksDB plugin for optimized PMem support
C++
5
star
33

mpi-pmem-ext

MPI Extensions for Persistent Memory
C
4
star
34

kvm-redis

Recipe to run a memtier benchmark on a cluster of KVM-hosted Redis servers
Jinja
4
star
35

pmemkv-jni

Java Native Interface for pmemkv
C++
3
star
36

pmul

PMUL is a Java library that adds PMem programming features to Java’s foreign memory API in JDK 18
Java
2
star
37

acpi-spec-ecr

ACPI Specification ECRs
Makefile
2
star
38

dev-utils-kit

Shell
2
star
39

pmemkv-ruby

Ruby bindings for pmemkv
Ruby
2
star
40

autoflushtest

Basic data integrity test for platforms with flush-on-fail CPU caches
C
1
star
41

pmdk-convert

Conversion tool for pmdk pools
CMake
1
star
42

knowledge-base

Knowledge Base for pmem.io
SCSS
1
star