pmem::obj::experimental::vector - EXPERIMENTAL persistent container with std::vector compatible interface. More...

#include <libpmemobj++/experimental/vector.hpp>

Public Member Functions
	vector ()
	Default constructor. More...

	vector (size_type count, const value_type &value)
	Constructs the container with count copies of elements with value value. More...

	vector (size_type count)
	Constructs the container with count copies of T default constructed values. More...

template<typename InputIt , typename std::enable_if< detail::is_input_iterator< InputIt >::value &&std::is_constructible< value_type, typename std::iterator_traits< InputIt >::reference >::value, InputIt >::type * = nullptr>
	vector (InputIt first, InputIt last)
	Constructs the container with the contents of the range [first, last). More...

	vector (const vector &other)
	Copy constructor. More...

	vector (vector &&other)
	Move constructor. More...

	vector (std::initializer_list< T > init)
	Constructs the container with the contents of the initializer list init. More...

	~vector ()
	Destructor. More...

reference	at (size_type n)
	Access element at specific index with bounds checking and add it to a transaction. More...

const_reference	at (size_type n) const
	Access element at specific index with bounds checking. More...

const_reference	const_at (size_type n) const
	Access element at specific index with bounds checking. More...

reference	operator[] (size_type n)
	Access element at specific index and add it to a transaction. More...

const_reference	operator[] (size_type n) const
	Access element at specific index. More...

reference	front ()
	Access the first element and add this element to a transaction. More...

const_reference	front () const
	Access the first element. More...

const_reference	cfront () const
	Access the first element. More...

reference	back ()
	Access the last element and add this element to a transaction. More...

const_reference	back () const
	Access the last element. More...

const_reference	cback () const
	Access the last element. More...

value_type *	data ()
	Returns raw pointer to the underlying data and adds entire array to a transaction. More...

const value_type *	data () const noexcept
	Returns const raw pointer to the underlying data. More...

const value_type *	cdata () const noexcept
	Returns const raw pointer to the underlying data. More...

iterator	begin ()
	Returns an iterator to the beginning. More...

const_iterator	begin () const noexcept
	Returns const iterator to the beginning. More...

const_iterator	cbegin () const noexcept
	Returns const iterator to the beginning. More...

iterator	end ()
	Returns an iterator to past the end. More...

const_iterator	end () const noexcept
	Returns a const iterator to past the end. More...

const_iterator	cend () const noexcept
	Returns a const iterator to the end. More...

reverse_iterator	rbegin ()
	Returns a reverse iterator to the beginning. More...

const_reverse_iterator	rbegin () const noexcept
	Returns a const reverse iterator to the beginning. More...

const_reverse_iterator	crbegin () const noexcept
	Returns a const reverse iterator to the beginning. More...

reverse_iterator	rend ()
	Returns a reverse iterator to the end. More...

const_reverse_iterator	rend () const noexcept
	Returns a const reverse iterator to the end. More...

const_reverse_iterator	crend () const noexcept
	Returns a const reverse iterator to the beginning. More...

constexpr bool	empty () const noexcept
	Checks whether the container is empty. More...

size_type	size () const noexcept

constexpr size_type	max_size () const noexcept

size_type	capacity () const noexcept

void	free_data ()
	Clears the content of a vector and frees all allocated persitent memory for data in transaction. More...

Private Member Functions
void	_alloc (size_type size)
	Private helper function. More...

void	_dealloc ()
	Private helper function. More...

void	_grow (size_type count, const_reference value)
	Private helper function. More...

template<typename InputIt , typename std::enable_if< detail::is_input_iterator< InputIt >::value &&std::is_constructible< value_type, typename std::iterator_traits< InputIt >::reference >::value, InputIt >::type * = nullptr>
void	_grow (InputIt first, InputIt last)
	Private helper function. More...

void	_shrink (size_type size_new) noexcept
	Private helper function. More...

Detailed Description

template<typename T>
class pmem::obj::experimental::vector< T >

pmem::obj::experimental::vector - EXPERIMENTAL persistent container with std::vector compatible interface.

Constructor & Destructor Documentation

◆ vector() [1/7]

template<typename T >

pmem::obj::experimental::vector< T >::vector ( )

Default constructor.

Constructs an empty container.

Precondition: must be called in transaction scope.

Exceptions

pmem::pool_error	if an object is not in persistent memory.
pmem::transaction_error	if constructor wasn't called in transaction.

◆ vector() [2/7]

template<typename T >

