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

This class serves similar purpose to pmem::obj::string, but keeps the data within the same allocation as inline_string itself. More...

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

Public Member Functions
	basic_inline_string (basic_string_view< CharT, Traits > v)
	Constructs inline string from a string_view. More...
	basic_inline_string (size_type capacity)
	Constructs empty inline_string with specified capacity. More...
	basic_inline_string (const basic_inline_string &rhs)
	Copy constructor. More...
basic_inline_string &	operator= (const basic_inline_string &rhs)
	Copy assignment operator.
basic_inline_string &	operator= (basic_string_view< CharT, Traits > rhs)
	Assignment operator from string_view.
	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 (const basic_inline_string &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 &	assign (basic_string_view< CharT, Traits > rhs)
	Transactionally assign content of basic_string_view. More...

Private 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.

Detailed Description

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

This class serves similar purpose to pmem::obj::string, but keeps the data within the same allocation as inline_string itself.

The data is always kept right after the inline_string structure. It means that creating an object of inline_string must be 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;
}

Constructor & Destructor Documentation

basic_inline_string() [1/3]

template<typename CharT , typename Traits >

pmem::obj::experimental::basic_inline_string< CharT, Traits >::basic_inline_string

(

basic_string_view< CharT, Traits >

v

)

Constructs inline string from a string_view.

Exceptions

pool_error

if inline_string doesn't reside on pmem.

basic_inline_string() [2/3]

template<typename CharT , typename Traits >

pmem::obj::experimental::basic_inline_string< CharT, Traits >::basic_inline_string

(

size_type

capacity

)

Constructs empty inline_string with specified capacity.

Exceptions

pool_error

if inline_string doesn't reside on pmem.

basic_inline_string() [3/3]

template<typename CharT , typename Traits >

pmem::obj::experimental::basic_inline_string< CharT, Traits >::basic_inline_string

(

const basic_inline_string< CharT, Traits > &

rhs

)

Copy constructor.

Exceptions

pool_error

if inline_string doesn't reside on pmem.

Member Function Documentation

assign()

template<typename CharT , typename Traits >

basic_inline_string< CharT, Traits > & pmem::obj::experimental::basic_inline_string< CharT, Traits >::assign

(

basic_string_view< CharT, Traits >

rhs

)

Transactionally assign content of basic_string_view.

Exceptions

std::out_of_range

if rhs is larger than capacity.

at() [1/2]

template<typename CharT , typename Traits >

basic_inline_string< CharT, Traits >::reference pmem::obj::experimental::basic_inline_string< CharT, Traits >::at

(

size_type

p

)

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< CharT, Traits >::const_reference pmem::obj::experimental::basic_inline_string< CharT, Traits >::at

(

size_type

p

)

const

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< CharT, Traits >::size_type pmem::obj::experimental::basic_inline_string< CharT, Traits >::capacity

noexcept

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< CharT, Traits >::const_pointer pmem::obj::experimental::basic_inline_string< CharT, Traits >::cdata

noexcept

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< CharT, Traits >::compare ( const basic_inline_string< CharT, Traits > &  rhs ) const

noexcept

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< CharT, Traits >::pointer pmem::obj::experimental::basic_inline_string< CharT, Traits >::data

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< CharT, Traits >::const_pointer pmem::obj::experimental::basic_inline_string< CharT, Traits >::data

noexcept

Returns

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

operator[]() [1/2]

template<typename CharT , typename Traits >

basic_inline_string< CharT, Traits >::reference pmem::obj::experimental::basic_inline_string< CharT, Traits >::operator[]

(

size_type

p

)

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< CharT, Traits >::const_reference pmem::obj::experimental::basic_inline_string< CharT, Traits >::operator[] ( size_type  p ) const

noexcept

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< CharT, Traits >::pointer > pmem::obj::experimental::basic_inline_string< CharT, Traits >::range	(	size_type	start,
		size_type	n
	)

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

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< CharT, Traits >::size_type pmem::obj::experimental::basic_inline_string< CharT, Traits >::size

noexcept

Returns

size of the string

---

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

• libpmemobj++/experimental/inline_string.hpp