Space Allocator

Introduction

The Space Allocator is a shared infrastructure module that provides disk space management for components that store persistent data — primarily service images and Deployment Bundle blobs. It ensures that storage consumption stays within configured limits and automatically frees space by evicting outdated items when new allocations would exceed capacity.

The module is partition-aware: multiple allocators targeting paths on the same filesystem partition share a single view of available space, preventing over-allocation even when different components manage separate directories on the same disk. This design is critical for embedded systems where storage is constrained and multiple components compete for the same physical media.

Architecture

The Space Allocator follows AosCore's two-layer design pattern:

• Interface (aos_core_lib_cpp/src/core/common/spaceallocator/itf/spaceallocator.hpp) — defines the SpaceAllocatorItf, SpaceItf, and ItemRemoverItf abstract interfaces
• Implementation (aos_core_lib_cpp/src/core/common/spaceallocator/spaceallocator.hpp) — provides the concrete SpaceAllocator template class and Partition management

Unlike most AosCore modules where the implementation lives in aos_core_cpp/src/common/, the Space Allocator implementation is entirely within the library layer (aos_core_lib_cpp). This is because it uses only platform-abstracted filesystem interfaces and has no application-level dependencies.

Key Abstractions

Abstraction	Role
SpaceAllocatorItf	Main interface — allocate space, free space, manage outdated items
SpaceItf	Represents an active allocation — can be accepted, released, or resized
ItemRemoverItf	Callback interface for removing outdated items to free space
Partition	Internal — tracks available space and outdated items for a filesystem mount point
SpaceAllocatorStorage	Internal — global static storage for partition state shared across all allocator instances

Interface Contract

The Space Allocator interface exposes the following operations:

Method	Parameters	Description
AllocateSpace	size	Reserves the specified number of bytes, returning a SpaceItf handle
FreeSpace	size	Releases previously allocated bytes back to the pool
AllocateDone	—	Signals that an allocation transaction is complete
AddOutdatedItem	id, version, timestamp	Registers an item as eligible for eviction when space is needed
RestoreOutdatedItem	id, version	Removes an item from the eviction-eligible list (e.g., when it becomes active again)

Space Handle Lifecycle

When AllocateSpace succeeds, it returns a SpaceItf handle that the caller uses to manage the allocation:

Method	Effect
Accept	Commits the allocation — the space is permanently consumed until explicitly freed
Release	Abandons the allocation — the reserved space is returned to the available pool
Resize	Changes the allocation size — frees the old reservation and allocates the new size
Size	Returns the current allocation size in bytes

After calling Accept or Release, the allocation transaction is finalized. Calling either method again returns an eNotFound error.

Partition-Aware Allocation

The Space Allocator's most important design property is partition awareness. Multiple allocator instances that target paths on the same filesystem mount point share a single Partition object that tracks the true available space.

How Partition Sharing Works

1. During Init, the allocator resolves the mount point for its configured path using the platform filesystem interface
2. If a Partition object already exists for that mount point (created by a previously initialized allocator), the new allocator joins it
3. All allocators on the same partition share:
   • The available space counter
   • The outdated items list (eviction candidates from any allocator on the partition)
   • The partition-level percentage limit accumulator

This prevents a scenario where two allocators on the same disk each believe they have the full disk available, leading to over-allocation and disk-full errors.

Partition State

Each partition tracks:

Field	Description
Mount point	Filesystem path identifying the partition
Total size	Total capacity of the partition (queried once at initialization)
Limit	Accumulated percentage limit from all allocators on this partition (max 100%)
Available size	Current available bytes (refreshed at the start of each allocation transaction)
Outdated items	List of items eligible for eviction, sorted by timestamp when eviction is needed
Allocator count	Number of active allocators sharing this partition

Configuration Limits

Parameter	Default	Description
Maximum partitions	4	Maximum number of distinct filesystem partitions tracked simultaneously
Maximum outdated items	64	Maximum number of items in the eviction queue per partition

Percentage-Based Limits

Each allocator instance can be initialized with a percentage limit that caps how much of the partition's total capacity it may consume:

sizeLimit = partitionTotalSize × (accumulatedLimit / 100)

• When limit is 0 (the default), the allocator has no per-allocator cap — it is constrained only by the partition's physical available space
• When limit is non-zero, the allocator tracks its own allocated size and refuses allocations that would exceed its calculated limit
• Multiple allocators on the same partition accumulate their limits — the total cannot exceed 100%

