Ch26.15: Freestanding API
1. The Header Boundary
Freestanding is a property of the headers you include, not a runtime switch inside a hosted binary. The three umbrella headers mark the boundary:
| Header | Contains | Use |
|---|---|---|
<fast_io_core.h> |
Core vocabulary, formatting, scanning, buffers, serialization, allocators. | The smallest freestanding surface. |
<fast_io_freestanding.h> |
Core plus freestanding containers, algorithms and buffer devices. | Normal freestanding target. |
<fast_io_hosted.h> |
Adds native files, consoles, processes, threads, filesystem. | Hosted target. |
<fast_io.h> |
Hosted plus the legacy iostream bridge. | The tutorial's normal build; never include it in a freestanding target. |
The fast_io module applies the same boundary: when the target is not hosted,
it defines FAST_IO_FREESTANDING and omits the hosted export units. The
freestanding module still exports core I/O, containers and allocators.
2. The Allocator Contract
A freestanding target has no hidden heap. The default allocator is
freestanding_global_allocator: declared by fast_io, defined by you. It
exposes the two failure policies in the function names:
| Function | Policy |
|---|---|
allocate_aligned_conditional_zero_at_least_die(...) |
Terminate through fast_terminate() when the arena is exhausted. |
allocate_aligned_conditional_zero_at_least_try(...) |
Report std::errc::not_enough_memory on the herbception channel. |
deallocate_aligned_n(p, alignment, n) |
Release a block; the arena implementation may make this a no-op. |
The return type is allocation_least_result, a pointer plus the usable size.
generic_allocator_adapter and typed_generic_allocator_adapter
turn a raw allocator into the interface containers expect.
using heap_a = ::fast_io::generic_allocator_adapter<my_arena>;
::fast_io::containers::vector<int, heap_a> v;
v.push_back(42);
There is no fallback to malloc, no global operator new, and no exception
allocation. If the target has no heap, the container that needs one is simply not
instantiated.
3. Freestanding Algorithms
The fast_io::freestanding namespace provides the algorithms a container or
formatter needs without pulling in <algorithm>:
| Group | Names |
|---|---|
| Copy and fill | copy, copy_n, copy_backward,
move_backward, fill, fill_n,
non_overlapped_copy, non_overlapped_copy_n,
overlapped_copy, overlapped_copy_n |
| Memory | my_memcpy, my_memmove, my_memset,
my_memcmp, bytes_clear_n,
nonoverlapped_bytes_copy_n |
| Search and compare | find_if, find_not, find_last,
find_last_not, find_first_not_of,
find_last_of, find_last_not_of,
my_mismatch, equal,
lexicographical_compare,
lexicographical_compare_three_way, lower_bound |
| Construction and rotation | uninitialized_copy, uninitialized_copy_n,
uninitialized_move_n, uninitialized_default_construct,
uninitialized_default_construct_n, uninitialized_fill,
uninitialized_fill_n, rotate, remove |
| Traits | is_zero_default_constructible,
is_trivially_copyable_or_relocatable and their
_v forms. |
These are the same names a hosted build uses internally. They are exported by the module's
freestanding.inc, so a module consumer does not need the header algorithms.
4. I/O Without a Console
In a freestanding target there is no default stdout. print and
println still exist, but the first argument must be a device the target
supplies: a UART buffer, a framebuffer, a ring buffer, a host mailbox. There is no silent
fallback to a console that does not exist.
::fast_io::obuffer_view out{uart_buffer, uart_buffer + sizeof(uart_buffer)};
::fast_io::io::println(out, "boot: ", stage);
The same rule applies to errors: herbceptions carry a domain and a code on the return path.
There is no unwinder, no frame table and no personality routine. A target that cannot
afford even that can use the _die allocator policy and terminate on exhaustion.
5. Module and Header Boundary
The module exports the allocation adapters, native allocators, freestanding algorithms and
the core I/O vocabulary. freestanding_global_allocator itself is header-side:
it is a declaration you implement, not a library definition. fast_terminate is
exported with the hosted unit; in a freestanding build, use your target's trap directly or
the allocation policy that matches it.
<fast_io.h> in a freestanding target.
It asks for consoles, files, processes and the iostream bridge. Include
<fast_io_freestanding.h> or the smaller core header instead.
Key Takeaways
- Freestanding is selected by the header boundary, not by a runtime flag.
fast_io_freestanding.hprovides core I/O, containers and algorithms;fast_io.his hosted-only.freestanding_global_allocatoris declared by fast_io and defined by the target.- Allocation failure is explicit in the function name:
_dieor_try. - Containers carry their allocator in the type; there is no hidden heap.
- The module exports allocation adapters and freestanding algorithms;
freestanding_global_allocatorremains header-side. - There is no default console;
printneeds a target-supplied device.