pmem::obj::experimental::vector< T >::vector	(	size_type	count,
		const value_type &	value
	)

Constructs the container with count copies of elements with value value.

Parameters

[in]	count	number of elements to construct.
[in]	value	value of all constructed elements.

Precondition: must be called in transaction scope.

Postcondition: size() == count; capacity() == size()

Exceptions

pmem::pool_error	if an object is not in persistent memory.
pmem::transaction_alloc_error	when allocating memory for underlying array in transaction failed.
pmem::transaction_error	if constructor wasn't called in transaction.
rethrows	element constructor exception.

◆ vector() [3/7]

template<typename T >

pmem::obj::experimental::vector< T >::vector ( size_type count )

explicit

Constructs the container with count copies of T default constructed values.

Parameters

[in] count number of elements to construct.

Precondition: must be called in transaction scope.

Postcondition: size() == count; capacity() == size()

Exceptions

pmem::pool_error	if an object is not in persistent memory.
pmem::transaction_alloc_error	when allocating memory for underlying array in transaction failed.
pmem::transaction_error	if constructor wasn't called in transaction.
rethrows	element constructor exception.

◆ vector() [4/7]

template<typename T >

template<typename InputIt , typename std::enable_if< detail::is_input_iterator< InputIt >::value &&std::is_constructible< T, typename std::iterator_traits< InputIt >::reference >::value, InputIt >::type * >

pmem::obj::experimental::vector< T >::vector	(	InputIt	first,
		InputIt	last
	)

Constructs the container with the contents of the range [first, last).

The first and last arguments must satisfy InputIterator requirements. This overload only participates in overload resolution if InputIt satisfies InputIterator, to avoid ambiguity with the overload of count-value constructor.

Parameters

[in]	first	first iterator.
[in]	last	last iterator.

Precondition: must be called in transaction scope.

Postcondition: size() == std::distance(first, last); capacity() == size()

Exceptions

pmem::pool_error	if an object is not in persistent memory.
pmem::transaction_alloc_error	when allocating memory for underlying array in transaction failed.
pmem::transaction_error	if constructor wasn't called in transaction.
rethrows	element constructor exception.

◆ vector() [5/7]

template<typename T >

pmem::obj::experimental::vector< T >::vector ( const vector< T > & other )

Copy constructor.

Constructs the container with the copy of the contents of other.

Parameters

[in] other reference to the vector to be copied.

Precondition: must be called in transaction scope.

Postcondition: size() == other.size(); capacity() == other.capacity()

Exceptions

pmem::pool_error	if an object is not in persistent memory.
pmem::transaction_alloc_error	when allocating memory for underlying array in transaction failed.
pmem::transaction_error	if constructor wasn't called in transaction.
rethrows	element constructor exception.

◆ vector() [6/7]

template<typename T >

pmem::obj::experimental::vector< T >::vector ( vector< T > && other )

Move constructor.

Constructs the container with the contents of other using move semantics. After the move, other is guaranteed to be empty().

Parameters

[in] other rvalue reference to the vector to be moved from.

Precondition: must be called in transaction scope.

Postcondition: size() == other.size(); capacity() == other.capacity(); data() == other.data(); other.data() == nullptr; other.capacity() == 0; other.size() == 0

Exceptions

pmem::pool_error	if an object is not in persistent memory.
pmem::transaction_error	if constructor wasn't called in transaction.

◆ vector() [7/7]

template<typename T>

pmem::obj::experimental::vector< T >::vector ( std::initializer_list< T > init )

Constructs the container with the contents of the initializer list init.

Parameters

[in] init initializer list with content to be constructed.

Precondition: must be called in transaction scope.

Postcondition: size() == init.size(); capacity() == size()

Exceptions

pmem::pool_error	if an object is not in persistent memory.
pmem::transaction_alloc_error	when allocating memory for underlying array in transaction failed.
pmem::transaction_error	if constructor wasn't called in transaction.
rethrows	element constructor exception.

◆ ~vector()

template<typename T >

pmem::obj::experimental::vector< T >::~vector ( )

Destructor.

Note that free_data may throw an transaction_free_error when freeing underlying array failed. It is recommended to call free_data manually before object destruction.

Member Function Documentation

◆ _alloc()

template<typename T >

void pmem::obj::experimental::vector< T >::_alloc ( size_type capacity_new )

private

Private helper function.

Must be called during transaction. Allocates memory for given number of elements.

Parameters

[in] capacity_new capacity of new underlying array.

Precondition: must be called in transaction scope.; data() == nullptr; size() == 0

