class ara::core::MemoryResource

The member function allocate of class ara::core::MemoryResource serves for allocating linear memory with a specified byte size and alignment [SWS_CORE_06503]. It is modeled on the C++ standard interface [mem.res], but deviates significantly in exception handling [SWS_CORE_06503].

Usage and Parameters

The call is synchronous via parameters bytes (number of bytes to request) and the optional alignment, which is set to alignof(std::max_align_t) by default [SWS_CORE_06503]. The return value is marked with attribute [[nodiscard]], which is why the returned pointer of type void* must be evaluated by the caller [SWS_CORE_06503].

Error Handling and Exception Safety

In contrast to standard behavior, the function does not throw an exception of type std::bad_alloc in case of error, but is declared as noexcept and considered exception-safe (exception safe) [SWS_CORE_06503]:

• Success: Returns a valid pointer to the allocated memory area according to [mem.res] [SWS_CORE_06503].
• Failure: If memory allocation fails, the function returns nullptr instead [SWS_CORE_06503]. The caller must therefore always explicitly check the result for a null pointer.

Concurrency and Interaction

The function is specified as not thread-safe (not thread-safe) [SWS_CORE_06503]. Parallel calls on the same instance of MemoryResource consequently require external synchronization by the caller. This fault-tolerant, exception-free pattern is found consistently in other memory components of AUTOSAR Adaptive: Thus, ara::core::PolymorphicAllocator::allocate uses the same approach without exceptions [SWS_CORE_06547], and the special instance NullMemoryResource also signals memory exhaustion by returning nullptr [SWS_CORE_06563].

Function deallocate of class ara::core::MemoryResource serves for deallocating memory areas according to [SWS_CORE_06504]. The usage generally follows the standard behavior from [mem.res], but exhibits specific deviations. The call takes place synchronously via signature void deallocate(void *p, std::size_t bytes, std::size_t alignment=max_align) noexcept, passing the pointer p to the block to be freed, the size bytes, as well as optionally the alignment [SWS_CORE_06504].

Regarding error behavior, the function is specified as noexcept and exception-safe (exception safe) [SWS_CORE_06504]. If deallocation fails, errors will be silently ignored (errors will be silently ignored) [SWS_CORE_06504]. No exceptions are thrown and no error messages are issued via DET or DEM.

With respect to concurrency, the function is explicitly classified as not thread-safe (not thread-safe) [SWS_CORE_06504]. Concurrent accesses to the same resource instance must therefore be synchronized externally by the caller.

In interaction with the allocator concept, this function corresponds to the typed interface deallocate of class ara::core::PolymorphicAllocator from [SWS_CORE_06548], which exhibits similar deviations regarding noexcept and silent error handling.

The pure virtual method do_allocate of class ara::core::MemoryResource serves for the allocation of memory blocks with a specified byte size and alignment [SWS_CORE_06566]. As parameters, it takes the number of bytes (bytes) as well as the required alignment (alignment). Upon successful allocation, it synchronously returns a pointer of type void * to the reserved memory area [SWS_CORE_06566].

With regard to error handling, the function purposefully deviates from the regular C++ standard: It is declared as noexcept and does not throw a std::bad_alloc exception on failure, but returns nullptr instead [SWS_CORE_06566]. Callers must therefore always check the allocation result for a null pointer.

Regarding concurrency, the method is specified as not thread-safe [SWS_CORE_06566]. Concurrent calls on the same instance require external synchronization unless the derived implementation provides its own protection. Due to the private visibility, invocation by users is likely to occur typically indirectly via the overarching interface of the base class. Question Q-5cbdabf121ed4550 (open)

In the interplay of memory management, the method forms the direct counterpart to do_deallocate, which is responsible for freeing the allocated memory and silently ignores errors [SWS_CORE_06567]. The comparison function do_is_equal furthermore checks whether two resource instances are compatible with each other regarding allocation and deallocation [SWS_CORE_06568].

The pure virtual member function do_deallocate of class ara::core::MemoryResource (declared in ara/core/memory_resource.h) serves according to [SWS_CORE_06567] for deallocating previously reserved memory. It accepts the pointer p to the memory area as well as its size bytes and required alignment alignment. The semantics basically correspond to the C++ standard [mem.res], but exhibit two significant adaptive-specific deviations [SWS_CORE_06567].

First, the function is declared as noexcept and guarantees exception safety (exception safe) [SWS_CORE_06567]. Second, any errors during deallocation are silently ignored, so that failed operations must neither throw error messages nor interrupt the program flow [SWS_CORE_06567].

Regarding concurrency, do_deallocate is specified as not thread-safe and has private visibility [SWS_CORE_06567]. As an implementation detail of a polymorphic memory resource, it is likely to be executed synchronously via the overarching public invocation interface. Question Q-3f97e122ee7fb281 (open) Competing deallocations on the same resource must be synchronized independently by derived classes if necessary.

In module core, the function forms the counterpart to allocation do_allocate [SWS_CORE_06566], which returns nullptr instead of an exception in the event of an error. Comparison with other resources is performed via the method do_is_equal [SWS_CORE_06568], which, in contrast to deallocation, is explicitly defined as thread-safe.

The pure virtual member function do_is_equal is declared in header #include "ara/core/memory_resource.h" in the namespace of ara::core::MemoryResource ([SWS_CORE_06568]). According to the C++ specification [mem.res], it serves for the synchronous equality comparison of the current memory resource with a passed reference const MemoryResource &other ([SWS_CORE_06568]). Since the method is defined with private visibility (private), its invocation is likely to be handled polymorphically as an implementation detail via the public interface of class ara::core::MemoryResource ([SWS_CORE_06568]). Question Q-cbe02f652b43d6ec (open)

Regarding execution and fault tolerance, do_is_equal is declared as exception safe as well as noexcept ([SWS_CORE_06568]). Accordingly, it must not throw exceptions under any circumstances and signals the result directly via the boolean return value ([SWS_CORE_06568]). In addition, the method is specified as thread-safe, so that derived implementations must guarantee thread safety even during concurrent comparisons ([SWS_CORE_06568]).

In interaction with the other virtual methods of memory management, do_is_equal completes the trio of customization points of derived resource classes ([SWS_CORE_06568]). While memory allocation do_allocate returns nullptr in case of error ([SWS_CORE_06566]) and do_deallocate silently ignores errors ([SWS_CORE_06567]), both functions, in contrast to do_is_equal, are designated as not thread-safe (not thread-safe) ([SWS_CORE_06566], [SWS_CORE_06567]). This emphasizes the special requirement on do_is_equal to safeguard concurrent resource comparisons ([SWS_CORE_06568]).