pmem::obj::pool_base Class Reference

The non-template pool base class. More...

#include <libpmemobj++/pool.hpp>

Inheritance diagram for pmem::obj::pool_base:

Public Member Functions
	pool_base () noexcept
	Defaulted constructor.
	pool_base (pmemobjpool *cpop) noexcept
	Explicit constructor. More...
	pool_base (const pool_base &) noexcept=default
	Defaulted copy constructor.
	pool_base (pool_base &&) noexcept=default
	Defaulted move constructor.
pool_base &	operator= (const pool_base &) noexcept=default
	Defaulted copy assignment operator.
pool_base &	operator= (pool_base &&) noexcept=default
	Defaulted move assignment operator.
virtual	~pool_base () noexcept=default
	Default virtual destructor.
void	close ()
	Closes the pool. More...
void	persist (const void *addr, size_t len) noexcept
	Performs persist operation on a given chunk of memory. More...
template<typename Y >
void	persist (const p< Y > &prop) noexcept
	Performs persist operation on a given pmem property. More...
template<typename Y >
void	persist (const persistent_ptr< Y > &ptr) noexcept
	Performs persist operation on a given persistent pointer. More...
void	flush (const void *addr, size_t len) noexcept
	Performs flush operation on a given chunk of memory. More...
template<typename Y >
void	flush (const p< Y > &prop) noexcept
	Performs flush operation on a given pmem property. More...
template<typename Y >
void	flush (const persistent_ptr< Y > &ptr) noexcept
	Performs flush operation on a given persistent object. More...
void	drain (void) noexcept
	Performs drain operation.
void *	memcpy_persist (void *dest, const void *src, size_t len) noexcept
	Performs memcpy and persist operation on a given chunk of memory. More...
void *	memset_persist (void *dest, int c, size_t len) noexcept
	Performs memset and persist operation on a given chunk of memory. More...
PMEMobjpool *	handle () noexcept
	Gets the C style handle to the pool. More...
pobj_defrag_result	defrag (persistent_ptr_base **ptrv, size_t oidcnt)
	Starts defragmentation using selected pointers within this pool. More...

Static Public Member Functions
static pool_base	open (const std::string &path, const std::string &layout)
	Opens an existing object store memory pool. More...
static pool_base	create (const std::string &path, const std::string &layout, std::size_t size=PMEMOBJ_MIN_POOL, mode_t mode=DEFAULT_MODE)
	Creates a new transactional object store pool. More...
static int	check (const std::string &path, const std::string &layout) noexcept
	Checks if a given pool is consistent. More...
static pool_base	open (const std::wstring &path, const std::wstring &layout)
	Opens an existing object store memory pool. More...
static pool_base	create (const std::wstring &path, const std::wstring &layout, std::size_t size=PMEMOBJ_MIN_POOL, mode_t mode=DEFAULT_MODE)
	Creates a new transactional object store pool. More...
static int	check (const std::wstring &path, const std::wstring &layout) noexcept
	Checks if a given pool is consistent. More...

Static Protected Attributes
static const int	DEFAULT_MODE = S_IWRITE | S_IREAD
	Default create mode.

Detailed Description

The non-template pool base class.

This class is a non-template version of pool. It is useful for places where providing pool template argument is undesirable. The typical usage example would be:

#include <fcntl.h>
#include <libpmemobj++/make_persistent_atomic.hpp>
#include <libpmemobj++/p.hpp>
#include <libpmemobj++/pool.hpp>
 
using namespace pmem::obj;
 
void
pool_base_example()
{
 
    struct some_struct {
        p<int> some_array[42];
        p<int> some_other_array[42];
        p<int> some_variable;
    };
 
    /* create a pmemobj pool */
    auto pop = pool_base::create("poolfile", "", PMEMOBJ_MIN_POOL);
 
    /* close a pmemobj pool */
    pop.close();
 
    /* or open a pmemobj pool */
    pop = pool_base::open("poolfile", "");
 
    /* no "root" object available in pool_base */
    persistent_ptr<some_struct> pval;
    make_persistent_atomic<some_struct>(pop, pval);
 
    /* low-level memory manipulation */
    pval->some_variable = 3;
    pop.persist(pval->some_variable);
 
    pop.memset_persist(pval->some_array, 2, sizeof(pval->some_array));
 
    pop.memcpy_persist(pval->some_other_array, pval->some_array,
               sizeof(pval->some_array));
 
    pop.close();
 
    /* check pool consistency */
    pool_base::check("poolfile", "");
}