Postcondition: capacity() == capacity_new

Exceptions

std::length_error	if new size exceeds biggest possible pmem allocation.
pmem::transaction_alloc_error	when allocating memory for underlying array in transaction failed.

◆ _dealloc()

template<typename T >

void pmem::obj::experimental::vector< T >::_dealloc ( )

private

Private helper function.

Must be called during transaction. Deallocates underlying array.

Precondition: must be called in transaction scope.

Postcondition: size() == 0; capacity() == 0; data() == nullptr

Exceptions

pmem::transaction_free_error when freeing old underlying array failed.

◆ _grow() [1/2]

template<typename T >

void pmem::obj::experimental::vector< T >::_grow	(	size_type	count,
		const_reference	value
	)

private

Private helper function.

Must be called during transaction. Assumes that there is enough space for additional elements. Copy constructs elements at the end of underlying array based on given parameters.

Parameters

[in]	count	number of elements to construct.
[in]	value	value of all constructed elements.

Precondition: must be called in transaction scope.; if initialized, range [end(), end() + count) must be snapshotted in current transaction.; capacity() >= count + size(); value is valid argument for value_type copy constructor.

Postcondition: size() == size() + count

Exceptions

rethrows constructor exception.

◆ _grow() [2/2]

template<typename T >

template<typename InputIt , typename std::enable_if< detail::is_input_iterator< InputIt >::value &&std::is_constructible< T, typename std::iterator_traits< InputIt >::reference >::value, InputIt >::type * >

void pmem::obj::experimental::vector< T >::_grow	(	InputIt	first,
		InputIt	last
	)

private

Private helper function.

Must be called during transaction. Assumes that there is enough space for additional elements and input arguments satisfy InputIterator requirements. Constructs elements in underlying array with the contents of the range [first, last). The first and last arguments must satisfy InputIterator requirements. This overload participates in overload resolution only if InputIt satisfies InputIterator.

Parameters

[in]	first	first iterator.
[in]	last	last iterator.

Precondition: must be called in transaction scope.; if initialized, range [end(), end() + std::distance(first, last)) must be snapshotted in current transaction.; capacity() >= std::distance(first, last) + size(); InputIt is InputIterator.; InputIt::reference is valid argument for value_type copy constructor.

Postcondition: size() == size() + std::distance(first, last)

Exceptions

rethrows constructor exception.

◆ _shrink()

template<typename T >

void pmem::obj::experimental::vector< T >::_shrink ( size_type size_new )

privatenoexcept

Private helper function.

Must be called during transaction. Destroys elements in underlying array beginning from position size_new.

Parameters

[in] size_new new size

Precondition: must be called in transaction scope.; if initialized, range [begin(), end()) must be snapshotted in current transaction.; size_new <= size()

Postcondition: size() == size_new

◆ at() [1/2]

template<typename T >

vector< T >::reference pmem::obj::experimental::vector< T >::at ( size_type n )

Access element at specific index with bounds checking and add it to a transaction.

Parameters

[in] n index number.

Returns: reference to element number n in underlying array.

Precondition: must be called in transaction scope.

Exceptions

std::out_of_range	if n is not within the range of the container.
pmem::transaction_error	when adding the object to the transaction failed.

◆ at() [2/2]

template<typename T >

vector< T >::const_reference pmem::obj::experimental::vector< T >::at ( size_type n ) const

Access element at specific index with bounds checking.

Parameters

[in] n index number.

Returns: const_reference to element number n in underlying array.

Exceptions

std::out_of_range if n is not within the range of the container.

◆ back() [1/2]

template<typename T >

vector< T >::reference pmem::obj::experimental::vector< T >::back ( )

Access the last element and add this element to a transaction.

Returns: reference to the last element in underlying array.

Precondition: must be called in transaction scope.

Exceptions

pmem::transaction_error when adding the object to the transaction failed.

◆ back() [2/2]

template<typename T >

vector< T >::const_reference pmem::obj::experimental::vector< T >::back ( ) const

Access the last element.

Returns: const_reference to the last element in underlying array.

◆ begin() [1/2]

template<typename T >

vector< T >::iterator pmem::obj::experimental::vector< T >::begin ( )

Returns an iterator to the beginning.

Returns: iterator pointing to the first element in the vector.

Precondition: must be called in transaction scope.

◆ begin() [2/2]

template<typename T >

vector< T >::const_iterator pmem::obj::experimental::vector< T >::begin ( ) const

noexcept

