PMDK C++ bindings  1.13.0-git23.gf49772ac
This is the C++ bindings documentation for PMDK's libpmemobj.
Public Member Functions | Static Public Member Functions | List of all members
pmem::obj::pool< T > Class Template Reference

PMEMobj pool class. More...

#include <libpmemobj++/pool.hpp>

Inheritance diagram for pmem::obj::pool< T >:
pmem::obj::pool_base

Public Member Functions

 pool () noexcept=default
 Defaulted constructor.
 
 pool (const pool &) noexcept=default
 Defaulted copy constructor.
 
 pool (pool &&) noexcept=default
 Defaulted move constructor.
 
pooloperator= (const pool &) noexcept=default
 Defaulted copy assignment operator.
 
pooloperator= (pool &&) noexcept=default
 Defaulted move assignment operator.
 
 ~pool () noexcept=default
 Default destructor.
 
 pool (const pool_base &pb) noexcept
 Defaulted copy constructor.
 
 pool (pool_base &&pb) noexcept
 Defaulted move constructor.
 
template<typename M >
ctl_get (const std::string &name)
 Query libpmemobj state at pool scope. More...
 
template<typename M >
ctl_set (const std::string &name, M arg)
 Modify libpmemobj state at pool scope. More...
 
template<typename M >
ctl_exec (const std::string &name, M arg)
 Execute function at pool scope. More...
 
template<typename M >
ctl_get (const std::wstring &name)
 Query libpmemobj state at pool scope. More...
 
template<typename M >
ctl_set (const std::wstring &name, M arg)
 Modify libpmemobj state at pool scope. More...
 
template<typename M >
ctl_exec (const std::wstring &name, M arg)
 Execute function at pool scope. More...
 
persistent_ptr< T > root ()
 Retrieves pool's root object. More...
 
- Public Member Functions inherited from pmem::obj::pool_base
 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_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< T > open (const std::string &path, const std::string &layout)
 Opens an existing object store memory pool. More...
 
static pool< T > 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)
 Checks if a given pool is consistent. More...
 
static pool< T > open (const std::wstring &path, const std::wstring &layout)
 Opens an existing object store memory pool. More...
 
static pool< T > 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)
 Checks if a given pool is consistent. More...
 
- Static Public Member Functions inherited from pmem::obj::pool_base
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...
 

Additional Inherited Members

- Static Protected Attributes inherited from pmem::obj::pool_base
static const int DEFAULT_MODE = S_IWRITE | S_IREAD
 Default create mode.
 

Detailed Description

template<typename T>
class pmem::obj::pool< T >

PMEMobj pool class.

This class is the pmemobj pool handler. It provides basic primitives for operations on pmemobj pools. The template parameter defines the type of the root object within the pool. This pool class inherits also some methods from the base class: pmem::obj::pool_base.

The typical usage example would be:

#include <fcntl.h>
using namespace pmem::obj;
void
pool_example()
{
/* pool root structure */
struct root {
p<int> some_array[42];
p<int> some_other_array[42];
p<double> some_variable;
};
/* create a pmemobj pool */
auto pop = pool<root>::create("poolfile", "layout", PMEMOBJ_MIN_POOL);
/* close a pmemobj pool */
pop.close();
/* or open a pmemobj pool */
pop = pool<root>::open("poolfile", "layout");
/* typical usage schemes */
auto root_obj = pop.root();
/* low-level memory manipulation */
root_obj->some_variable = 3.2;
pop.persist(root_obj->some_variable);
pop.memset_persist(root_obj->some_array, 2,
sizeof(root_obj->some_array));
pop.memcpy_persist(root_obj->some_other_array, root_obj->some_array,
sizeof(root_obj->some_array));
pop.close();
/* check pool consistency */
pool<root>::check("poolfile", "layout");
}
static pool< T > open(const std::string &path, const std::string &layout)
Opens an existing object store memory pool.
Definition: pool.hpp:672
static int check(const std::string &path, const std::string &layout)
Checks if a given pool is consistent.
Definition: pool.hpp:711
persistent_ptr< T > root()
Retrieves pool's root object.
Definition: pool.hpp:644
static pool< T > 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:694
Main libpmemobj namespace.
Definition: allocation_flag.hpp:18
Resides on pmem property template.
Persistent smart pointer.
C++ pmemobj pool.

