Módulo de Memória
Três allocators personalizados — linear, pool e stack — que
partilham a interface IAllocator para memória temporária por frame,
objetos de tamanho fixo e escopos aninhados.
Visão Geral#
O módulo Memory fornece allocators personalizados para gestão de memória sem
dependências externas. Todos os allocators implementam a interface IAllocator.
Localização: src/caffeine/memory
Namespace: Caffeine (não Caffeine::Memory — os allocators vivem
diretamente no namespace raiz).
Ficheiros#
| Ficheiro | Descrição | Estado |
|---|---|---|
Allocator.hpp |
Interface IAllocator |
✅ Completo |
LinearAllocator.hpp |
Alocação O(1), reset() limpa tudo |
✅ Completo |
PoolAllocator.hpp |
Slots de tamanho fixo, alloc/free O(1) | ✅ Completo |
StackAllocator.hpp |
Markers, freeToMarker() |
✅ Completo |
Arquitetura#
Interface IAllocator#
cpp
class IAllocator {
public:
virtual ~IAllocator() = default;
virtual void* alloc(usize size, usize alignment = 8) = 0;
virtual void free(void* ptr) = 0;
virtual void reset() = 0;
virtual usize usedMemory() const = 0;
virtual usize totalSize() const = 0;
virtual usize peakMemory() const = 0;
virtual usize allocationCount() const = 0;
virtual const char* name() const = 0;
};
// Helpers livres (Allocator.hpp)
inline usize calculatePadding(void* ptr, usize alignment);
inline usize calculateAlignedSize(usize size, usize alignment);
Comparação dos Allocators#
| Allocator | Alocação | Libertação | Caso de uso |
|---|---|---|---|
| Linear | O(1) | Apenas reset() (free() é no-op) |
Memória temporária por frame |
| Pool | O(1) | O(1); free(nullptr) é seguro; sem deteção de double-free |
Objetos de tamanho fixo (partículas) |
| Stack | O(1) | freeToMarker() (free() é no-op) |
Alocações com escopo |
Semântica confirmada no código#
- Construtores: cada allocator pode ser dono do seu buffer
(
explicit X(usize size), alocado comnew u8[]) ou envolver um buffer externo (X(void* buffer, usize size), sem transferência de ownership). - Out of memory:
alloc()retornanullptr— verifique sempre o resultado. - Especificidades do Pool: o construtor exige
alignment >= 8e potência de dois;alloc()ignora os parâmetrossize/alignment(devolve sempre um slot fixo e verificasize <= slotSizeem debug); os slots têm de comportar um ponteiro (mínimo 8 bytes — a free list é intrusiva);reset()reconstrói a free list. Introspeção:freeSlots(),slotSize(),maxSlots(). - Especificidades do Stack:
Markeré um offsetusizea partir do início do buffer (setMarker());freeToMarker()ignora markers além do cursor e repõe a contagem de alocações;free(ptr)não faz nada. - Estatísticas:
usedMemory()/totalSize()/peakMemory()/allocationCount()são atualizados em tempo real;reset()zera a contagem de alocações (Linear/Stack) ou a contagem de slots usados (Pool).
Exemplos de Uso#
LinearAllocator#
cpp
// Cria um allocator linear de 64KB
Caffeine::LinearAllocator alloc(64 * 1024);
// Aloca (O(1))
void* ptr = alloc.alloc(1024, 8);
// Liberta tudo de uma vez
alloc.reset();
PoolAllocator#
cpp
// Cria um pool para 100 partículas de 64 bytes cada
Caffeine::PoolAllocator pool(64 * 100, 64);
// Aloca (O(1))
void* p1 = pool.alloc(64);
void* p2 = pool.alloc(64);
// free devolve o slot ao pool
pool.free(p1);
StackAllocator#
cpp
Caffeine::StackAllocator stack(1024 * 1024); // 1MB
// Guarda um marker
auto marker = stack.setMarker();
// Aloca
void* ptr = stack.alloc(512);
// Liberta até ao marker (tudo o que está depois dele)
stack.freeToMarker(marker);
DOD (Data-Oriented Design)#
- Todos os allocators usam blocos contíguos de memória
- Sem memória dinâmica depois da alocação inicial
- Não são thread-safe para instâncias partilhadas; use allocators por thread ou sincronização externa
- Zero alocações no heap durante a operação normal
Referência Rápida#
| Classe | Complexidade | Método principal |
|---|---|---|
LinearAllocator |
O(1) alloc, O(1) reset | reset() limpa tudo |
PoolAllocator |
O(1) | free() devolve o slot |
StackAllocator |
O(1) alloc | freeToMarker() |
Ver Também#
Documentação Relacionada#
- memory/memory-model.md - Especificação detalhada dos allocators
- HISTORY.md - Requisitos e regras de desenvolvimento da Fase 1
- architecture_specs.md - Especificações técnicas
- API Reference - Documentação completa da API
- Test Documentation - Testes dos allocators
Módulos Relacionados#
- Core Module - Tipos fundamentais (usados pela Memory)
- Containers Module -
Vectorusa allocators - Math Module - Tipos matemáticos