Returns const iterator to the beginning.

Returns: const_iterator pointing to the first element in the vector.

◆ capacity()

template<typename T >

vector< T >::size_type pmem::obj::experimental::vector< T >::capacity ( ) const

noexcept

Returns: number of elements that can be held in currently allocated storage

◆ cback()

template<typename T >

vector< T >::const_reference pmem::obj::experimental::vector< T >::cback ( ) const

Access the last element.

In contradiction to back(), cback() will return const_reference not depending on the const-qualification of the object it is called on. std::vector doesn't provide cback() method.

Returns: const_reference to the last element in underlying array.

◆ cbegin()

template<typename T >

vector< T >::const_iterator pmem::obj::experimental::vector< T >::cbegin ( ) const

noexcept

Returns const iterator to the beginning.

In contradiction to begin(), cbegin() will return const_iterator not depending on the const-qualification of the object it is called on.

Returns: const_iterator pointing to the first element in the vector.

◆ cdata()

template<typename T >

const vector< T >::value_type * pmem::obj::experimental::vector< T >::cdata ( ) const

noexcept

Returns const raw pointer to the underlying data.

In contradiction to data(), cdata() will return const_pointer not depending on the const-qualification of the object it is called on. std::vector doesn't provide cdata() method.

Returns: const_pointer to the underlying data.

◆ cend()

template<typename T >

vector< T >::const_iterator pmem::obj::experimental::vector< T >::cend ( ) const

noexcept

Returns a const iterator to the end.

In contradiction to end(), cend() will return const_iterator not depending on the const-qualification of the object it is called on.

Returns: const_iterator referring to the past-the-end element in the vector.

◆ cfront()

template<typename T >

vector< T >::const_reference pmem::obj::experimental::vector< T >::cfront ( ) const

Access the first element.

In contradiction to front(), cfront() will return const_reference not depending on the const-qualification of the object it is called on. std::vector doesn't provide cfront() method.

Returns: reference to first element in underlying array.

◆ const_at()

template<typename T >

vector< T >::const_reference pmem::obj::experimental::vector< T >::const_at ( size_type n ) const

Access element at specific index with bounds checking.

In contradiction to at(), const_at() will return const_reference not depending on the const-qualification of the object it is called on. std::vector doesn't provide const_at() method.

Parameters

[in] n index number.

Returns: const_reference to element number n in underlying array.

Exceptions

std::out_of_range if n is not within the range of the container.

◆ crbegin()

template<typename T >

vector< T >::const_reverse_iterator pmem::obj::experimental::vector< T >::crbegin ( ) const

noexcept

Returns a const reverse iterator to the beginning.

In contradiction to rbegin(), crbegin() will return const_reverse_iterator not depending on the const-qualification of the object it is called on.

Returns: const_reverse_iterator pointing to the last element in the vector.

◆ crend()

template<typename T >

vector< T >::const_reverse_iterator pmem::obj::experimental::vector< T >::crend ( ) const

noexcept

Returns a const reverse iterator to the beginning.

In contradiction to rend(), crend() will return const_reverse_iterator not depending on the const-qualification of the object it is called on.

Returns: const_reverse_iterator pointing to the theoretical element preceding the first element in the vector.

◆ data() [1/2]

template<typename T >

vector< T >::value_type * pmem::obj::experimental::vector< T >::data ( )

Returns raw pointer to the underlying data and adds entire array to a transaction.

Returns: pointer to the underlying data.

Precondition: must be called in transaction scope.

Exceptions

pmem::transaction_error when adding the object to the transaction failed.

◆ data() [2/2]

template<typename T >

const vector< T >::value_type * pmem::obj::experimental::vector< T >::data ( ) const

noexcept

Returns const raw pointer to the underlying data.

Returns: const_pointer to the underlying data.

◆ empty()

template<typename T >

constexpr bool pmem::obj::experimental::vector< T >::empty ( ) const

noexcept

Checks whether the container is empty.

Returns: true if container is empty, false otherwise.

◆ end() [1/2]

template<typename T >

vector< T >::iterator pmem::obj::experimental::vector< T >::end ( )

Returns an iterator to past the end.

Returns: iterator referring to the past-the-end element in the vector.

Precondition: must be called in transaction scope.

◆ end() [2/2]

template<typename T >

vector< T >::const_iterator pmem::obj::experimental::vector< T >::end ( ) const

noexcept

Returns a const iterator to past the end.

Returns: const_iterator referring to the past-the-end element in the vector.

◆ free_data()

