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.

Do not include <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