cetl::pf17::pmr::UnsynchronizedBufferMemoryResource Class Reference

#include "cetl/pf17/buffer_memory_resource.hpp"

Public Member Functions
	UnsynchronizedBufferMemoryResource (void *buffer, std::size_t buffer_size_bytes, cetl::pf17::pmr::memory_resource *upstream, std::size_t upstream_max_size_bytes) noexcept
	UnsynchronizedBufferMemoryResource (void *buffer, std::size_t buffer_size_bytes) noexcept
	UnsynchronizedBufferMemoryResource (const UnsynchronizedBufferMemoryResource &)=delete
UnsynchronizedBufferMemoryResource &	operator= (const UnsynchronizedBufferMemoryResource &)=delete
	UnsynchronizedBufferMemoryResource (UnsynchronizedBufferMemoryResource &&) noexcept=default
UnsynchronizedBufferMemoryResource &	operator= (UnsynchronizedBufferMemoryResource &&)=delete
void *	data () noexcept
const void *	data () const noexcept
std::size_t	size () const noexcept
Public Member Functions inherited from cetl::pf17::pmr::memory_resource
	memory_resource ()=default
	memory_resource (const memory_resource &rhs)=default
virtual	~memory_resource ()=default
memory_resource &	operator= (const memory_resource &rhs)=default
void *	allocate (std::size_t size_bytes, std::size_t alignment=alignof(std::max_align_t))
void	deallocate (void *p, std::size_t size_bytes, std::size_t alignment=alignof(std::max_align_t))
bool	is_equal (const memory_resource &rhs) const noexcept
std::size_t	max_size () const noexcept
void *	reallocate (void *ptr, std::size_t old_size_bytes, std::size_t new_size_bytes, std::size_t alignment=alignof(std::max_align_t))

Detailed Description

Implementation of cetl::pf17::pmr::memory_resource that uses cetl::pmr::UnsynchronizedBufferMemoryResourceDelegate as the internal implementation.

Examples

Using this class with STL containers:

cetl::pf17::pmr::UnsynchronizedBufferMemoryResource   aResource{small_message_buffer_.data, SmallMessageSizeBytes};
cetl::pf17::pmr::polymorphic_allocator<std::uint64_t> aAlloc{&aResource};
Message                                               a{aAlloc};
 
// The big "gotcha" when using UnsynchronizedArrayMemoryResource with STL containers is that you must reserve
// the size needed before you insert data into them. This is because UnsynchronizedArrayMemoryResource only
// allows one allocation at a time and vector, for example, will have two allocations outstanding as it
// geometrically grows its capacity as new items are added.
const std::size_t item_cout = SmallMessageSizeBytes / sizeof(decltype(aAlloc)::value_type);
a.data.reserve(item_cout);
 
std::cout << "BEFORE -> data size = " << a.data.size() << ", data capacity : " << a.data.capacity() << std::endl;
 
for (std::size_t i = 0; i < item_cout; ++i)
{
    a.data.push_back(i);
}
 
std::cout << "AFTER  -> data size = " << a.data.size() << ", data capacity : " << a.data.capacity() << std::endl;

Creating a small-buffer optimization using this class:

// BUT WAIT! THERE'S MORE! The UnsynchronizedArrayMemoryResource both slices and dices! That is, you can provide
// an upstream allocator to turn this into a "small buffer optimization" resource where the internal allocation
// is the small buffer and the upstream allocator becomes the larger allocator.
 
cetl::pf17::pmr::UnsynchronizedBufferMemoryResource bResource{small_message_buffer_.data,
                                                              SmallMessageSizeBytes,
                                                              cetl::pf17::pmr::new_delete_resource(),
                                                              std::numeric_limits<std::size_t>::max()};
 
cetl::pf17::pmr::polymorphic_allocator<std::uint64_t> bAlloc{&bResource};
Message                                               b{bAlloc};
 
// This time we won't reserve which should cause vector to do multiple allocations. We'll also insert
// a bunch more items than there is space in the small message buffer.
std::cout << "BEFORE -> data size = " << b.data.size() << ", data capacity : " << b.data.capacity() << std::endl;
 
const std::size_t item_cout = (SmallMessageSizeBytes / sizeof(decltype(bAlloc)::value_type)) * 100;
for (std::size_t i = 0; i < item_cout; ++i)
{
    b.data.push_back(i);
}
 
std::cout << "AFTER  -> data size = " << b.data.size() << ", data capacity : " << b.data.capacity() << std::endl;

Using two std::pmr::UnsynchronizedBufferMemoryResourceDelegate instances with std::vector:

