Add o1heapMinArenaSize; closes https://github.com/pavel-kirienko/o1heap/issues/17\#issuecomment-1518245157

Author: pavel-kirienko

o1heap/o1heap.c

@@ -14,7 +14,7 @@
 // Copyright (c) Pavel Kirienko
 // Authors: Pavel Kirienko <[email protected]>
 
-// ReSharper disable CppDFANullDereference
+// ReSharper disable CppDFANullDereference CppRedundantCastExpression
 
 #include "o1heap.h"
 #include <assert.h>
@@ -258,11 +258,12 @@ O1HEAP_PRIVATE void unbin(O1HeapInstance* const handle, const Fragment* const fr
 
 // ---------------------------------------- PUBLIC API IMPLEMENTATION ----------------------------------------
 
+const size_t o1heapMinArenaSize = INSTANCE_SIZE_PADDED + FRAGMENT_SIZE_MIN;
+
 O1HeapInstance* o1heapInit(void* const base, const size_t size)
 {
     O1HeapInstance* out = NULL;
-    if ((base != NULL) && ((((size_t) base) % O1HEAP_ALIGNMENT) == 0U) &&
-        (size >= (INSTANCE_SIZE_PADDED + FRAGMENT_SIZE_MIN)))
+    if ((base != NULL) && ((((size_t) base) % O1HEAP_ALIGNMENT) == 0U) && (size >= o1heapMinArenaSize))
     {
         // Allocate the core heap metadata structure in the beginning of the arena.
         O1HEAP_ASSERT(((size_t) base) % sizeof(O1HeapInstance*) == 0U);

o1heap/o1heap.h

@@ -66,6 +66,11 @@ typedef struct
     uint64_t oom_count;
 } O1HeapDiagnostics;
 
+/// o1heapInit() will fail unless the arena size is at least this large.
+/// This value depends only on the machine architecture.
+/// The other reason to fail is if the arena pointer is not aligned at O1HEAP_ALIGNMENT.
+extern const size_t o1heapMinArenaSize;
+
 /// The arena base pointer shall be aligned at O1HEAP_ALIGNMENT, otherwise NULL is returned.
 ///
 /// The total heap capacity cannot exceed approx. (SIZE_MAX/2). If the arena size allows for a larger heap,
@@ -76,10 +81,13 @@ typedef struct
 /// own needs (normally about 40..600 bytes depending on the architecture, but this parameter is not characterized).
 /// A pointer to the newly initialized instance is returned.
 ///
-/// If the provided space is insufficient, NULL is returned.
+/// The function fails and returns NULL iff:
+/// - The provided space is less than o1heapMinArenaSize.
+/// - The base pointer is not aligned at O1HEAP_ALIGNMENT.
+/// - The base pointer is NULL.
 ///
-/// An initialized instance does not hold any resources. Therefore, if the instance is no longer needed,
-/// it can be discarded without any de-initialization procedures.
+/// An initialized instance does not hold any resources except for the arena memory.
+/// Therefore, if the instance is no longer needed, it can be discarded without any de-initialization procedures.
 ///
 /// The heap is not thread-safe; external synchronization may be required.
 O1HeapInstance* o1heapInit(void* const base, const size_t size);

tests/test_general.cpp

@@ -562,6 +562,13 @@ TEST_CASE("General: random A")
     }
 }
 
+TEST_CASE("General: min arena size")
+{
+    alignas(128U) std::array<std::byte, 1024> arena{};
+    REQUIRE(nullptr == init(arena.data(), o1heapMinArenaSize - 1U));
+    REQUIRE(nullptr != init(arena.data(), o1heapMinArenaSize));
+}
+
 TEST_CASE("General: max allocation size")
 {
     alignas(128U) std::array<std::byte, 4096U + sizeof(internal::O1HeapInstance) + O1HEAP_ALIGNMENT - 1U> arena{};