cetl::pf17::pmr::memory_resource Class Reference

#include "cetl/pf17/memory_resource.hpp"

Public Member Functions
	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

Interface to a class that manages memory resources.

This implementation Adheres to memory_resource as defined by the C++17 specification. It does not incorporate changes made to this type in C++20.

Constructor & Destructor Documentation

memory_resource() [1/2]

cetl::pf17::pmr::memory_resource::memory_resource ( )

default

Implicitly defined default constructor.

Referenced by cetl::pf17::pmr::deviant::basic_monotonic_buffer_resource::do_is_equal(), cetl::pf17::pmr::deviant::MaxAlignNewDeleteResource::do_is_equal(), is_equal(), memory_resource(), and operator=().

Here is the caller graph for this function:

memory_resource() [2/2]

cetl::pf17::pmr::memory_resource::memory_resource ( const memory_resource & rhs )

default

Implicitly defined copy constructor.

Parameters

rhs	The object to copy from.

References memory_resource().

~memory_resource()

virtual cetl::pf17::pmr::memory_resource::~memory_resource ( )

virtualdefault

Implicitly defined destructor.

Member Function Documentation

allocate()

void * cetl::pf17::pmr::memory_resource::allocate ( std::size_t size_bytes, std::size_t alignment = alignof(std::max_align_t) )

inline

Allocate memory.

Allocates at least size_bytes of memory aligned to alignment by calling the template method do_allocate.

Example

Because C++14 does not provide portable, low-level memory allocators that support arbitrary alignment the ability for CETL to support over-alignment is limited. A possible implementation is proposed here to demonstrate:

    void* do_allocate(std::size_t size_bytes, std::size_t alignment) override
    {
        // The standard specifies a pre-condition that alignment is a power of two.
        CETL_DEBUG_ASSERT(alignment && !(alignment & (alignment - 1)), "Alignment must be a power of 2.");
 
        // This class has a precondition that the memory_resource pointer is not-null. We use a raw pointer
        // since the C++17 standard uses a similar pattern for an "upstream" allocator for the
        // std::pmr::monotonic_buffer_resource.
        if (nullptr == upstream_)
        {
#if defined(__cpp_exceptions)
            throw std::bad_alloc();
#endif
            return nullptr;
        }
 
        // Optimization here: if we are not over-aligning then just use the upstream allocator.
        if (alignment <= alignof(std::max_align_t))
        {
            return upstream_->allocate(size_bytes, alignment);
        }
 
        // This method will demonstrate an implementation of do_allocate that handles the alignment parameter using
        // only portable APIs available in C++14. We'll over-allocate from the system to store a MemoryBlock and
        // to ensure we can locate a starting pointer within the memory that is aligned to the requested power of 2.
 
        // We'll allocate the size of the MemoryBlock and also enforce that the size plus the padding added by the
        // compiler provides an alignof(std::max_align_t) aligned start to our aligned memory area.
        const std::size_t control_block_size_bytes =
            sizeof(MemoryBlock) + (sizeof(MemoryBlock) % alignof(std::max_align_t));
 
        // Now we adjust our allocation to account for over-alignment. For under-alignment we just waste memory.
        const std::size_t over_alignment = (alignment > alignof(std::max_align_t)) ? alignment : 0;
        const std::size_t upstream_size  = control_block_size_bytes + over_alignment + size_bytes;
 
        byte* const max_aligned_memory =
            static_cast<byte*>(upstream_->allocate(upstream_size, alignof(std::max_align_t)));
 
        if (nullptr == max_aligned_memory)
        {
            // we don't have to throw here because, if exceptions are enabled, the upstream call would have thrown.
            return nullptr;
        }
 
        // Time to setup RAII for our raw memory. We can reuse the MemoryBlockDeleter as long as we haven't yet
        // set the next_block pointer.
        MemoryBlockPointer cb(new (max_aligned_memory) MemoryBlock{nullptr, size_bytes, upstream_size, nullptr},
                              MemoryBlockDeleter(upstream_));
 
        // We expect all malloc implementations to return memory aligned to std::max_align_t.
        CETL_DEBUG_ASSERT((reinterpret_cast<std::uintptr_t>(max_aligned_memory) % alignof(std::max_align_t)) == 0,
                          "The upstream allocator must provide alignof(std::max_align_t) aligned memory!?");
 
        // Now we give the area after the MemoryBlock to std::align to do it's thing.
        void*       aligned_memory          = &static_cast<byte*>(max_aligned_memory)[control_block_size_bytes];
        std::size_t max_aligned_memory_size = upstream_size - control_block_size_bytes;
        aligned_memory = std::align(alignment, size_bytes, aligned_memory, max_aligned_memory_size);
 
        // If we get here then something about our expectations for over-allocation memory was wrong. Given this
        // is just example code we haven't rigorously proven that it will always be correct. UMMV.
        if (nullptr == aligned_memory || max_aligned_memory_size < size_bytes)
        {
#if defined(__cpp_exceptions)
            throw std::bad_alloc();
#endif
            return nullptr;
        }
 
        // One last sanity check but this failing would mean std::align was broken so we don't expect
        // this to ever fail given a correctly implemented C++14 library.
        CETL_DEBUG_ASSERT((reinterpret_cast<std::uintptr_t>(aligned_memory) % static_cast<std::uintptr_t>(alignment)) ==
                              0,
                          "Internal alignment math was incorrect and did not result in a properly aligned memory block "
                          "block.");
 
        // All that's left is the linked-list business.
        cb->aligned_memory = aligned_memory;
 
        if (nullptr == head_.get())
        {
            CETL_DEBUG_ASSERT(nullptr == tail_, "Tail must be null when head is null.");
            // This is the first. We establish the head of our linked list of
            // allocations here.
            head_.swap(cb);
            tail_ = head_.get();
        }
        else if (nullptr == tail_)
        {
            head_->next = cb.release();
            tail_       = head_->next;
        }
        else
        {
            tail_->next = cb.release();
            tail_       = tail_->next;
        }
 
        // We return the aligned region to the call. They must use this object to de_allocate or the behaviour
        // is undefined.
        return aligned_memory;
    }

