SuperTinyKernel™ RTOS 1.08.x
Lightweight, high-performance, deterministic, bare-metal C++ RTOS for resource-constrained embedded systems. MIT Open Source License.
Loading...
Searching...
No Matches
stk_memory_blockpool.h
Go to the documentation of this file.
1/*
2 * SuperTinyKernel(TM) RTOS: Lightweight High-Performance Deterministic C++ RTOS for Embedded Systems.
3 *
4 * Source: https://github.com/SuperTinyKernel-RTOS
5 *
6 * Copyright (c) 2022-2026 Neutron Code Limited <stk@neutroncode.com>. All Rights Reserved.
7 * License: MIT License, see LICENSE for a full text.
8 */
9
10#ifndef STK_MEMORY_BLOCKPOOL_H_
11#define STK_MEMORY_BLOCKPOOL_H_
12
14#include "sync/stk_sync_cv.h"
15
21#ifndef STK_MEMORY_BLOCKPOOL_ALIGN_DEFAULT
22 #define STK_MEMORY_BLOCKPOOL_ALIGN_DEFAULT stk::memory::MemoryAllocator::MIN_ALIGNMENT
23#endif
24
32#ifndef STK_MEMORY_BLOCKPOOL_BITMAP
33 #define STK_MEMORY_BLOCKPOOL_BITMAP (0)
34#endif
35
39
40namespace stk {
41namespace memory {
42
133{
134public:
137 static const size_t CAPACITY_MAX = 0xFFFEU;
138
142
163 explicit BlockMemoryPool(size_t capacity, size_t raw_block_size, uint8_t *storage,
164 size_t storage_size, const char *name = nullptr,
165 size_t alignment = ALIGN_DEFAULT);
166
181#if STK_MEMORY_HAS_HEAP
182 explicit BlockMemoryPool(size_t capacity, size_t raw_block_size, const char *name = nullptr,
183 size_t alignment = ALIGN_DEFAULT);
184#endif
185
195
203 static constexpr size_t AlignBlockSize(size_t raw_size, size_t alignment = ALIGN_DEFAULT)
204 {
205 return Max(alignment, ((raw_size + (alignment - 1U)) & ~(alignment - 1U)));
206 }
207
211 static constexpr size_t BitmapBytes(size_t capacity)
212 {
213 return ((STK_MEMORY_BLOCKPOOL_BITMAP != 0) ? ((capacity + 7U) / 8U) : 0U);
214 }
215
227 static constexpr size_t RequiredStorageSize(size_t capacity, size_t raw_block_size, size_t alignment = ALIGN_DEFAULT)
228 {
229 return ((capacity * AlignBlockSize(raw_block_size, alignment)) + BitmapBytes(capacity));
230 }
231
246 void *TimedAlloc(Timeout timeout_ticks = WAIT_INFINITE);
247
264 EWaitResult TimedAllocEx(void **block, Timeout timeout_ticks = WAIT_INFINITE);
265
274 template <typename T> T *TimedAllocT(Timeout timeout_ticks = WAIT_INFINITE);
275
282 void *Alloc();
283
289 template <typename T> T *AllocT();
290
298 void *TryAlloc();
299
306 template <typename T> T *TryAllocT();
307
308#if STK_MEMORY_PLACEMENT_NEW
309
316 template <typename T, typename... TArgs> T *TimedNewT(Timeout timeout_ticks, TArgs &&...args);
317
321 template <typename T, typename... TArgs> T *NewT(TArgs &&...args);
322
325 template <typename T, typename... TArgs> T *TryNewT(TArgs &&...args);
326
331 template <typename T> void DeleteT(T *ptr);
332
335 template <typename T, typename... TArgs> PoolPtr<T, BlockMemoryPool> TryMakeT(TArgs &&...args);
336
340 template <typename T, typename... TArgs> PoolPtr<T, BlockMemoryPool> MakeT(TArgs &&...args);
341
342#endif // STK_MEMORY_PLACEMENT_NEW
343
364 bool Free(void *ptr);
365
374 bool IsStorageValid() const { return ((m_blocks != nullptr) && (m_capacity != 0U)); }
375
382 size_t GetCapacity() const { return m_capacity; }
383
390 size_t GetBlockSize() const { return m_block_size; }
391
395 size_t GetBlockAlignment() const { return m_block_align; }
396
402 size_t GetUsedCount() const { return m_used_count; }
403
409 size_t GetFreeCount() const { return (m_capacity - m_used_count); }
410
415 size_t GetPeakUsedCount() const { return ((m_block_size != 0U) ? (m_stats.peak_allocated / m_block_size) : 0U); }
416
421 size_t GetAllocFailCount() const { return m_stats.alloc_fail_count; }
422
429
434 bool IsFull() const { return (GetFreeCount() == 0U); }
435
440 bool IsEmpty() const { return (m_used_count == 0U); }
441
442private:
444
451 {
453 };
454
455 static const uint8_t FILL_ALLOC = 0xCDU;
456 static const uint8_t FILL_FREE = 0xDDU;
457
460 static bool IsValidAlignment(size_t alignment)
461 {
462 return ((alignment >= sizeof(MemoryBlock)) && ((alignment & (alignment - 1U)) == 0U));
463 }
464
467 static bool ArgsValid(size_t capacity, size_t raw_block_size, size_t alignment, size_t block_size)
468 {
469 return ((capacity > 0U) && (capacity <= CAPACITY_MAX) && (raw_block_size > 0U) &&
470 IsValidAlignment(alignment) && (block_size >= raw_block_size));
471 }
472
476 void Setup(size_t raw_block_size, size_t alignment);
477
485
489 void *PopFreeList();
490
493 static __stk_forceinline void Fill(void *ptr, size_t size, uint8_t value)
494 {
495 STK_MEMSET(ptr, value, size);
496 }
497
498#if STK_MEMORY_BLOCKPOOL_BITMAP
499 bool BitmapTest(size_t index) const { return ((m_bitmap[index >> 3U] & static_cast<uint8_t>(1U << (index & 7U))) != 0U); }
500 void BitmapSet(size_t index) { m_bitmap[index >> 3U] = static_cast<uint8_t>(m_bitmap[index >> 3U] | static_cast<uint8_t>(1U << (index & 7U))); }
501 void BitmapClear(size_t index) { m_bitmap[index >> 3U] = static_cast<uint8_t>(m_bitmap[index >> 3U] & static_cast<uint8_t>(~(1U << (index & 7U)))); }
502#endif
503
504 uint8_t *m_storage;
505 uint8_t *m_blocks;
506 uint8_t *m_bitmap;
512 size_t m_capacity;
516};
517
518// ---------------------------------------------------------------------------
519// Constructors / Destructor
520// ---------------------------------------------------------------------------
521
522inline BlockMemoryPool::BlockMemoryPool(size_t capacity, size_t raw_block_size, uint8_t *storage,
523 size_t storage_size, const char *name, size_t alignment)
524: m_storage(storage),
525 m_blocks(nullptr),
526 m_bitmap(nullptr),
527 m_free_list(nullptr),
528 m_cv(),
529 m_storage_size(storage_size),
530 m_block_size(AlignBlockSize(raw_block_size, alignment)),
531 m_block_align(alignment),
532 m_capacity(capacity),
533 m_used_count(0U),
534 m_stats(capacity * m_block_size),
535 m_storage_owned(false)
536{
537 STK_ASSERT(storage != nullptr);
538
539#if STK_SYNC_DEBUG_NAMES
540 SetTraceName(name);
541#else
542 STK_UNUSED(name);
543#endif
544
545 Setup(raw_block_size, alignment);
546}
547
548#if STK_MEMORY_HAS_HEAP
549inline BlockMemoryPool::BlockMemoryPool(size_t capacity, size_t raw_block_size, const char *name,
550 size_t alignment)
551: m_storage(nullptr),
552 m_blocks(nullptr),
553 m_bitmap(nullptr),
554 m_free_list(nullptr),
555 m_cv(),
556 m_storage_size(0U),
557 m_block_size(AlignBlockSize(raw_block_size, alignment)),
558 m_block_align(alignment),
559 m_capacity(capacity),
560 m_used_count(0U),
561 m_stats(capacity * m_block_size),
562 m_storage_owned(true)
563{
564#if STK_SYNC_DEBUG_NAMES
565 SetTraceName(name);
566#else
567 STK_UNUSED(name);
568#endif
569
570 if (ArgsValid(capacity, raw_block_size, alignment, m_block_size))
571 {
572 // total = blocks + bitmap (AllocateAligned() aligns the start itself, no slack is needed);
573 // every step is checked so that a huge capacity * block size can not wrap around
574 const size_t max_size = static_cast<size_t>(~static_cast<size_t>(0U));
575 const size_t bitmap = BitmapBytes(capacity);
576
577 if ((capacity <= (max_size / m_block_size)) &&
578 ((capacity * m_block_size) <= (max_size - bitmap)))
579 {
580 const size_t total = ((capacity * m_block_size) + bitmap);
581
582 m_storage = static_cast<uint8_t *>(MemoryAllocator::AllocateAligned(total, alignment));
583 if (m_storage != nullptr)
584 {
585 m_storage_size = total;
586 }
587 }
588 }
589
590 // else: m_blocks remains nullptr; caller must check IsStorageValid()
591 Setup(raw_block_size, alignment);
592}
593#endif
594
596{
597 // ConditionVariable destructor asserts the wait list is empty
598 STK_ASSERT(m_used_count == 0U); // all blocks must be returned before the pool goes away
599
600#if STK_MEMORY_HAS_HEAP
601 if (m_storage_owned && (m_storage != nullptr))
602 {
604 m_storage = nullptr;
605 }
606#endif
607
608 m_blocks = nullptr;
609}
610
611// ---------------------------------------------------------------------------
612// Alloc / TimedAlloc / TryAlloc
613// ---------------------------------------------------------------------------
614
615inline EWaitResult BlockMemoryPool::TimedAllocEx(void **block, Timeout timeout_ticks)
616{
618
619 STK_ASSERT(block != nullptr); // API contract: output pointer must be valid
620
621 if (block == nullptr)
622 {
623 // result is WAIT_RESULT_FAIL already, so noop
624 }
625 else
626 {
627 *block = nullptr;
628
629 if ((timeout_ticks != NO_WAIT) && hw::IsInsideISR())
630 {
631 STK_ASSERT(false); // API contract: ISR callers must pass NO_WAIT / use TryAlloc()
632 }
633 else if (!IsStorageValid())
634 {
635 // result is WAIT_RESULT_FAIL: an invalid pool can never produce a block, so do not block on it
636 }
637 else
638 {
640
641 const bool timed_wait = (timeout_ticks != WAIT_INFINITE) && (timeout_ticks != NO_WAIT);
642
643 // capture an absolute deadline once, before entering the wait loop; a different
644 // allocator (TryAlloc() from another task or an ISR) can steal the just-freed
645 // block between NotifyOne_CS() and this task re-acquiring the critical section
646 // (Mesa-style wakeup, not a direct handoff - see Free()'s note), so re-passing
647 // the original timeout_ticks on each retry would silently restart it;
648 // kept as 64-bit Ticks (not truncated to Timeout) so it can't wrap on long uptimes
649 const Ticks deadline = (timed_wait ? (GetTicks() + static_cast<Ticks>(timeout_ticks)) : 0);
650
651 result = WAIT_RESULT_SIGNAL; // fast path: a block is already available
652
653 while (m_free_list == nullptr)
654 {
655 Timeout remaining = timeout_ticks;
656
657 if (timeout_ticks == NO_WAIT)
658 {
659 // no waiting requested (ISR-safe path): never touch the condition variable
660 result = WAIT_RESULT_TIMEOUT;
661 break;
662 }
663
664 if (timed_wait)
665 {
666 const Ticks left = (deadline - GetTicks());
667 if (left <= 0)
668 {
669 result = WAIT_RESULT_TIMEOUT; // budget is spent and the free-list was just checked
670 break;
671 }
672 remaining = static_cast<Timeout>(left);
673 }
674
675 // Atomically release the critical section, suspend the task, and
676 // re-acquire before returning - no CPU cycles wasted while waiting.
677 result = m_cv.WaitEx(cs_, remaining);
678 if (result != WAIT_RESULT_SIGNAL)
679 {
680 break; // timeout, cancellation or kernel failure: report as is
681 }
682 }
683
684 // timeout raced with a Free(): the lock was re-acquired and a block is available,
685 // so honor it instead of reporting a failure (cancellation is never overridden)
686 if ((result == WAIT_RESULT_TIMEOUT) && (m_free_list != nullptr))
687 {
688 result = WAIT_RESULT_SIGNAL;
689 }
690
691 // only allocate a block if the wait ended in a signal (or none was needed)
692 if (result == WAIT_RESULT_SIGNAL)
693 {
694 *block = PopFreeList();
695 }
696 else if (result == WAIT_RESULT_TIMEOUT)
697 {
698 m_stats.RecordAllocFail();
699 }
700 else
701 {
702 // cancellation or kernel failure is not pool exhaustion: not counted
703 }
704 }
705 }
706
707 return result;
708}
709
710inline void *BlockMemoryPool::TimedAlloc(Timeout timeout_ticks)
711{
712 void *block = nullptr;
713
714 if (TimedAllocEx(&block, timeout_ticks) != WAIT_RESULT_SIGNAL)
715 {
716 block = nullptr;
717 }
718
719 return block;
720}
721
722template <typename T>
723inline T *BlockMemoryPool::TimedAllocT(Timeout timeout_ticks)
724{
725 T *result = nullptr;
726
727 STK_ASSERT(sizeof(T) <= m_block_size); // API contract: block size should be larger or equal to object's size
728 STK_ASSERT(alignof(T) <= m_block_align); // API contract: blocks are aligned to the pool alignment only
729
730 // refuse (rather than hand out an undersized or misaligned block) in release builds too
731 if ((sizeof(T) <= m_block_size) && (alignof(T) <= m_block_align))
732 {
733 result = static_cast<T *>(TimedAlloc(timeout_ticks));
734 }
735
736 return result;
737}
738
740{
742}
743
744template <typename T>
746{
748}
749
751{
752 return TimedAlloc(NO_WAIT);
753}
754
755template <typename T>
757{
758 return TimedAllocT<T>(NO_WAIT);
759}
760
761// ---------------------------------------------------------------------------
762// Typed object helpers
763// ---------------------------------------------------------------------------
764
765#if STK_MEMORY_PLACEMENT_NEW
766
767template <typename T, typename... TArgs>
768inline T *BlockMemoryPool::TimedNewT(Timeout timeout_ticks, TArgs &&...args)
769{
770 T *const ptr = TimedAllocT<T>(timeout_ticks);
771
772 if (ptr != nullptr)
773 {
774 auto const obj = new (static_cast<void *>(ptr)) T(static_cast<TArgs &&>(args)...);
775 STK_UNUSED(obj);
776 }
777
778 return ptr;
779}
780
781template <typename T, typename... TArgs>
782inline T *BlockMemoryPool::NewT(TArgs &&...args)
783{
784 return TimedNewT<T>(WAIT_INFINITE, static_cast<TArgs &&>(args)...);
785}
786
787template <typename T, typename... TArgs>
788inline T *BlockMemoryPool::TryNewT(TArgs &&...args)
789{
790 return TimedNewT<T>(NO_WAIT, static_cast<TArgs &&>(args)...);
791}
792
793template <typename T>
794inline void BlockMemoryPool::DeleteT(T *ptr)
795{
796 if (ptr != nullptr)
797 {
798 ptr->~T();
799
800 const bool freed = Free(ptr);
801 STK_UNUSED(freed);
802 }
803}
804
805template <typename T, typename... TArgs>
807{
808 return PoolPtr<T, BlockMemoryPool>(TryNewT<T>(static_cast<TArgs &&>(args)...), this);
809}
810
811template <typename T, typename... TArgs>
813{
814 return PoolPtr<T, BlockMemoryPool>(NewT<T>(static_cast<TArgs &&>(args)...), this);
815}
816
817#endif // STK_MEMORY_PLACEMENT_NEW
818
819// ---------------------------------------------------------------------------
820// Free
821// ---------------------------------------------------------------------------
822
823inline bool BlockMemoryPool::Free(void *ptr)
824{
825 bool success = false;
826
827 if ((ptr != nullptr) && (m_blocks != nullptr))
828 {
829 // bounds check: ptr must be in range [m_blocks, m_blocks + capacity * block_size)
830 const Word pt = hw::PtrToWord(ptr);
831 const Word lo = hw::PtrToWord(m_blocks);
832 const Word hi = lo + (m_capacity * m_block_size);
833
834 if ((pt < lo) || (pt >= hi))
835 {
836 STK_ASSERT(false); // API contract: ptr does not belong to this pool
837 }
838 // alignment check: ptr must be at the start of a block boundary
839 else if ((static_cast<size_t>(pt - lo) % m_block_size) != 0U)
840 {
841 STK_ASSERT(false); // API contract: ptr is misaligned (not a block start)
842 }
843 else
844 {
846
847 if (m_used_count == 0U)
848 {
849 STK_ASSERT(false); // pool is already fully free - definite double-free
850 }
851 else
852 {
853 bool valid = true;
854
855 #if STK_MEMORY_BLOCKPOOL_BITMAP
856 // O(1) double-free detection that stays active in release builds
857 const size_t index = (static_cast<size_t>(pt - lo) / m_block_size);
858
859 if (!BitmapTest(index))
860 {
861 STK_ASSERT(false); // double-free: block is not marked as allocated
862 valid = false;
863 }
864 else
865 {
866 BitmapClear(index);
867 }
868 #elif STK_MEMORY_POOL_CHECKS
869 // O(n) double-free detection: walk the free-list and check if ptr is already on it,
870 // only active if STK_MEMORY_POOL_CHECKS is enabled - compiles away completely otherwise
871 for (const MemoryBlock *node = m_free_list; (node != nullptr); node = node->next)
872 {
873 if (node == reinterpret_cast<const MemoryBlock *>(ptr))
874 {
875 STK_ASSERT(false); // double-free: ptr is already on the free-list
876 valid = false;
877 break;
878 }
879 }
880 #endif
881
882 if (valid)
883 {
884 #if STK_MEMORY_POOL_CHECKS
885 // poison everything except the link word that is written below
886 Fill(static_cast<uint8_t *>(ptr) + sizeof(MemoryBlock), (m_block_size - sizeof(MemoryBlock)), FILL_FREE);
887 #endif
888
889 // push block onto free-list head (O(1))
890 auto *const blk = reinterpret_cast<MemoryBlock *>(ptr);
891 blk->next = m_free_list;
892 m_free_list = blk;
893 m_used_count = (m_used_count - 1U);
894 m_stats.RecordFree(m_block_size);
895
896 // wake one blocked allocator - true scheduler wait, no spin-yield
897 m_cv.NotifyOne_CS();
898
899 success = true;
900 }
901 }
902 }
903 }
904
905 return success;
906}
907
908// ---------------------------------------------------------------------------
909// Statistics
910// ---------------------------------------------------------------------------
911
913{
915
916 return m_stats;
917}
918
919// ---------------------------------------------------------------------------
920// Private helpers
921// ---------------------------------------------------------------------------
922
923inline void BlockMemoryPool::Setup(size_t raw_block_size, size_t alignment)
924{
925 const size_t requested = m_capacity;
926
927 m_blocks = nullptr;
928 m_bitmap = nullptr;
929 m_free_list = nullptr;
930 m_capacity = 0U;
931 m_used_count = 0U;
932
933 STK_ASSERT(requested > 0U);
934 STK_ASSERT(requested <= CAPACITY_MAX);
935 STK_ASSERT(raw_block_size > 0U);
936 STK_ASSERT(IsValidAlignment(alignment));
937
938 if (ArgsValid(requested, raw_block_size, alignment, m_block_size) && (m_storage != nullptr))
939 {
940 // align the start of the first block, the unaligned head bytes are not used
941 const size_t addr = static_cast<size_t>(hw::PtrToWord(m_storage));
942 const size_t shift = (((addr + (alignment - 1U)) & ~(alignment - 1U)) - addr);
943 const size_t usable = ((m_storage_size > shift) ? (m_storage_size - shift) : 0U);
944
945 // trim the capacity to what fits (blocks + optional bitmap); never exceeds usable, so no overflow
946 size_t n = (usable / m_block_size);
947 if (n > requested)
948 {
949 n = requested;
950 }
951
952 while ((n > 0U) && (((n * m_block_size) + BitmapBytes(n)) > usable))
953 {
954 --n;
955 }
956
957 // API contract: caller-supplied buffer must be large enough (after alignment);
958 // in Release builds the capacity is trimmed to fit instead
959 STK_ASSERT(n == requested);
960
961 if (n > 0U)
962 {
963 m_blocks = (m_storage + shift);
964 m_capacity = n;
965 m_bitmap = (m_blocks + (n * m_block_size));
966
968 }
969 }
970
971 // the real capacity is known only now (trimmed to the storage, 0 if the pool is invalid)
973}
974
976{
978
979 m_free_list = nullptr;
980 m_used_count = 0U;
981
982#if STK_MEMORY_BLOCKPOOL_BITMAP
983 for (size_t i = 0U; i < BitmapBytes(m_capacity); ++i)
984 {
985 m_bitmap[i] = 0U;
986 }
987#endif
988
989 // Link blocks in reverse order so m_free_list ends up pointing at block_0
990 // (lowest address), giving ascending allocation order.
991 for (size_t i = m_capacity; i-- > 0U; )
992 {
994
995 blk->next = m_free_list;
996 m_free_list = blk;
997 }
998}
999
1001{
1003
1004 MemoryBlock *const blk = m_free_list;
1005
1006 m_free_list = blk->next;
1007 m_used_count = (m_used_count + 1U);
1008
1009 m_stats.RecordAllocate(m_block_size);
1010
1011#if STK_MEMORY_BLOCKPOOL_BITMAP
1012 BitmapSet(static_cast<size_t>(hw::PtrToWord(blk) - hw::PtrToWord(m_blocks)) / m_block_size);
1013#endif
1014
1015#if STK_MEMORY_POOL_CHECKS
1017#endif
1018
1019 return blk;
1020}
1021
1022// ---------------------------------------------------------------------------
1023// StaticBlockPool - zero-heap pool that embeds its own, correctly sized and aligned storage
1024// ---------------------------------------------------------------------------
1025
1026namespace detail {
1027
1031template <size_t TBlockSize, size_t TCapacity, size_t TAlign>
1033{
1034 alignas(TAlign) uint8_t m_buf[BlockMemoryPool::RequiredStorageSize(TCapacity, TBlockSize, TAlign)];
1035};
1036
1037} // namespace detail
1038
1051template <size_t TBlockSize, size_t TCapacity, size_t TAlign = BlockMemoryPool::ALIGN_DEFAULT>
1052class StaticBlockPool : private detail::BlockPoolStorage<TBlockSize, TCapacity, TAlign>,
1053 public BlockMemoryPool
1054{
1055 STK_STATIC_ASSERT_DESC(TBlockSize > 0U, "block size must be greater than zero");
1056 STK_STATIC_ASSERT_DESC((TCapacity > 0U) && (TCapacity <= BlockMemoryPool::CAPACITY_MAX), "invalid capacity");
1057 STK_STATIC_ASSERT_DESC((TAlign >= sizeof(void *)) && ((TAlign & (TAlign - 1U)) == 0U),
1058 "alignment must be a power of two not less than sizeof(void *)");
1059
1060public:
1061 explicit StaticBlockPool(const char *name = nullptr)
1062 : BlockMemoryPool(TCapacity, TBlockSize, this->m_buf, sizeof(this->m_buf), name, TAlign)
1063 {}
1064};
1065
1066#if STK_MEMORY_PLACEMENT_NEW
1069template <typename T, size_t N>
1071 ((alignof(T) > BlockMemoryPool::ALIGN_DEFAULT) ? alignof(T) : BlockMemoryPool::ALIGN_DEFAULT)>;
1072#endif
1073
1074} // namespace memory
1075} // namespace stk
1076
1077#endif /* STK_MEMORY_BLOCKPOOL_H_ */
Memory allocator front-end with checked API and its weak backend hooks: stk::memory::MemoryAllocator.
#define STK_MEMORY_BLOCKPOOL_ALIGN_DEFAULT
Default block alignment (bytes, power of two, not less than sizeof(void *)) used when a pool is const...
#define STK_MEMORY_BLOCKPOOL_BITMAP
When defined as 1, BlockMemoryPool keeps one "allocated" bit per block (capacity/8 bytes,...
#define STK_UNUSED(X)
Explicitly marks a variable as unused to suppress compiler warnings.
Definition stk_defs.h:715
#define __stk_forceinline
Forces compiler to always inline the decorated function, regardless of optimisation level.
Definition stk_defs.h:270
#define STK_ASSERT(e)
Runtime assertion. Halts execution if the expression e evaluates to false.
Definition stk_defs.h:532
#define STK_VIRT_DTOR
Expands to nothing if STK_STRICT_COMPLIANCY=0 (non-virtual destructors, smaller objects),...
Definition stk_defs.h:254
Implementation of synchronization primitive: stk::sync::ConditionVariable.
Namespace of STK package.
uintptr_t Word
Native processor word type.
Definition stk_common.h:206
static constexpr Timeout NO_WAIT
Timeout value: return immediately if the synchronization object is not yet signaled (non-blocking pol...
Definition stk_common.h:280
EWaitResult
Wait result (see IKernelService::Wait).
Definition stk_common.h:138
@ WAIT_RESULT_FAIL
IKernelService::Wait returned with error without waiting.
Definition stk_common.h:139
@ WAIT_RESULT_TIMEOUT
The wake was caused by a timeout expiry.
Definition stk_common.h:141
@ WAIT_RESULT_SIGNAL
The wake was caused by a signal.
Definition stk_common.h:140
int64_t Ticks
Ticks value.
Definition stk_common.h:221
int32_t Timeout
Timeout time (ticks).
Definition stk_common.h:216
constexpr T Max(T a, T b) noexcept
Compile-time maximum of two values.
Definition stk_defs.h:758
void STK_MEMSET(void *const dest, uint8_t value, size_t size)
Implementation of STK_MEMSET.
Definition stk_arch.h:823
static Ticks GetTicks()
Get number of ticks elapsed since kernel start.
Definition stk_helper.h:448
static constexpr Timeout WAIT_INFINITE
Timeout value: block indefinitely until the synchronization object is signaled.
Definition stk_common.h:274
static T * WordToPtr(Word value) noexcept
Cast a CPU register-width integer back to a pointer.
Definition stk_arch.h:232
static Word PtrToWord(T *const ptr) noexcept
Cast a pointer to a CPU register-width integer.
Definition stk_arch.h:215
bool IsInsideISR()
Check whether the CPU is currently executing inside a hardware interrupt service routine (ISR).
StaticBlockPool< sizeof(T), N,((alignof(T) > BlockMemoryPool::ALIGN_DEFAULT) ? alignof(T) :BlockMemoryPool::ALIGN_DEFAULT)> StaticBlockPoolFor
Pool of N blocks sized and aligned for objects of type T.
static void * AllocateAligned(size_t size, size_t alignment, size_t offset=0U)
Allocate memory with an alignment stricter than MIN_ALIGNMENT and an optional offset.
static void FreeAligned(void *ptr)
Free memory obtained with AllocateAligned().
Snapshot of the memory allocator's statistics.
Minimal move-only owning pointer for an object that lives in a memory pool.
uint8_t * m_bitmap
"allocated" bitmap (STK_MEMORY_BLOCKPOOL_BITMAP), otherwise unused
void DeleteT(T *ptr)
Destroy an object created with the NewT() family and return its block to the pool.
size_t GetUsedCount() const
Get the number of currently allocated (outstanding) blocks.
EWaitResult TimedAllocEx(void **block, Timeout timeout_ticks=WAIT_INFINITE)
Allocate one block, preserving the full wait outcome.
static const size_t ALIGN_DEFAULT
Default block alignment in bytes (see STK_MEMORY_BLOCKPOOL_ALIGN_DEFAULT).
static constexpr size_t BitmapBytes(size_t capacity)
Number of bytes of the "allocated" bitmap for capacity blocks.
static const uint8_t FILL_ALLOC
payload fill on allocation (STK_MEMORY_POOL_CHECKS)
size_t GetFreeCount() const
Get the number of free (available) blocks.
uint8_t * m_storage
raw storage as supplied or allocated (before alignment)
void * PopFreeList()
Pop the head block from the free-list, increment m_used_count, and return it.
size_t m_storage_size
size of the raw storage in bytes
T * TryNewT(TArgs &&...args)
Non-blocking TimedNewT(). ISR-safe if the constructor of T is.
static const size_t CAPACITY_MAX
Max capacity supported (number of blocks).
T * NewT(TArgs &&...args)
Allocate one block and construct a T in it, blocking indefinitely.
size_t m_capacity
total number of blocks (0 if invalid)
static bool ArgsValid(size_t capacity, size_t raw_block_size, size_t alignment, size_t block_size)
Check constructor arguments (block size overflow included).
size_t GetCapacity() const
Get the total block capacity of the pool.
STK_NONCOPYABLE_CLASS(BlockMemoryPool)
static __stk_forceinline void Fill(void *ptr, size_t size, uint8_t value)
Fill size bytes at ptr with value (used by diagnostics only).
T * TryAllocT()
Non-blocking typed allocation attempt.
size_t GetBlockAlignment() const
Get the alignment (bytes) of every block.
bool IsFull() const
Check whether all blocks are currently allocated (pool exhausted).
size_t GetAllocFailCount() const
Get the number of allocation requests that failed because the pool was exhausted (timeouts and NO_WAI...
size_t m_block_align
alignment of every block in bytes
bool IsStorageValid() const
Verify that the backing storage is valid and the pool is ready for use.
static const uint8_t FILL_FREE
payload fill on free (STK_MEMORY_POOL_CHECKS)
uint8_t * m_blocks
aligned start of block 0, nullptr if the pool is invalid
MemoryAllocator::Stats m_stats
live statistics in bytes (blocks * block size): usage, watermark, counters
MemoryAllocator::Stats GetStats() const
Get a consistent statistics snapshot in the same format as MemoryAllocator::GetStats().
bool Free(void *ptr)
Return a previously allocated block to the pool.
static bool IsValidAlignment(size_t alignment)
Check an alignment value: a power of two, large enough for the free-list link.
size_t GetPeakUsedCount() const
Get the high watermark: the maximum number of blocks that were allocated at the same time.
STK_VIRT_DTOR ~BlockMemoryPool()
Destructor.
void Setup(size_t raw_block_size, size_t alignment)
Align storage, trim the capacity to what fits and build the free-list.
void BuildFreeList()
Initialise the intrusive free-list across m_blocks.
void * TryAlloc()
Non-blocking allocation attempt.
MemoryBlock * m_free_list
head of the intrusive free-list (nullptr when pool is empty)
void * TimedAlloc(Timeout timeout_ticks=WAIT_INFINITE)
Allocate one block, blocking until one becomes available or the timeout expires.
sync::ConditionVariable m_cv
signalled by Free() to wake one task blocked in TimedAlloc()
BlockMemoryPool(size_t capacity, size_t raw_block_size, uint8_t *storage, size_t storage_size, const char *name=nullptr, size_t alignment=ALIGN_DEFAULT)
Construct a pool backed by caller-supplied (external) storage.
PoolPtr< T, BlockMemoryPool > MakeT(TArgs &&...args)
Blocking allocate-and-construct returning an owning PoolPtr.
size_t GetBlockSize() const
Get the aligned block size used internally by the allocator.
void * Alloc()
Allocate one block, blocking indefinitely until one is available.
PoolPtr< T, BlockMemoryPool > TryMakeT(TArgs &&...args)
Non-blocking allocate-and-construct returning an owning PoolPtr.
T * TimedAllocT(Timeout timeout_ticks=WAIT_INFINITE)
Allocate one typed block, blocking until one becomes available or the timeout expires.
bool IsEmpty() const
Check whether all blocks are free (no outstanding allocations).
static constexpr size_t RequiredStorageSize(size_t capacity, size_t raw_block_size, size_t alignment=ALIGN_DEFAULT)
Compute the size of the storage buffer required for an external-storage pool.
size_t m_used_count
number of blocks currently allocated (outstanding)
static constexpr size_t AlignBlockSize(size_t raw_size, size_t alignment=ALIGN_DEFAULT)
Round a raw block size up to the nearest multiple of alignment.
T * AllocT()
Allocate one typed block, blocking indefinitely until one is available.
size_t m_block_size
aligned block size in bytes (>= m_block_align)
bool m_storage_owned
true -> storage is heap-allocated; free in destructor
T * TimedNewT(Timeout timeout_ticks, TArgs &&...args)
Allocate one block and construct a T in it (placement new), waiting up to timeout_ticks.
Intrusive free-list node overlaid on the first word of every free block.
MemoryBlock * next
next free block in the list, or nullptr if this is the last one
Storage holder. Kept as a separate (first) base class so that the buffer exists before BlockMemoryPoo...
uint8_t m_buf[BlockMemoryPool::RequiredStorageSize(TCapacity, TBlockSize, TAlign)]
Fixed-size block pool that owns its storage: no heap, no separately declared (and possibly mis-sized ...
StaticBlockPool(const char *name=nullptr)
STK_STATIC_ASSERT_DESC((TCapacity > 0U) &&(TCapacity<=BlockMemoryPool::CAPACITY_MAX), "invalid capacity")
STK_STATIC_ASSERT_DESC(TBlockSize > 0U, "block size must be greater than zero")
STK_STATIC_ASSERT_DESC((TAlign >=sizeof(void *)) &&((TAlign &(TAlign - 1U))==0U), "alignment must be a power of two not less than sizeof(void *)")
RAII instance that enters the critical section on construction and exits it on destruction.
Definition stk_arch.h:495
Traceable object.
Definition stk_common.h:606
void SetTraceName(const char *name)
Set name.
Definition stk_common.h:617
RAII-style low-level synchronization primitive for atomic code execution. Used as building brick for ...
Definition stk_sync_cs.h:58
Condition Variable primitive for signaling between tasks based on specific predicates.
Definition stk_sync_cv.h:68