pmem::obj::pool< T > Class Template Reference

PMEMobj pool class. More...

#include <libpmemobj++/pool.hpp>

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

Public Member Functions
	pool () noexcept=default
	Defaulted constructor.
	pool (const pool &) noexcept=default
	Defaulted copy constructor.
	pool (pool &&) noexcept=default
	Defaulted move constructor.
pool &	operator= (const pool &) noexcept=default
	Defaulted copy assignment operator.
pool &	operator= (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 >
M	ctl_get (const std::string &name)
	Query libpmemobj state at pool scope. More...
template<typename M >
M	ctl_set (const std::string &name, M arg)
	Modify libpmemobj state at pool scope. More...
template<typename M >
M	ctl_exec (const std::string &name, M arg)
	Execute function at pool scope. More...
template<typename M >
M	ctl_get (const std::wstring &name)
	Query libpmemobj state at pool scope. More...
template<typename M >
M	ctl_set (const std::wstring &name, M arg)
	Modify libpmemobj state at pool scope. More...
template<typename M >
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...
POBJ_CPP_DEPRECATED persistent_ptr< T >	get_root ()
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< 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 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

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>
#include <libpmemobj++/p.hpp>
#include <libpmemobj++/persistent_ptr.hpp>
#include <libpmemobj++/pool.hpp>
 
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");
}

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

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]

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

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 ( )

inlineinherited

Closes the pool.

Exceptions

std::logic_error

if the pool has already been closed.

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

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]

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

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.

ctl_exec() [1/2]

template<typename T >

template<typename M >

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

inline

Execute function at pool scope.

Parameters

[in]	name	name of entry point
[in]	arg	extra 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, M  arg  )

inline

Execute function at pool scope.

Parameters

[in]	name	name of entry point
[in]	arg	extra 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]

name

name 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]

name

name 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, M  arg  )

inline

Modify libpmemobj state at pool scope.

Parameters

[in]	name	name of entry point
[in]	arg	extra 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, M  arg  )

inline

Modify libpmemobj state at pool scope.

Parameters

[in]	name	name of entry point
[in]	arg	extra 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

defrag()

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

inlineinherited

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 )

inlinenoexceptinherited

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 )

inlinenoexceptinherited

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  )

inlinenoexceptinherited

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 ( )

inlinenoexceptinherited

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  )

inlinenoexceptinherited

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  )

inlinenoexceptinherited

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]

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

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]

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

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 )

inlinenoexceptinherited

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 )

inlinenoexceptinherited

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  )

inlinenoexceptinherited

Performs persist operation on a given chunk of memory.

Parameters

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

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_error

when pool handle is incorrect.

---

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

• libpmemobj++/persistent_ptr.hpp
• libpmemobj++/pool.hpp