This API should not be mixed with C API. For example explicitly calling pmemobj_set_user_data(pop) on pool which is handled by C++ pool object is undefined behaviour.

Member Function Documentation

◆ check() [1/2]

template<typename T >
static int pmem::obj::pool< T >::check ( const std::string &  path,
const std::string &  layout 
)
inlinestatic

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]

template<typename T >
static int pmem::obj::pool< T >::check ( const std::wstring &  path,
const std::wstring &  layout 
)
inlinestatic

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.

◆ create() [1/2]

template<typename T >
static pool<T> pmem::obj::pool< T >::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]

template<typename T >
static pool<T> pmem::obj::pool< T >::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.

◆ ctl_exec() [1/2]

template<typename T >
template<typename M >
M pmem::obj::pool< T >::ctl_exec ( const std::string &  name,
arg 
)
inline

Execute function at pool scope.

Parameters
[in]namename of entry point
[in]argextra argument
Returns
copy of arg, possibly modified by query

For more details, see: https://pmem.io/pmdk/manpages/linux/master/libpmemobj/pmemobj_ctl_get.3

◆ ctl_exec() [2/2]

template<typename T >
template<typename M >
M pmem::obj::pool< T >::ctl_exec ( const std::wstring &  name,
arg 
)
inline

Execute function at pool scope.

Parameters
[in]namename of entry point
[in]argextra argument
Returns
copy of arg, possibly modified by query

For more details, see: https://pmem.io/pmdk/manpages/linux/master/libpmemobj/pmemobj_ctl_get.3

◆ ctl_get() [1/2]

template<typename T >
template<typename M >
M pmem::obj::pool< T >::ctl_get ( const std::string &  name)
inline

Query libpmemobj state at pool scope.

Parameters
[in]namename of entry point
Returns
variable representing internal state

For more details, see: https://pmem.io/pmdk/manpages/linux/master/libpmemobj/pmemobj_ctl_get.3

◆ ctl_get() [2/2]

template<typename T >
template<typename M >
M pmem::obj::pool< T >::ctl_get ( const std::wstring &  name)
inline

Query libpmemobj state at pool scope.

Parameters
[in]namename of entry point
Returns
variable representing internal state

For more details, see: https://pmem.io/pmdk/manpages/linux/master/libpmemobj/pmemobj_ctl_get.3

◆ ctl_set() [1/2]

template<typename T >
template<typename M >
M pmem::obj::pool< T >::ctl_set ( const std::string &  name,
arg 
)
inline

Modify libpmemobj state at pool scope.

Parameters
[in]namename of entry point
[in]argextra argument
Returns
copy of arg, possibly modified by query

For more details, see: https://pmem.io/pmdk/manpages/linux/master/libpmemobj/pmemobj_ctl_get.3

◆ ctl_set() [2/2]

template<typename T >
template<typename M >
M pmem::obj::pool< T >::ctl_set ( const std::wstring &  name,
arg 
)
inline

Modify libpmemobj state at pool scope.

Parameters
[in]namename of entry point
[in]argextra argument
Returns
copy of arg, possibly modified by query

For more details, see: https://pmem.io/pmdk/manpages/linux/master/libpmemobj/pmemobj_ctl_get.3

◆ open() [1/2]

template<typename T >
static pool<T> pmem::obj::pool< T >::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]

template<typename T >
static pool<T> pmem::obj::pool< T >::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.

◆ root()

template<typename T >
persistent_ptr<T> pmem::obj::pool< T >::root ( )
inline

Retrieves pool's root object.

Returns
persistent pointer to the root object.
Exceptions
pmem::pool_errorwhen pool handle is incorrect.

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