template<typename T >

void pmem::obj::experimental::vector< T >::free_data ( )

Clears the content of a vector and frees all allocated persitent memory for data in transaction.

Postcondition: size() == 0; capacity() == 0; data() == nullptr

Exceptions

pmem::transaction_free_error when freeing underlying array failed.

◆ front() [1/2]

template<typename T >

vector< T >::reference pmem::obj::experimental::vector< T >::front ( )

Access the first element and add this element to a transaction.

Returns: reference to first element in underlying array.

Precondition: must be called in transaction scope.

Exceptions

pmem::transaction_error when adding the object to the transaction failed.

◆ front() [2/2]

template<typename T >

vector< T >::const_reference pmem::obj::experimental::vector< T >::front ( ) const

Access the first element.

Returns: const_reference to first element in underlying array.

◆ max_size()

template<typename T >

constexpr vector< T >::size_type pmem::obj::experimental::vector< T >::max_size ( ) const

noexcept

Returns: maximum number of elements the container is able to hold due to PMDK limitations.

◆ operator[]() [1/2]

template<typename T >

vector< T >::reference pmem::obj::experimental::vector< T >::operator[] ( size_type n )

Access element at specific index and add it to a transaction.

No bounds checking is performed.

Parameters

[in] n index number.

Returns: reference to element number n in underlying array.

Precondition: must be called in transaction scope.

Exceptions

pmem::transaction_error when adding the object to the transaction failed.

◆ operator[]() [2/2]

template<typename T >

vector< T >::const_reference pmem::obj::experimental::vector< T >::operator[] ( size_type n ) const

Access element at specific index.

No bounds checking is performed.

Parameters

[in] n index number.

Returns: const_reference to element number n in underlying array.

◆ rbegin() [1/2]

template<typename T >

vector< T >::reverse_iterator pmem::obj::experimental::vector< T >::rbegin ( )

Returns a reverse iterator to the beginning.

Returns: reverse_iterator pointing to the last element in the vector.

Precondition: must be called in transaction scope.

◆ rbegin() [2/2]

template<typename T >

vector< T >::const_reverse_iterator pmem::obj::experimental::vector< T >::rbegin ( ) const

noexcept

Returns a const reverse iterator to the beginning.

Returns: const_reverse_iterator pointing to the last element in the vector.

◆ rend() [1/2]

template<typename T >

vector< T >::reverse_iterator pmem::obj::experimental::vector< T >::rend ( )

Returns a reverse iterator to the end.

Returns: reverse_iterator pointing to the theoretical element preceding the first element in the vector.

Precondition: must be called in transaction scope.

◆ rend() [2/2]

template<typename T >

vector< T >::const_reverse_iterator pmem::obj::experimental::vector< T >::rend ( ) const

noexcept

Returns a const reverse iterator to the end.

Returns: const_reverse_iterator pointing to the theoretical element preceding the first element in the vector.

◆ size()

template<typename T >

vector< T >::size_type pmem::obj::experimental::vector< T >::size ( ) const

noexcept

Returns: number of elements.

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

libpmemobj++/experimental/vector.hpp

Public Member Functions

Private Member Functions

Detailed Description

template<typename T> class pmem::obj::experimental::vector< T >

Constructor & Destructor Documentation

◆ vector() [1/7]

◆ vector() [2/7]

◆ vector() [3/7]

◆ vector() [4/7]

◆ vector() [5/7]

◆ vector() [6/7]

◆ vector() [7/7]

◆ ~vector()

Member Function Documentation

◆ _alloc()

◆ _dealloc()

◆ _grow() [1/2]

◆ _grow() [2/2]

◆ _shrink()

◆ at() [1/2]

◆ at() [2/2]

◆ back() [1/2]

◆ back() [2/2]

◆ begin() [1/2]

◆ begin() [2/2]

◆ capacity()

◆ cback()

◆ cbegin()

◆ cdata()

◆ cend()

◆ cfront()

◆ const_at()

◆ crbegin()

◆ crend()

◆ data() [1/2]

◆ data() [2/2]

◆ empty()

◆ end() [1/2]

◆ end() [2/2]

◆ free_data()

◆ front() [1/2]

◆ front() [2/2]

◆ max_size()

◆ operator[]() [1/2]

◆ operator[]() [2/2]

◆ rbegin() [1/2]

◆ rbegin() [2/2]

◆ rend() [1/2]

◆ rend() [2/2]

◆ size()

template<typename T>
class pmem::obj::experimental::vector< T >