// One more example: by using another UnsynchronizedArrayMemoryResource as an upstream for another
// UnsynchronizedArrayMemoryResource with the same-sized buffer you can use vector push_back without reserve up
// to the size of these buffers.
static cetl::pf17::byte                               upstream_buffer[SmallMessageSizeBytes];
cetl::pf17::pmr::UnsynchronizedBufferMemoryResource   cUpstreamResource{&upstream_buffer, SmallMessageSizeBytes};
cetl::pf17::pmr::UnsynchronizedBufferMemoryResource   cResource{small_message_buffer_.data,
                                                              SmallMessageSizeBytes,
                                                              &cUpstreamResource,
                                                              std::numeric_limits<std::size_t>::max()};
cetl::pf17::pmr::polymorphic_allocator<std::uint64_t> cAlloc{&cResource};
Message                                               c{cAlloc};
 
// We also won't reserve in this example which should cause vector to do multiple allocations. We'll insert
// exactly the number of items that will fit in the small message buffer. Because containers like vector use a
// geometric growth strategy for capacity we can't insert more than the capacity of one of the small message
// buffers but with two of them we can insert up to that capacity whereas with only one we would run out of
// memory well before we reached `SmallMessageSizeBytes / sizeof(decltype(cAlloc)::value_type)`.
std::cout << "BEFORE -> data size = " << c.data.size() << ", data capacity : " << c.data.capacity() << std::endl;
 
const std::size_t item_cout = SmallMessageSizeBytes / sizeof(decltype(cAlloc)::value_type);
for (std::size_t i = 0; i < item_cout; ++i)
{
    c.data.push_back(i);
}
 
std::cout << "AFTER  -> data size = " << c.data.size() << ", data capacity : " << c.data.capacity() << std::endl;
 
// Essentially, this technique is a double-buffering strategy where the "front" buffer is the
// vector data and the "back" buffer is used to move memory ahead of a reallocation (e.g. push_back or
// shrink_to_fit) and finally a swap. Of course, this is probably a lot of wasted memory movement but std::vector
// doesn't have any other way to do this. CETL's VariableLengthArray, however, is more aware of CETL PMR and can do
// much smarter things with array memory resources.
 

(See full example here...)

Constructor & Destructor Documentation

UnsynchronizedBufferMemoryResource() [1/2]

cetl::pf17::pmr::UnsynchronizedBufferMemoryResource::UnsynchronizedBufferMemoryResource ( void * buffer, std::size_t buffer_size_bytes, cetl::pf17::pmr::memory_resource * upstream, std::size_t upstream_max_size_bytes )

inlinenoexcept

See cetl::pmr::UnsynchronizedBufferMemoryResourceDelegate for details.

Parameters

buffer	The buffer to provide to cetl::pmr::UnsynchronizedBufferMemoryResourceDelegate.
buffer_size_bytes	The size of the buffer to provide to cetl::pmr::UnsynchronizedBufferMemoryResourceDelegate
upstream	The upstream memory resource to provide to cetl::pmr::UnsynchronizedBufferMemoryResourceDelegate. This cannot be null.
upstream_max_size_bytes	The maximum size of the upstream memory resource.

UnsynchronizedBufferMemoryResource() [2/2]

cetl::pf17::pmr::UnsynchronizedBufferMemoryResource::UnsynchronizedBufferMemoryResource ( void * buffer, std::size_t buffer_size_bytes )

inlinenoexcept

Constructor version that uses cetl::pf17::pmr::null_memory_resource as the upstream resource.

Parameters

buffer	The buffer to provide to cetl::pmr::UnsynchronizedBufferMemoryResourceDelegate.
buffer_size_bytes	The size of the buffer to provide to cetl::pmr::UnsynchronizedBufferMemoryResourceDelegate

References cetl::pf17::pmr::null_memory_resource().

Member Function Documentation

data() [1/2]

const void * cetl::pf17::pmr::UnsynchronizedBufferMemoryResource::data ( ) const

inlinenoexcept

Direct access to the internal data. It is generally not safe to use this memory directly.

data() [2/2]

void * cetl::pf17::pmr::UnsynchronizedBufferMemoryResource::data ( )

inlinenoexcept

Direct access to the internal data. It is generally not safe to use this memory directly.

References data().

Referenced by data().

Here is the caller graph for this function:

size()

std::size_t cetl::pf17::pmr::UnsynchronizedBufferMemoryResource::size ( ) const

inlinenoexcept

The size in bytes of the internal buffer.

---

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

• /__w/CETL/CETL/include/cetl/pf17/buffer_memory_resource.hpp