(See full example here...)

Parameters

size_bytes	The number of bytes to allocate. Implementations may allocate additional bytes but shall not allocate fewer. Callers should always assume that a successful call has allocated exactly the requested number of bytes.
alignment	The alignment of the allocated memory. CETL will treat an inability to properly align memory as an allocation failure.

Returns

The allocated memory or std::nullptr if exceptions are disabled and an allocation failure occurs.

Exceptions

std::bad_alloc

Throws if any allocation errors occur. Implementations shall not leak memory even if the allocation fails.

deallocate()

void cetl::pf17::pmr::memory_resource::deallocate ( void * p, std::size_t size_bytes, std::size_t alignment = alignof(std::max_align_t) )

inline

Deallocate memory previous allocated by this class.

Deallocates memory by calling the template method do_deallocate. While the specification sets a precondition that p was returned by a call to cetl::pf17::pmr::memory_resource::allocate with the same size_bytes and alignment it does not require any errors to be raised if any of the inputs are invalid.

Example

See cetl::pf17::pmr::memory_resource::allocate for the first part of this example and a discussion of the limitations of CETL's implementations.

void do_deallocate(void* p, std::size_t size_bytes, std::size_t alignment) override
{
    // The standard does not actually specify what to do about size_bytes nor alignment in the deallocate method.
    // It does require that this method does not throw and, since there's no return value,
    // this means any failures to find and deallocate memory are silent.
    // We use alignment to detect which allocator was used and dispatch the deallocate call accordingly.
    if (alignment <= alignof(std::max_align_t))
    {
        upstream_->deallocate(p, size_bytes, alignment);
        return;
    }
    MemoryBlock* previous;
 
    MemoryBlock* cb = find(p, previous);
 
    // In a debug mode you might want to assert on conditions that shouldn't occur
    // in a healthy program.
    // Here we maintain the standard behaviour of C that deallocating nullptr is
    // not an error. We therefore only abort if p is not null AND we did not find a
    // control block OR p was null AND we somehow did find a control block
    // (that would be weird).
    CETL_DEBUG_ASSERT((p && cb) || (!p && !cb), "Unknown pointer provided to do_deallocate.");
 
    // Here we assert that, if we are deallocating a valid block, the size requested
    // by the call to do_allocate is the same size provided to this method.
    CETL_DEBUG_ASSERT(!p || cb->aligned_memory_size_bytes == size_bytes,
                      "Control Block size did not match size argument for do_deallocate.");
 
    if (nullptr != cb)
    {
        if (nullptr == previous)
        {
            // there was no previous block. This is the head we are deleting.
            CETL_DEBUG_ASSERT(cb == head_.get(), "find logic is incorrect");
            (void) head_.release();
            head_.reset(cb->next);
        }
        else
        {
            previous->next = cb->next;
        }
        if (cb == tail_)
        {
            tail_ = cb->next;
        }
        const std::size_t memory_block_size_bytes = cb->memory_block_size_bytes;
        cb->~MemoryBlock();
        upstream_->deallocate(cb, memory_block_size_bytes);
    }
}

