pmem::obj::experimental::basic_dram_inline_string< CharT, Traits > Class Template Reference

Pmem/DRAM 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_dram_inline_string (basic_string_view< CharT, Traits > v)
	basic_dram_inline_string (size_type capacity)
	basic_dram_inline_string (const basic_dram_inline_string &rhs)
basic_dram_inline_string &	operator= (const basic_dram_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_dram_inline_string< CharT, Traits >

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

Note

Unlike other containers, it can be used on pmem and dram. Modifiers (like assign()) can only be called if inline string is kept on pmem, though.

pmem::obj::experimental::basic_dram_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;
}

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_range	if rhs is larger than capacity.
pool_error	if 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]

p

with bounds checking and snapshot it if there is an active transaction.

Returns

reference to a CharT

Exceptions

pmem::transaction_error	when snapshotting failed.
std::out_of_range	if 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]

p

with bounds checking.

Returns

const_reference to a CharT

Exceptions

std::out_of_range

if 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_error

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

p

and snapshot it if there is an active transaction. No bounds checking is performed.

Returns

reference to a CharT

Exceptions

pmem::transaction_error

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

p

No 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]	start	start index of requested range.
[in]	n	number of elements in range.

Returns

pmem::obj::slice from start to start + n.

Exceptions

std::out_of_range	if any element of the range would be outside of the container.
pmem::transaction_error	when 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:

• libpmemobj++/experimental/inline_string.hpp