Skip to content

vision.md

Latest commit

 

History

History
286 lines (204 loc) · 8.83 KB

vision.md

File metadata and controls

286 lines (204 loc) · 8.83 KB
Raw

UMR Vision

Universal Memory Runtime
Next-generation memory management infrastructure for C

Field Value
Version 1.0
Status Implementation Hardening (v0.1)
Target Open Source Systems Infrastructure
Language C23 Core Runtime
License MIT

1. Vision Statement

UMR (Universal Memory Runtime) redesigns memory management in C by creating a modular, observable, high-performance memory runtime that goes beyond traditional malloc / free.

Traditional C memory management exposes a minimal interface:

void* malloc(size_t size);
void* calloc(size_t nmemb, size_t size);
void* realloc(void* ptr, size_t size);
void  free(void* ptr);

That interface is sufficient for correctness, but it leaves critical gaps:

Gap Impact
No memory visibility Developers cannot see what the heap looks like at runtime
No fine-grained control One global strategy for every allocation pattern
Weak fragmentation management Long-running processes degrade over time
No allocation intelligence The allocator cannot adapt to workload
Limited debugging Leaks, double-frees, and corruption are hard to diagnose
No runtime optimization hooks Applications cannot tune behavior without replacing the allocator

UMR introduces a complete memory infrastructure layer between the application and the operating system:

Application
     |
     v
UMR Runtime API
     |
     v
Memory Management Engine
  (allocators, metadata, policies, debug, profiler)
     |
     v
Physical / Virtual Memory
  (mmap, VirtualAlloc, brk, …)

UMR is intended to become foundational infrastructure for:

  • Game engines
  • Databases
  • Operating systems and kernels (userspace first)
  • Embedded systems
  • AI / ML infrastructure and inference runtimes
  • High-performance networking and storage applications

2. Mission

Build an open-source universal memory runtime that provides:

  1. Faster allocation than stock platform malloc for common workloads
  2. Better memory utilization through specialized allocators and fragment management
  3. Complete memory observability — every block can be inspected and explained
  4. Advanced debugging — leaks, corruption, invalid frees, overflow detection
  5. Custom allocation strategies — arenas, pools, slabs, buddy, fragment, large-object
  6. A path to relocatable memory — handles, compaction, and defragmentation in future phases

The mission is not to invent another opaque drop-in allocator. It is to make memory management a first-class, inspectable subsystem of the application.

3. Core Philosophy

Memory should not be a black box.

Today

Application
    |
    v
 malloc() / free()
    |
    v
   ???
    |
    v
 OS Memory

The application asks for bytes and gets a pointer. Everything else is invisible: ownership, lifetime intent, fragmentation, thread locality, and failure modes.

With UMR

Application
    |
    v
   UMR
    ├── Allocation Tracking
    ├── Memory Policies
    ├── Fragment Manager
    ├── Heap Visualization
    ├── Debug Layer
    └── Performance Engine
    |
    v
 OS Memory

UMR treats the heap as a managed runtime with explicit policies, metadata, and tooling — analogous to how a language runtime manages objects, but implemented in portable C23 for systems that cannot afford a GC or a managed language.

Design principles

Principle Meaning
Observability first Every allocation can carry identity, origin, and status
Modularity Allocators are pluggable engines, not a monolith
Performance by default Debug and profiling are opt-in or layered, not always-on tax
Compatibility A familiar malloc-shaped API lowers adoption friction
Honesty about limits No pretend GC; no silent pointer rewriting in v1
Portability Linux, Windows, and macOS via a thin platform layer

4. Goals

Primary goals

G1 — Replace malloc (compatible API)

Provide a drop-in compatible surface:

void* umr_malloc(size_t size);
void  umr_free(void* ptr);
void* umr_realloc(void* ptr, size_t size);
void* umr_calloc(size_t count, size_t size);