(See full example here...)

Parameters

p	A pointer returned by cetl::pf17::pmr::memory_resource::allocate.
size_bytes	The size passed into cetl::pf17::pmr::memory_resource::allocate.
alignment	The alignment passed into cetl::pf17::pmr::memory_resource::allocate.

Exceptions

nothing

(but is not noexcept).

is_equal()

bool cetl::pf17::pmr::memory_resource::is_equal ( const memory_resource & rhs ) const

inlinenoexcept

Compares two memory_resource implementations by calling template method do_is_equal.

Parameters

rhs	The memory_resource to compare.

Returns

true if memory allocated from this object can be deallocated by rhs and vice-versa.

References memory_resource().

max_size()

std::size_t cetl::pf17::pmr::memory_resource::max_size ( ) const

inlinenoexcept

A necessary evil, this method deviates from std::pmr::memory_resource.

This means CETL's memory_allocator is not ABI compatible with std::pmr::memory_resource and std::pmr::memory_resource is not, necessarily, backwards compatible with CETL. Because CETL does not require RTTI, it is not an option to define a specialized interface that fixed size resources can implement since there is no way to determine the type of the resource or to safely cast to it.

Returns

The maximum size that can be allocated by this object.

Referenced by cetl::pf17::pmr::deviant::basic_monotonic_buffer_resource::do_allocate().

Here is the caller graph for this function:

operator=()

memory_resource & cetl::pf17::pmr::memory_resource::operator= ( const memory_resource & rhs )

default

Implicitly defined assignment operator.

Parameters

rhs	The object to assign from.

Returns

A reference to the assigned-to object (i.e. *this).

References memory_resource().

reallocate()

void * cetl::pf17::pmr::memory_resource::reallocate ( void * ptr, std::size_t old_size_bytes, std::size_t new_size_bytes, std::size_t alignment = alignof(std::max_align_t) )

inline

Reallocate memory.

Follows a similar behaviour contract described by std::reallocate with the implementation defined behaviour for zero-length reallocations is to always return nullptr.

Note

The behaviour of this method when called with a different alignment then used in the original allocation is implementation defined.

Parameters

ptr	The pointer to reallocate. If the reallocation is successful this pointer is invalid and must not be used even if it's address is the same as the returned pointer. This pointer remains valid for any failure.
old_size_bytes	The number of bytes returned by the original allocation.
new_size_bytes	The number of bytes to change ptr to hold.
alignment	The alignment of the allocated memory. CETL will treat an inability to properly align or to support re-alignment of memory as an allocation failure.

Returns

The allocated memory or std::nullptr if exceptions are disabled and an allocation failure occurs.

Exceptions

std::bad_alloc

Throws if any allocation errors occur. Implementations shall not leak memory even if the allocation fails.

---

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

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