---

description: Understand the two memory-management mechanisms used in SAMSON: custom heap allocation and reference-based garbage collection.

Memory management

SAMSON exposes two distinct memory-management mechanisms:

• custom heap management for performance-sensitive allocation patterns
• reference-based garbage collection through the SAMSON referencing system

Most extension developers need to understand the second one first. The custom heap mechanism is useful, but only for specific performance hotspots.

Custom heap management

Use custom heap management when your code allocates and destroys very large numbers of small objects and normal heap traffic becomes a measurable bottleneck.

To opt in, add SB_HEAP in the class declaration:

#include "SBCHeap.hpp"

class MyClass {

    SB_HEAP;

public:

    MyClass();
    virtual ~MyClass();

};

The class definition must then be accompanied by a custom heap implementation, thanks to the macro SB_HEAP_IMPLEMENTATION:

#include "MyClass.hpp"

SB_HEAP_IMPLEMENTATION(MyClass, 4096);

The integer argument is the initial number of pre-allocated objects. SAMSON can adapt if more are needed at the same time.

SB_HEAP redefines new and delete for that class so the rest of the code can stay unchanged.

In practice, only use this after you have evidence that allocation churn matters. It is a performance tool, not the default memory model for everyday extension code.

Garbage collection

SAMSON uses a custom referencing mechanism to track references between objects. This mechanism supports features such as signals and slots, but it also gives SAMSON a basic form of garbage collection.

The rule is simple:

• if an object is a reference target
• and no reference owner references it anymore
• SAMSON deletes it

This is why raw delete is usually the wrong tool for SAMSON objects such as data graph nodes. Lifetime is controlled by the referencing system, not by ad hoc ownership guesses.

Practical guidance

• Learn Referencing before writing long-lived extension code that stores SAMSON objects.
• Reach for SB_HEAP only when profiling shows a real allocation bottleneck.
• Assume that many important SAMSON objects participate in reference-managed lifetime.

For more detail, see Referencing.