Two-Level Allocation Check

Every AllocateSpace call passes through two checks:

1. Allocator-level check — if a percentage limit is configured, verifies that currentAllocatedSize + requestedSize ≤ sizeLimit
2. Partition-level check — verifies that the partition has enough physical free space for the allocation

Both checks must pass for the allocation to succeed. If either check fails and outdated items are available, the allocator attempts automatic eviction before returning an error.

Automatic Eviction

When an allocation cannot be satisfied due to insufficient space, the Space Allocator automatically evicts outdated items to free capacity. This is the primary mechanism for managing storage on space-constrained embedded devices.

Eviction Process

1. The outdated items list is sorted by timestamp (oldest first)
2. Items are removed one by one, starting with the oldest, until enough space is freed
3. For each item, the ItemRemoverItf::RemoveItem callback is invoked, which:
   • Physically deletes the item's data from disk
   • Returns the actual size freed
4. The freed space is added back to both the allocator's tracked size and the partition's available space
5. If sufficient space is freed, the original allocation proceeds

Eviction at Allocator Level vs Partition Level

Eviction can be triggered at two levels:

• Allocator level — when the allocator's percentage limit is exceeded, only items belonging to this allocator are evicted
• Partition level — when the partition's physical space is exhausted, items from any allocator on the partition may be evicted (oldest-first across all allocators)

This distinction ensures that one allocator's eviction policy doesn't unnecessarily remove items managed by another allocator, while still allowing the system to recover from true disk-full conditions.

Outdated Item Registration

Components register items as eviction candidates using AddOutdatedItem:

• Items are identified by an ID and version string
• Each item carries a timestamp used for oldest-first eviction ordering
• If the outdated items list is full (64 items by default), the oldest item is immediately evicted to make room for the new registration
• Items can be restored (removed from the eviction list) using RestoreOutdatedItem — for example, when a previously outdated service image becomes active again due to a rollback

Concurrent Allocation

The Space Allocator is designed for multi-threaded use:

• Each allocator instance has its own mutex protecting per-allocator state (allocated size, allocation count)
• The shared Partition object has its own mutex protecting partition-wide state (available size, outdated items)
• The global partition map has a separate mutex protecting allocator initialization and shutdown

Allocation Counting

The allocator uses an allocation count to track active transactions:

• AllocateSpace increments the count
• Accept or Release (via AllocateDone) decrements the count
• The available space is refreshed from the filesystem only when the count transitions from 0 to 1 (start of a new transaction batch)
• This avoids expensive filesystem queries on every allocation within a batch of related operations

Initialization

An allocator is initialized with:

Parameter	Required	Description
path	Yes	Directory path where this allocator manages storage
platformFS	Yes	Platform filesystem interface for mount point detection and size queries
limit	No	Percentage of partition capacity this allocator may use (0 = unlimited)
remover	No	Item remover callback for automatic eviction (required if eviction is needed)

During initialization:

1. The target directory is created if it does not exist
2. The mount point is resolved for the given path
3. If no partition exists for this mount point, a new one is created with the partition's total size
4. The allocator registers itself with the partition and applies its percentage limit

Integration Points

Service Manager

SM uses a single Space Allocator instance (mImagesSpaceAllocator) to manage storage for service images. SM's Image Manager implements ItemRemoverItf to handle eviction — when the allocator needs space, it removes the oldest unused service image layers.

Communication Manager

CM uses two separate Space Allocator instances:

Allocator	Purpose
mDownloadSpaceAllocator	Manages temporary space for in-progress downloads
mInstallSpaceAllocator	Manages permanent space for installed Deployment Bundle images

Both allocators target the same install path, meaning they share a partition and coordinate their space usage. CM's Image Manager implements ItemRemoverItf for both, enabling eviction of outdated download artifacts and installed images independently.

Image Manager Integration

Both SM and CM Image Managers implement the ItemRemoverItf interface, making them responsible for:

1. Registering outdated items when images are superseded by newer versions
2. Physically removing image data when the allocator triggers eviction
3. Restoring items from the outdated list when they become active again (e.g., during rollback)

Related Pages

• Common Infrastructure — overview of all shared modules
• Downloader — file retrieval subsystem that works alongside the Space Allocator
• OCI Image Format — image structure stored in allocator-managed directories
• SM Image Manager — primary consumer for service image storage
• CM Update Manager — coordinates downloads that consume allocated space
• Storage and Quotas — configuration reference for storage limits