PMDK C++ bindings  1.13.0-git107.g7e59f08f
This is the C++ bindings documentation for PMDK's libpmemobj.
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_baseoperator= (const pool_base &) noexcept=default
 Defaulted copy assignment operator.
 
pool_baseoperator= (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_CPP_DEPRECATED PMEMobjpool * get_handle () noexcept
 
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 Member Functions

static void check_pool (pmemobjpool *pop, std::string mode)
 

Protected Attributes

PMEMobjpool * pop
 

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>
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", "");
}
static pool_base open(const std::string &path, const std::string &layout)
Opens an existing object store memory pool.
Definition: pool.hpp:109
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.
Definition: pool.hpp:140
static int check(const std::string &path, const std::string &layout) noexcept
Checks if a given pool is consistent.
Definition: pool.hpp:168
persistent_ptr atomic allocation functions for objects.
Main libpmemobj namespace.
Definition: allocation_flag.hpp:18
Resides on pmem property template.
C++ pmemobj pool.

The example of using pool with RAII idiom:

using namespace pmem::obj;
class Foo {
private:
/* pool root structure */
struct persistent_data {
p<int> some_variable;
};
/* 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();
}
PMEMobj pool class.
Definition: pool.hpp:482
Persistent smart pointer.

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
cpopC-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
pathSystem path to the file containing the memory pool or a pool set.
layoutUnique 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
pathSystem path to the file containing the memory pool or a pool set.
layoutUnique 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_errorif 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
pathSystem 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.
layoutUnique identifier of the pool, can be a null-terminated string.
sizeSize of the pool in bytes. If zero and the file exists the pool is created in-place.
modeFile mode for the new file.
Returns
handle to the created pool.
Exceptions
pmem::pool_errorwhen 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
pathSystem 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.
layoutUnique identifier of the pool, can be a null-terminated string.
sizeSize of the pool in bytes. If zero and the file exists the pool is created in-place.
modeFile mode for the new file.
Returns
handle to the created pool.
Exceptions
pmem::pool_errorwhen 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]ptrvpointer to contiguous space containing persistent_ptr's for defrag.
[in]oidcntnumber of persistent_ptr's passed (in ptrv).
Returns
result struct containing a number of relocated and total processed objects.
Exceptions
pmem::defrag_errorwhen 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]propResides 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]ptrPersistent 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]addraddress of memory chunk
[in]lensize 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]destdestination memory address
[in]srcsource memory address
[in]lensize 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]destdestination memory address
[in]cconstant value to fill the memory
[in]lensize 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
pathSystem path to the file containing the memory pool or a pool set.
layoutUnique identifier of the pool as specified at pool creation time.
Returns
handle to the opened pool.
Exceptions
pmem::pool_errorwhen 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
pathSystem path to the file containing the memory pool or a pool set.
layoutUnique identifier of the pool as specified at pool creation time.
Returns
handle to the opened pool.
Exceptions
pmem::pool_errorwhen 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]propResides 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]ptrPersistent 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]addraddress of memory chunk
[in]lensize of memory chunk

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