The exmple of using pool with RAII idiom:

#include <libpmemobj++/p.hpp>
#include <libpmemobj++/persistent_ptr.hpp>
#include <libpmemobj++/pool.hpp>
 
using namespace pmem::obj;
 
class Foo {
private:
    /* pool root structure */
    struct persistent_data {
        p<int> some_variable;
    };
 
    using pool_type = pmem::obj::pool<persistent_data>;
    /* pool object */
    pool_type pop;
 
    const char *layout = "pool_layout";
 
public:
    Foo(const char *poolfile_path)
    {
        /* Create a pmemobj pool. */
        if (pool_type::check(poolfile_path, layout) == 1) {
            pop = pool_type::open(poolfile_path, layout);
        } else {
            std::cerr << "Cannot open pool" << std::endl
                  << "Trying to create a new one " << std::endl;
            pop = pool_type::create("poolfile", layout,
                        PMEMOBJ_MIN_POOL);
        }
    }
 
    Foo() = delete;
 
    ~Foo()
    {
        /* Close a pmemobj pool */
        try {
            pop.close();
        } catch (...) {
            /* Let's ignore all exceptions during close */
        }
    }
 
    void
    set(int variable)
    {
        auto root_obj = pop.root();
        root_obj->some_variable = variable;
        pop.persist(root_obj->some_variable);
    }
 
    void
    increment()
    {
        set(pop.root()->some_variable + 1);
    }
 
    void
    print()
    {
        std::cout << pop.root()->some_variable << std::endl;
    }
};
 
void
pool_example()
{
    auto foo = Foo("poolfile");
    foo.print();
    foo.set(42);
    foo.print();
    foo.increment();
    foo.print();
}

Constructor & Destructor Documentation

pool_base()

pmem::obj::pool_base::pool_base ( pmemobjpool *  cpop )

inlineexplicitnoexcept

Explicit constructor.

Create pool_base object based on C-style pool handle.

Parameters

cpop	C-style pool handle.

Member Function Documentation

check() [1/2]

static int pmem::obj::pool_base::check ( const std::string &  path, const std::string &  layout  )

inlinestaticnoexcept

Checks if a given pool is consistent.

Parameters

path	System path to the file containing the memory pool or a pool set.
layout	Unique identifier of the pool as specified at pool creation time.

Returns

-1 on error, 1 if file is consistent, 0 otherwise.

check() [2/2]

static int pmem::obj::pool_base::check ( const std::wstring &  path, const std::wstring &  layout  )

inlinestaticnoexcept

Checks if a given pool is consistent.

Wide string variant. Available only on Windows.

Parameters

path	System path to the file containing the memory pool or a pool set.
layout	Unique identifier of the pool as specified at pool creation time.

Returns

-1 on error, 1 if file is consistent, 0 otherwise.

close()

void pmem::obj::pool_base::close ( )

inline

Closes the pool.

Exceptions

std::logic_error

if the pool has already been closed.

create() [1/2]

static pool_base pmem::obj::pool_base::create ( const std::string &  path, const std::string &  layout, std::size_t  size = PMEMOBJ_MIN_POOL, mode_t  mode = DEFAULT_MODE  )

inlinestatic

Creates a new transactional object store pool.

Parameters

path	System path to the file to be created. If exists the pool can be created in-place depending on the size parameter. Existing file must be zeroed.
layout	Unique identifier of the pool, can be a null-terminated string.
size	Size of the pool in bytes. If zero and the file exists the pool is created in-place.
mode	File mode for the new file.

Returns

handle to the created pool.

Exceptions

pmem::pool_error

when an error during creation occurs.

create() [2/2]

static pool_base pmem::obj::pool_base::create ( const std::wstring &  path, const std::wstring &  layout, std::size_t  size = PMEMOBJ_MIN_POOL, mode_t  mode = DEFAULT_MODE  )

inlinestatic

Creates a new transactional object store pool.

Wide string variant. Available only on Windows.

Parameters

path	System path to the file to be created. If exists the pool can be created in-place depending on the size parameter. Existing file must be zeroed.
layout	Unique identifier of the pool, can be a null-terminated string.
size	Size of the pool in bytes. If zero and the file exists the pool is created in-place.
mode	File mode for the new file.

Returns

handle to the created pool.

Exceptions

pmem::pool_error

when an error during creation occurs.

defrag()

pobj_defrag_result pmem::obj::pool_base::defrag ( persistent_ptr_base **  ptrv, size_t  oidcnt  )

inline

Starts defragmentation using selected pointers within this pool.

Parameters

[in]	ptrv	pointer to contiguous space containing persistent_ptr's for defrag.
[in]	oidcnt	number of persistent_ptr's passed (in ptrv).

Returns

result struct containing a number of relocated and total processed objects.

Exceptions

pmem::defrag_error

when a failure during defragmentation occurs. Even if this error is thrown, some of the objects could have been relocated, see defrag_error.result for summary stats.

flush() [1/3]

template<typename Y >

void pmem::obj::pool_base::flush ( const p< Y > &  prop )

inlinenoexcept

Performs flush operation on a given pmem property.

Parameters

[in]

prop

Resides on pmem property

flush() [2/3]

template<typename Y >

void pmem::obj::pool_base::flush ( const persistent_ptr< Y > &  ptr )

inlinenoexcept

Performs flush operation on a given persistent object.

Parameters

[in]

ptr

Persistent pointer to object

flush() [3/3]

void pmem::obj::pool_base::flush ( const void *  addr, size_t  len  )

inlinenoexcept

Performs flush operation on a given chunk of memory.

Parameters

[in]	addr	address of memory chunk
[in]	len	size of memory chunk

handle()

PMEMobjpool* pmem::obj::pool_base::handle ( )

inlinenoexcept

Gets the C style handle to the pool.

Necessary to be able to use the pool with the C API.

Returns

pool opaque handle.

memcpy_persist()

void* pmem::obj::pool_base::memcpy_persist ( void *  dest, const void *  src, size_t  len  )

inlinenoexcept

Performs memcpy and persist operation on a given chunk of memory.

Parameters

[in]	dest	destination memory address
[in]	src	source memory address
[in]	len	size of memory chunk

Returns

A pointer to dest

memset_persist()

void* pmem::obj::pool_base::memset_persist ( void *  dest, int  c, size_t  len  )

inlinenoexcept

Performs memset and persist operation on a given chunk of memory.

Parameters

[in]	dest	destination memory address
[in]	c	constant value to fill the memory
[in]	len	size of memory chunk

Returns

A pointer to dest

open() [1/2]

static pool_base pmem::obj::pool_base::open ( const std::string &  path, const std::string &  layout  )

inlinestatic

Opens an existing object store memory pool.

Parameters

path	System path to the file containing the memory pool or a pool set.
layout	Unique identifier of the pool as specified at pool creation time.

Returns

handle to the opened pool.

Exceptions

pmem::pool_error

when an error during opening occurs.

open() [2/2]

static pool_base pmem::obj::pool_base::open ( const std::wstring &  path, const std::wstring &  layout  )

inlinestatic

Opens an existing object store memory pool.

Wide string variant. Available only on Windows.

Parameters

path	System path to the file containing the memory pool or a pool set.
layout	Unique identifier of the pool as specified at pool creation time.

Returns

handle to the opened pool.

Exceptions

pmem::pool_error

when an error during opening occurs.

persist() [1/3]

template<typename Y >

void pmem::obj::pool_base::persist ( const p< Y > &  prop )

inlinenoexcept

Performs persist operation on a given pmem property.

Parameters

[in]

prop

Resides on pmem property

persist() [2/3]

template<typename Y >

void pmem::obj::pool_base::persist ( const persistent_ptr< Y > &  ptr )

inlinenoexcept

Performs persist operation on a given persistent pointer.

Persist is not performed on the object referenced by this pointer.

Parameters

[in]

ptr

Persistent pointer to object

persist() [3/3]

void pmem::obj::pool_base::persist ( const void *  addr, size_t  len  )

inlinenoexcept

Performs persist operation on a given chunk of memory.

Parameters

[in]	addr	address of memory chunk
[in]	len	size of memory chunk

---

The documentation for this class was generated from the following file:

• libpmemobj++/pool.hpp