PMDK C++ bindings  1.13.0-git107.g7e59f08f
This is the C++ bindings documentation for PMDK's libpmemobj.
Public Types | Public Member Functions | Protected Member Functions | Protected Attributes | List of all members
pmem::obj::experimental::basic_inline_string< CharT, Traits > Class Template Reference
Experimental Containers

Pmem-only variation of pmem::obj::string, where data is kept right next to the inline_string structure. More...

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

Inherits pmem::obj::experimental::basic_inline_string_base< CharT, Traits >.

Public Types

using traits_type = Traits
 
using value_type = CharT
 
using size_type = std::size_t
 
using difference_type = std::ptrdiff_t
 
using reference = value_type &
 
using const_reference = const value_type &
 
using pointer = value_type *
 
using const_pointer = const value_type *
 

Public Member Functions

 basic_inline_string (basic_string_view< CharT, Traits > v)
 
 basic_inline_string (size_type capacity)
 
 basic_inline_string (const basic_inline_string &rhs)
 
basic_inline_string & operator= (const basic_inline_string &rhs)
 
 operator basic_string_view< CharT, Traits > () const
 Conversion operator to string_view.
 
size_type size () const noexcept
 
size_type capacity () const noexcept
 
pointer data ()
 Returns pointer to the underlying data and if there is an active transaction add entire data to a transaction. More...
 
const_pointer data () const noexcept
 
const_pointer cdata () const noexcept
 Returns const pointer to the underlying data. More...
 
int compare (basic_string_view< CharT, Traits > rhs) const noexcept
 Compares this inline_string with other. More...
 
reference operator[] (size_type p)
 Returns reference to a character at position. More...
 
const_reference operator[] (size_type p) const noexcept
 Returns reference to a character at position. More...
 
reference at (size_type p)
 Returns reference to a character at position. More...
 
const_reference at (size_type p) const
 Returns reference to a character at position. More...
 
slice< pointer > range (size_type p, size_type count)
 Returns slice and snapshots (if there is an active transaction) requested range. More...
 
basic_inline_string_base & assign (basic_string_view< CharT, Traits > rhs)
 Transactionally assign content of basic_string_view. More...
 

Protected Member Functions

pointer snapshotted_data (size_t p, size_t n)
 Return pointer to data at position p and if there is an active transaction snapshot elements from p to p + n.
 

Protected Attributes

obj::p< uint64_t > size_
 
obj::p< uint64_t > capacity_
 

Detailed Description

template<typename CharT, typename Traits = std::char_traits<CharT>>
class pmem::obj::experimental::basic_inline_string< CharT, Traits >

Pmem-only variation of pmem::obj::string, where data is kept right next to the inline_string structure.

Note
It can be kept only on pmem.

pmem::obj::experimental::basic_inline_string serves similar purpose to pmem::obj::string, but keeps the data within the same allocation as inline_string itself. It means, the data is always kept right after the inline_string structure.

Creating an object of inline_string must be hence done as follows:

  1. Allocate memory of sizeof(inline_string) + size of the characters string + sizeof('\0')
  2. Use emplace new() to create inline_string

Example:

