> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/holoscan/sdk-user-guide/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/holoscan/sdk-user-guide/_mcp/server.

# holoscan::FirstFitAllocatorBase

> Memory management helper class using first-fit allocation strategy.

Memory management helper class using first-fit allocation strategy.

This class keeps track of allocated and free regions within a large memory chunk and can efficiently find the first available block that fits a requested size. It works only with indices and relies on an external class to hold the actual memory.

Internally, it uses a binary segment tree to track the largest available block in any given area of memory. All operations have logarithmic time complexity.

```cpp showLineNumbers={false}
#include <holoscan/first_fit_allocator_base.hpp>
```

---

## Constructors

### FirstFitAllocatorBase \[#firstfitallocatorbase]

```cpp showLineNumbers={false}
holoscan::FirstFitAllocatorBase::FirstFitAllocatorBase()
```

Default constructor.

---

## Methods

### allocate \[#allocate]

```cpp showLineNumbers={false}
expected_t<void> holoscan::FirstFitAllocatorBase::allocate(
    int32_t size
)
```

Allocate internal data structures to handle memory requests for a given size.

Requires 32 \* 2^ceil(log2(size)) bytes of memory for internal bookkeeping.

**Returns:** Success or error status. Error::kInvalidSize if size is invalid.

**Parameters**

**`size`** `int32_t`

Maximum size of memory that can be managed.

---

### acquire \[#acquire]

```cpp showLineNumbers={false}
expected_t<int32_t> holoscan::FirstFitAllocatorBase::acquire(
    int32_t size
)
```

Acquire a contiguous block of memory of the specified size.

If such a contiguous block exists, returns the lowest index where the block starts. This block will be marked as allocated until a call to release() is made.

**Returns:** Index of the allocated block on success, Error::kOutOfMemory if no suitable block exists.

**Parameters**

**`size`** `int32_t`

Size of the memory block to acquire.

---

### release \[#release]

```cpp showLineNumbers={false}
expected_t<void> holoscan::FirstFitAllocatorBase::release(
    int32_t index
)
```

Release a previously acquired block of memory.

The block must have been previously acquired using acquire(). Once released, the memory becomes available for future allocations.

**Returns:** Success or error status. Error::kBlockNotAllocated if the block was not previously allocated.

**Parameters**

**`index`** `int32_t`

Starting index of the block to release.

---

### propagate\_to\_root \[#propagatetoroot]

```cpp showLineNumbers={false}
void holoscan::FirstFitAllocatorBase::propagate_to_root(
    int32_t idx
)
```

Update the tree path from a given node to the root.

**Parameters**

**`idx`** `int32_t`

Index of the node to start propagation from.

---

### update \[#update]

```cpp showLineNumbers={false}
void holoscan::FirstFitAllocatorBase::update(
    int32_t left,
    int32_t right,
    int32_t free
)
```

Update a segment of the tree and mark it as free or allocated.

**Parameters**

**`left`** `int32_t`

Left boundary of the segment (inclusive).

---

**`right`** `int32_t`

Right boundary of the segment (exclusive).

---

**`free`** `int32_t`

1 If marking as free, 0 if marking as allocated.

---

---

## Types

### Typedefs

| Name           | Definition             | Description                         |
| -------------- | ---------------------- | ----------------------------------- |
| `expected_t`   | `expected< T, Error >` | Expected type used by this class.   |
| `unexpected_t` | `unexpected< Error >`  | Unexpected type used by this class. |

### Error

Error codes used by the first-fit allocator classes.

| Name                 | Value | Description                                                                                  |
| -------------------- | ----- | -------------------------------------------------------------------------------------------- |
| `kAlreadyInUse`      |       | Returned when the suballocator is already in use and some memory has not been released yet.  |
| `kInvalidSize`       |       | Returned if the size is invalid (negative or too big).                                       |
| `kOutOfMemory`       |       | Returned if the class can't allocate enough memory.                                          |
| `kBlockNotAllocated` |       | Returned if we attempt to release a block of memory not allocated yet.                       |
| `kLogicError`        |       | This error happens when there is a logical issue during execution. This should never happen. |

---

## Member variables

| Name                      | Type                         | Description                                               |
| ------------------------- | ---------------------------- | --------------------------------------------------------- |
| `tree_`                   | `std::unique_ptr< Memory[]>` | Binary segment tree for memory management.                |
| `size_`                   | `int32_t`                    | Total size available at initialization.                   |
| `last_layer_first_index_` | `int32_t`                    | Helper index pointing to the first leaf node in the tree. |

---

## Inner classes

### Memory

```cpp showLineNumbers={false}
struct holoscan::FirstFitAllocatorBase::Memory
```

Helper data structure for efficient memory block searching.

Represents a node in a binary segment tree used to track free and allocated memory regions.

| Name    | Type      | Description                                                                                  |
| ------- | --------- | -------------------------------------------------------------------------------------------- |
| `left`  | `int32_t` | Size of available memory starting from the left side of the subtree.                         |
| `right` | `int32_t` | Size of available memory starting from the right side of the subtree.                        |
| `max`   | `int32_t` | Size of the largest available block in the subtree.                                          |
| `size`  | `int32_t` | Constant size of the subtree. When a block is acquired, contains the size that was acquired. |