Success criterion: a developer can replace #include <stdlib.h> allocation calls with #include <umr.h> and gain profiling, debugging, and statistics without rewriting allocation strategy code.

G2 — Modular allocator system

Support multiple allocation strategies behind one runtime:

  • Arena allocator
  • Pool allocator
  • Slab allocator
  • Buddy allocator
  • Fragment allocator
  • Large object allocator

The Allocation Manager routes requests to the appropriate engine based on size class, policy, or explicit API.

G3 — Memory intelligence

The runtime should understand:

  • Where memory is allocated
  • How much is used vs free
  • Where fragmentation occurs
  • Which strategy performs best for a given workload

This intelligence feeds the profiler, policies, and (later) automatic strategy selection.

G4 — Developer tooling

Ship first-class tools:

  • Heap profiler (umr stats)
  • Memory debugger / sanitizer hooks
  • Leak detector
  • Visualization (umr visualize)
  • Snapshots for offline analysis

5. Non-Goals (Initial Version)

UMR will not initially:

Non-goal Rationale
Replace OS virtual memory management UMR sits on top of mmap / VirtualAlloc / etc.
Provide garbage collection C ownership remains explicit; no GC pause model
Automatically move raw C pointers Relocatable handles are a future feature
Modify compiler behavior No custom compiler plugins required for core use
Be a kernel-mode allocator in v1 Userspace runtime first; kernel ports are out of scope for early phases

These boundaries keep the first releases shippable and honest about what C pointers allow.

6. Who UMR Is For

Audience Why UMR matters
Game developers Frame arenas, object pools, deterministic reset
Systems programmers Controllable heaps, observability, custom policies
Embedded developers Predictable pools/slabs, low-fragmentation modes
Database engineers Region allocators, large-object paths, leak hunting
HPC / AI infra Thread-local caches, fast temporary arenas

7. Success Metrics

UMR succeeds when:

Performance

  • Throughput within 90–120% of mimalloc on representative microbenchmarks and a small suite of application-like workloads
  • Competitive with glibc malloc, jemalloc, tcmalloc on common size-class patterns

Memory efficiency

  • Lower fragmentation than glibc malloc under mixed allocate/free workloads
  • Measurable improvement under long-running churn (fragment engine + specialized allocators)

Developer experience

A developer can:

#include <umr.h>

and immediately gain:

  • Profiling and statistics
  • Debugging aids (leaks, double-free, invalid pointer)
  • Optional visualization and snapshots

without becoming a memory-allocator expert.

Adoption signals (open source)

  • Clear docs and examples that run on Linux, Windows, and macOS
  • Public benchmarks against known allocators
  • Stable C API with semantic versioning

8. Open Source Strategy

Topic Direction
License MIT (repository already licensed)
Alternative considered Apache 2.0 if patent grant becomes a community requirement
Community focus Game, systems, embedded, and database engineers
Distribution Source-first; CMake + Ninja; GitHub Actions CI
Documentation MkDocs + Doxygen for API reference

UMR should feel like infrastructure other projects can vendor or link against with confidence: small public API surface, predictable ABI policy, and transparent behavior under debug builds.

9. Long-Term North Star

Beyond v1, UMR aims to evolve from a sophisticated allocator into a memory runtime:

  1. Relocatable handles (UMR_Handle) enabling compaction without invalidating ownership semantics
  2. Automatic fragmentation optimization — observe, adapt strategy, reclaim
  3. Cold memory compression for large heaps with sparse hot sets
  4. Persistent / restart-surviving regions for specialized workloads
  5. Remote heap debugger — inspect another process or machine’s UMR heap

The north star remains the same: memory that can be explained, controlled, and improved — not guessed at.

10. Summary

UMR is an open-source C23 memory runtime that replaces the black-box nature of malloc with a modular, observable, high-performance engine. It starts as a compatible allocation API with specialized allocators and developer tooling, and grows toward intelligent, relocatable memory infrastructure for systems that need both speed and insight.