struct Object {
Object(int x, const char *s) : x(x), s(s)
{
}
int x;
/* Using inline_string instead of pmem::obj::string reduces number of
* allocations and dereferences which cost much more than on DRAM.
*/
pmem::obj::experimental::inline_string s;
};
struct root {
pmem::obj::persistent_ptr<Object> o;
};
void
create_and_print_object(pmem::obj::pool<root> pop)
{
auto r = pop.root();
pmem::obj::transaction::run(pop, [&] {
/* String was already allocated in a previous app run. */
if (r->o)
return;
auto value = "example";
/* There must be space for the Object itself and "example"
* string. */
auto req_capacity =
sizeof(Object) + strlen(value) + sizeof('\0');
pmem::obj::allocator<void> a;
r->o = static_cast<pmem::obj::persistent_ptr<Object>>(
a.allocate(req_capacity));
new (r->o.get()) Object(1, value);
});
std::cout << r->o->s.data() << std::endl;
}
void
assign_and_print_object(pmem::obj::pool<root> pop)
{
auto r = pop.root();
auto new_value = "some new, longer value";
if (r->o->s.capacity() >= strlen(new_value)) {
/* If there is enough capacity, we can assign the new value. */
r->o->s.assign(new_value);
} else {
/* Otherwise we have to reallocate the whole object. */
pmem::obj::transaction::run(pop, [&] {
pmem::obj::allocator<void> a;
auto ptr =
static_cast<pmem::obj::persistent_ptr<Object>>(
a.allocate(sizeof(Object) +
strlen(new_value) + 1));
new (ptr.get()) Object(r->o->x, new_value);
pmem::obj::delete_persistent<Object>(r->o);
r->o = ptr;
});
}
std::cout << r->o->s.data() << std::endl;
}
pmem::obj::allocator
(EXPERIMENTAL) Encapsulates the information about the persistent memory allocation model using PMDK's...
Definition: allocator.hpp:467
pmem::obj::basic_transaction::run
static void run(obj::pool_base &pool, std::function< void()> tx, Locks &... locks)
Execute a closure-like transaction and lock locks.
Definition: transaction.hpp:676
pmem::obj::experimental::basic_inline_string
Pmem-only variation of pmem::obj::string, where data is kept right next to the inline_string structur...
Definition: inline_string.hpp:162
pmem::obj::persistent_ptr
Persistent pointer class.
Definition: persistent_ptr.hpp:153
pmem::obj::pool
PMEMobj pool class.
Definition: pool.hpp:482
pmem::obj::pool::root
persistent_ptr< T > root()
Retrieves pool's root object.
Definition: pool.hpp:644
pmem::obj::standard_alloc_policy::allocate
pointer allocate(size_type cnt, const_void_pointer=0)
Allocate storage for cnt objects of type T.
Definition: allocator.hpp:247

Constructor & Destructor Documentation

◆ basic_inline_string() [1/3]

template<typename CharT , typename Traits = std::char_traits<CharT>>
pmem::obj::experimental::basic_inline_string< CharT, Traits >::basic_inline_string ( basic_string_view< CharT, Traits >  v)
inline
Exceptions
pool_errorif inline string is not on pmem.

◆ basic_inline_string() [2/3]

template<typename CharT , typename Traits = std::char_traits<CharT>>
pmem::obj::experimental::basic_inline_string< CharT, Traits >::basic_inline_string ( size_type  capacity)
inline
Exceptions
pool_errorif inline string is not on pmem.

◆ basic_inline_string() [3/3]

template<typename CharT , typename Traits = std::char_traits<CharT>>
pmem::obj::experimental::basic_inline_string< CharT, Traits >::basic_inline_string ( const basic_inline_string< CharT, Traits > &  rhs)
inline
Exceptions
pool_errorif inline string is not on pmem.

Member Function Documentation

◆ assign()

template<typename CharT , typename Traits >
basic_inline_string_base< CharT, Traits > & pmem::obj::experimental::basic_inline_string_base< CharT, Traits >::assign ( basic_string_view< CharT, Traits >  rhs)
inherited

Transactionally assign content of basic_string_view.

Exceptions
std::out_of_rangeif rhs is larger than capacity.
pool_errorif inline string is not on pmem.

◆ at() [1/2]

template<typename CharT , typename Traits >
basic_inline_string_base< CharT, Traits >::reference pmem::obj::experimental::basic_inline_string_base< CharT, Traits >::at ( size_type  p)
inherited

Returns reference to a character at position.

Parameters
[in]pwith bounds checking and snapshot it if there is an active transaction.
Returns
reference to a CharT
Exceptions
pmem::transaction_errorwhen snapshotting failed.
std::out_of_rangeif p is not within the range of the container.

◆ at() [2/2]

