AMA – Arena / Array Memory Allocation for PlayBASIC



This library implements a fully custom arena-style memory allocator written entirely in PlayBASIC.
Rather than relying on scattered arrays or implicit allocations, it provides a way to manage memory manually from a single contiguous pool, much like a real heap in a low-level engine.

The result is explicit control over allocation, deallocation, fragmentation, and compaction — concepts that are normally hidden from high-level languages.




Core Idea

At the heart of AMA is one large, linear memory buffer that acts as a simulated heap.
All memory requests are carved out of this buffer as banks — simple ranges defined by:

• A start address
• An end address
• A status flag (in use or free)

These banks are not arrays or objects themselves. They are just slices of a shared memory arena.
What the memory represents is entirely up to the caller.

This design mirrors how classic engines and operating systems managed memory on constrained hardware.




How Allocation Works (Conceptually)

When a new bank is requested, the allocator:

1. Scans the existing allocations in address order
2. Searches for a free gap large enough to satisfy the request
3. Prefers the *smallest usable gap* (best-fit strategy)
4. Automatically grows the arena if no gap is large enough
5. Inserts the new bank into a sorted allocation list

Because banks are stored in sorted address order, the allocator can reason about gaps, fragmentation, and layout very efficiently — without scanning the entire memory buffer.




Fragmentation Is a First-Class Concept

Deleting banks in arbitrary order will naturally create memory fragmentation.
AMA does not hide this — it tracks and exposes it.

The library measures:

• Total free memory
• Largest contiguous free gap
• A fragmentation percentage derived from these values

This makes it possible to see situations where memory exists, but not in a usable form — a classic real-world heap problem.




Manual Defragmentation

To address fragmentation, AMA includes a defragmentation pass that:

• Moves active banks downward in memory
• Removes gaps between allocations
• Preserves all data during relocation
• Updates internal address tracking

After defragmentation, all free memory becomes one large contiguous block at the end of the arena.

This is effectively a compacting memory manager, similar in spirit to early garbage-collected or frame-based systems — but fully under programmer control.




Debugging and Validation Tools

The allocator includes extensive validation support:

• Memory filling to detect corruption
• Verification passes to ensure banks don’t overlap
• Integrity checks after defragmentation
• Sorted-order diagnostics for allocation state

These tools turn the allocator into something you can inspect and trust, rather than a black box.




What the Demo Program Shows

The demo included with the library is not a gameplay example — it is a stress test and visualiser.

It demonstrates:

• Repeated allocation and deletion of banks
• Intentional fragmentation
• Manual defragmentation triggers
• Real-time memory statistics (used, free, total)
• Bank counts and allocation order

Most importantly, it renders a **graphical memory map** where each allocation appears as a coloured region.
Larger banks appear brighter, making fragmentation patterns instantly visible.

This turns abstract memory behaviour into something you can actually *see*.




Why This Exists

This library recreates the style of memory management used in:

• Classic game engines
• Console and embedded development
• Performance-critical tools
• Retro systems with strict memory limits

All within PlayBASIC — without native pointers or explicit heap access.

It provides a practical, hands-on way to understand:

• How heaps fragment
• Why best-fit allocation matters
• When defragmentation becomes necessary
• What “contiguous memory” really means




Big Picture

In simple terms:

AMA builds a miniature memory manager inside PlayBASIC, complete with allocation strategies, fragmentation metrics, defragmentation, and debugging support — then proves it works through visualisation and stress testing.

It’s not just a utility library.
It’s an educational and experimental framework for exploring how real memory managers behave — from within a high-level language.