Hardened containers and views
reloco provides small C++17-compatible containers and views for code that
cannot rely on exceptions, allocation, or build-mode-dependent safety. The
core types include:
| Type | Purpose |
|---|---|
reloco::array<T, N> |
Fixed-size owning array with hardened element access |
reloco::string_view |
Non-owning character view with checked and non-trapping access |
reloco::span<T> |
Non-owning contiguous range over contiguous storage |
reloco::string |
Allocator-backed, growable character buffer with fallible construction |
reloco::vector<T> |
Allocator-backed, growable dynamic array with fallible construction |
reloco::inline_vector<T, Capacity> |
Fixed-capacity, allocation-free growable array with fallible mutation |
reloco::flat_set<T, Compare> |
Sorted, unique-element set backed by vector<T>, with fallible insertion |
reloco::basic_inline_string<Capacity, CharT, TraitsT> |
Fixed-capacity, allocation-free character buffer with fallible mutation |
reloco::optional<T> |
Zero-allocation, conditionally-present value wrapper with hardened access |
reloco::unique_ptr<T> |
Move-only, allocator-backed smart pointer with fallible construction |
reloco::shared_ptr<T> / reloco::weak_ptr<T> |
Reference-counted, allocator-backed smart pointer with fallible construction |
reloco::expected<T, E> |
Allocation-free value-or-error result |
These types provide familiar standard-library-style APIs while keeping the reloco surface available in C++17. The non-owning view types interoperate with their standard-library equivalents when the toolchain provides them.
Prefer hardened types in low-level code
Use the hardened reloco type by default when writing firmware, kernel-mode components, interrupt handlers, crash diagnostics, protocol parsers, and other code where an unchecked access or dangling borrow is a security issue.
| Instead of | Prefer | When |
|---|---|---|
std::array<T, N> |
reloco::array<T, N> |
Fixed-size owned storage |
std::span<T> |
reloco::span<T> |
Borrowed contiguous storage |
std::string_view |
reloco::string_view |
Borrowed character data |
std::string |
reloco::string |
Allocator-backed, growable, fallible character storage |
std::vector<T> |
reloco::vector<T> |
Allocator-backed, growable, fallible dynamic array |
| n/a | reloco::inline_vector<T, Capacity> |
Fixed-capacity, allocation-free, fallible growable array |
std::set<T> |
reloco::flat_set<T> |
Sorted, unique-element set with fallible, contiguous storage |
std::optional<T> |
reloco::optional<T> |
Conditionally-present value with hardened, trapping-by-default access |
std::unique_ptr<T> |
reloco::unique_ptr<T> |
Allocator-backed, fallible single-object ownership |
std::shared_ptr<T> / std::weak_ptr<T> |
reloco::shared_ptr<T> / reloco::weak_ptr<T> |
Allocator-backed, fallible shared object ownership |
std::expected<T, E> |
reloco::expected<T, E> |
Allocation-free fallible results |
This is a project default, not a ban on the standard library. Keep standard types when required by a platform API, third-party library, ABI, or generic ecosystem interface. Convert to a hardened view at the boundary and keep the security-sensitive implementation on reloco types.
reloco::string, reloco::vector<T>, and reloco::flat_set<T> are the
dynamic owning containers reloco provides: an allocator-backed, growable
character buffer, dynamic array, and sorted unique-element set,
respectively, whose construction and every mutation that can fail
(try_reserve, try_append/try_push_back, try_insert/try_insert_at,
…) returns reloco::result<T> instead of throwing. All three compose
with the fallible-construction protocol (see docs/fallible-construction.md),
so reloco::unique_ptr<reloco::string>::try_create(...),
reloco::unique_ptr<reloco::vector<T>>::try_create(...), and similar work
out of the box. std::map and other node-based associative containers
still have no direct reloco replacement (see reloco::mutable_container_ref/
container_ref_std.hpp for opt-in, type-erased mutation of std::map
itself); use them only where allocation, failure behavior, and execution
context are explicitly acceptable, and prefer caller-owned fixed storage
plus reloco::span in bounded or kernel-mode paths.
void parse_packet(std::span<const std::byte> platform_input) {
reloco::span<const std::byte> input = platform_input;
// Keep checked parsing on the hardened view from this point onward.
}
Security is enabled by default
Unlike conventional standard-library containers, where unchecked element
access is commonly the default, reloco makes checked behavior the default
and requires an explicit opt-out. Checked reloco operations use
RELOCO_ASSERT. These checks remain active in release builds and are not
removed merely because NDEBUG is defined. Invalid checked access calls the
configured assertion handler and then traps.
This makes hardening opt-out rather than opt-in: applications get checked
behavior by default and must explicitly define RELOCO_DISABLE_ASSERT to
remove it. Do this only after proving that every checked precondition is
satisfied. With assertions disabled, violating a precondition is undefined
behavior; the macro is a performance and code-size tradeoff, not an error
recovery mode.
target_compile_definitions(firmware PRIVATE RELOCO_DISABLE_ASSERT=1)
The opt-out applies globally to checked reloco operations in that target.
Prefer selecting an unsafe_* operation at a measured hot call site instead
of disabling hardening for the entire program.
Choose an access tier
reloco::string_view exposes three access styles:
| Tier | Examples | Behavior on invalid input |
|---|---|---|
| Checked | operator[], front(), back(), substr() |
Assertion handler, then trap |
| Non-trapping | try_at(), try_front(), try_back(), try_substr() |
Returns reloco::result (reloco::expected<T, reloco::error>) |
| Explicitly unsafe | unsafe_front(), unsafe_back(), unsafe_substr() |
Debug assertion only; caller owns the precondition |
Use checked operations when invalid input indicates a programming defect. Use
try_* operations for data-dependent bounds or empty-input cases that the
application expects to handle.
reloco::string_view input = receive_field();
if (auto first = input.try_front()) {
consume(first.value().get());
} else {
report_empty_field();
}
if (auto payload = input.try_substr(header_size)) {
decode(payload.value());
} else {
report_truncated_field();
}
reloco::expected<T, E>::value() and error() are also checked. Test the
result with has_value() or its boolean conversion before accessing the
active alternative.
reloco::span<T> follows the same model:
| Tier | Examples |
|---|---|
| Checked | operator[], front(), back(), subspan(), first(), last() |
| Non-trapping | try_at(), try_front(), try_back(), try_subspan(), try_first(), try_last() |
| Explicitly unsafe | unsafe_at(), unsafe_front(), unsafe_back(), unsafe_subspan(), unsafe_first(), unsafe_last() |
| Unchecked (hot loops) | unchecked_at() |
unsafe_at() asserts in debug builds and, in release builds, lets the optimizer assume the index is in range.
unchecked_at() (on span and array) never checks or assumes anything in any build mode: it is a plain
element access for loops whose index range was proven once, outside the loop (for example the indexes of the
kernel framework, docs/kernel/README.md). An out-of-range index is undefined behavior, so reach for it only when
a proof exists; otherwise use operator[]. span::unchecked_subspan(offset, count) is the same idea for
sub-ranges.
Fallible span operations return reloco::result (reloco::expected<T, reloco::error>).
as_bytes() creates a read-only byte view without copying the represented
storage.
reloco::array<T, N> provides checked operator[], fallible try_at(),
explicit unsafe_at(), hardened iterators and data access, as_span(),
compile-time static_subspan<Offset, Count>(), fill(), swap(), and
allocation-free map(). It supports aggregate initialization, structured
bindings, and zero-length arrays. Borrowing accessors, including get<I>(),
are rejected on temporary arrays. Tuple traits are provided for structured
bindings; use ADL get rather than expecting std::get or std::apply
interoperability.
Debug checks and unsafe operations
RELOCO_DEBUG_ASSERT protects lower-level operations whose contracts are
intended to be established by nearby code. It is active in debug builds and
when RELOCO_DEBUG is defined, but it is disabled by NDEBUG otherwise.
Only operations explicitly named unsafe_* use this debug-check tier.
Checked reloco::span<T> indexing and subviews remain hardened in release
builds. Both reloco::span<T> and reloco::string_view name their fast
paths with an unsafe_* prefix so security-sensitive call sites remain
visible in review.
Every unsafe_* method across the library (array, span, string_view,
string, vector, inline_vector, flat_set, basic_inline_string,
optional, value_ptr, shared_ptr/unique_ptr, and checked_value) is
additionally marked RELOCO_UNSAFE_BUFFER_USAGE (see reloco/lifetime.hpp).
Under Clang’s -Wunsafe-buffer-usage, any unwrapped call site is a compiler
diagnostic — callers must wrap the call in
RELOCO_BEGIN_UNSAFE_BUFFER_USAGE/RELOCO_END_UNSAFE_BUFFER_USAGE to
make the opt-out explicit and greppable, not just documented in a comment:
if (!field.empty()) {
RELOCO_BEGIN_UNSAFE_BUFFER_USAGE
const char first = field.unsafe_front();
RELOCO_END_UNSAFE_BUFFER_USAGE
consume(first);
}
Do not use an unsafe operation solely to avoid handling invalid input. Keep
the precondition adjacent to the call and prefer a checked or try_* API at
trust boundaries.
Dangling-reference prevention
reloco::expected deletes dereference and pointer-style accessors on
temporary result objects where the returned value could dangle after the full
expression. reloco::span<T> similarly rejects indexing, pointer access,
and iterator access on temporary span objects. reloco::string_view also
rejects construction from a temporary owning string.
std::string storage = load_name();
reloco::string_view safe = storage;
// Rejected: the owning string would be destroyed immediately.
// reloco::string_view dangling = load_name();
The owner must still outlive every non-owning reloco::string_view or
reloco::span<T>. Hardening detects API contract violations; it cannot
extend the lifetime of referenced storage.
For non-owning references to individual objects, and for guidance on compiler
annotations, see Lifetime safety and value_ref. See
Container contract for the copy-paste template
implementing these tiers, lifetime annotations, and rvalue protection
together when adding a new container.
optional<T> move semantics: Rust Option, not std::optional
reloco::optional<T>’s move constructor and move-assignment operator
always leave the moved-from source empty (has_value() == false),
exactly like a plain Rust move (checked at compile time) or
Option::take() (checked at run time) – never std::optional<T>’s
behavior of leaving the source “engaged,” still holding a moved-from T.
reloco::optional<int> a(42);
reloco::optional<int> b(std::move(a));
// b.has_value() == true, *b == 42
// a.has_value() == false -- NOT "true, holding a moved-from int"
This is a deliberate safety choice, not an oversight relative to
std::optional. std::optional<T>::has_value() is unchanged by being
moved from, so a moved-from std::optional<void *> or
std::optional<int> still reads as “present,” silently holding
whatever unspecified moved-from value T’s own move left behind –
easy to mistake for “moving an optional doesn’t touch the source” and a
recurring source of use-after-move bugs, especially for scalar/pointer
T where there is no obviously-moved-from sentinel the way there is for
e.g. a moved-from std::string/std::vector. reloco::optional<T>
closes that gap: after a move, the source is unconditionally empty, so
any later use (*a, a.value(), …) traps via RELOCO_ASSERT instead
of silently reading stale data.
reloco::optional<T>::swap() already followed this “always leave a
clean, well-defined state behind” discipline; the move constructor and
move-assignment operator now match it.
Configure assertion reporting
The default assertion handler writes the failed expression, source location, and message to standard error before trapping. Replace it when diagnostics must go to a device log, crash record, or platform-specific transport:
void assertion_log(const char *expression, const char *file, int line,
const char *message) {
write_crash_record(expression, file, line, message);
}
reloco::set_assert_handler(assertion_log);
Define RELOCO_DISABLE_ASSERT_STDIO to suppress the default standard-error
dependency while preserving checks and traps:
target_compile_definitions(firmware PRIVATE RELOCO_DISABLE_ASSERT_STDIO=1)
Install a custom handler before a failure can occur if the default handler is disabled and the platform requires a persistent diagnostic record.