template<typename CharT , typename Traits >
basic_inline_string_base< CharT, Traits >::const_reference pmem::obj::experimental::basic_inline_string_base< CharT, Traits >::at ( size_type  p) const
inherited

Returns reference to a character at position.

Parameters
[in]pwith bounds checking.
Returns
const_reference to a CharT
Exceptions
std::out_of_rangeif p is not within the range of the container.

◆ capacity()

template<typename CharT , typename Traits >
basic_inline_string_base< CharT, Traits >::size_type pmem::obj::experimental::basic_inline_string_base< CharT, Traits >::capacity
noexceptinherited
Returns
number of characters that can be held in the inline_string.

The space actually occupied by inline_string is equal to sizeof(inline_string) + capacity() + sizeof('\0') and cannot be expanded.

◆ cdata()

template<typename CharT , typename Traits >
basic_inline_string_base< CharT, Traits >::const_pointer pmem::obj::experimental::basic_inline_string_base< CharT, Traits >::cdata
noexceptinherited

Returns const 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.

Returns
const_pointer to the data (equal to (this + 1))

◆ compare()

template<typename CharT , typename Traits >
int pmem::obj::experimental::basic_inline_string_base< CharT, Traits >::compare ( basic_string_view< CharT, Traits >  rhs) const
noexceptinherited

Compares this inline_string with other.

Works in the same way as std::basic_string::compare.

Returns
0 if both character sequences compare equal, positive value if this is lexicographically greater than other, negative value if this is lexicographically less than other.

◆ data() [1/2]

template<typename CharT , typename Traits >
basic_inline_string_base< CharT, Traits >::pointer pmem::obj::experimental::basic_inline_string_base< CharT, Traits >::data
inherited

Returns pointer to the underlying data and if there is an active transaction add entire data to a transaction.

Returns
pointer to the data (equal to (this + 1))
Exceptions
pmem::transaction_errorwhen snapshotting failed.

◆ data() [2/2]

template<typename CharT , typename Traits >
basic_inline_string_base< CharT, Traits >::const_pointer pmem::obj::experimental::basic_inline_string_base< CharT, Traits >::data
noexceptinherited
Returns
const_pointer to the data (equal to (this + 1))

◆ operator[]() [1/2]

template<typename CharT , typename Traits >
basic_inline_string_base< CharT, Traits >::reference pmem::obj::experimental::basic_inline_string_base< CharT, Traits >::operator[] ( size_type  p)
inherited

Returns reference to a character at position.

Parameters
[in]pand snapshot it if there is an active transaction. No bounds checking is performed.
Returns
reference to a CharT
Exceptions
pmem::transaction_errorwhen snapshotting failed.

◆ operator[]() [2/2]

template<typename CharT , typename Traits >
basic_inline_string_base< CharT, Traits >::const_reference pmem::obj::experimental::basic_inline_string_base< CharT, Traits >::operator[] ( size_type  p) const
noexceptinherited

Returns reference to a character at position.

Parameters
[in]pNo bounds checking is performed.
Returns
const_reference to a CharT

◆ range()

template<typename CharT , typename Traits >
slice< typename basic_inline_string_base< CharT, Traits >::pointer > pmem::obj::experimental::basic_inline_string_base< CharT, Traits >::range ( size_type  start,
size_type  n 
)
inherited

Returns slice and snapshots (if there is an active transaction) requested range.

This method is not specified by STL standards.

Parameters
[in]startstart index of requested range.
[in]nnumber of elements in range.
Returns
pmem::obj::slice from start to start + n.
Exceptions
std::out_of_rangeif any element of the range would be outside of the container.
pmem::transaction_errorwhen snapshotting failed.

◆ size()

template<typename CharT , typename Traits >
basic_inline_string_base< CharT, Traits >::size_type pmem::obj::experimental::basic_inline_string_base< CharT, Traits >::size
noexceptinherited
Returns
size of the string
The documentation for this class was generated from the following file: