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

Public Member Functions

Static Public Member Functions

Static Protected Member Functions

Protected Attributes

Static Protected Attributes

Detailed Description

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

Member Function Documentation

◆ check() [1/2]

◆ check() [2/2]

◆ close()

◆ create() [1/2]

◆ create() [2/2]

◆ ctl_exec() [1/2]

◆ ctl_exec() [2/2]

◆ ctl_get() [1/2]

◆ ctl_get() [2/2]

◆ ctl_set() [1/2]

◆ ctl_set() [2/2]

◆ defrag()

◆ flush() [1/3]

◆ flush() [2/3]

◆ flush() [3/3]

◆ handle()

◆ memcpy_persist()

◆ memset_persist()

◆ open() [1/2]

◆ open() [2/2]

◆ persist() [1/3]

◆ persist() [2/3]

◆ persist() [3/3]

◆ root()

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