Fallible construction: try_create, try_allocate, try_construct, try_clone

Ordinary C++ construction has no room for failure that isn’t an exception or undefined behavior: a constructor either succeeds or throws, and there is no standard way to report “allocation failed” or “the requested state is invalid” from one without unwinding. That is unusable on the same class of targets reloco targets everywhere else — firmware, RTOS tasks, interrupt paths, kernel-adjacent code — so reloco never puts fallible work inside a constructor. Instead, every type that can fail to come into existence exposes one (or more) of five static or member functions, and reports the outcome through reloco::result<T> (reloco::expected<T, reloco::error>, see Hardened containers and error.hpp) instead of throwing. reloco::error is the one error enum every fallible reloco operation uses; no type defines its own scoped error enum.

include/reloco/concepts.hpp defines a has_try_*_v<T, ...> compile-time detection trait for each of these functions (plus a matching C++20 concept of the same name, when available), so generic code — containers, factory helpers, test fixtures — can check which construction protocol a type supports and dispatch accordingly, without every type needing to inherit from a common base or register itself anywhere.

Function Detected by Use when
T::try_create(Args...) has_try_create_v<T, Args...> The type can use the process-wide reloco::default_allocator() (or needs no allocator at all)
T::try_allocate(reloco::allocator_ref, Args...) has_try_allocate_v<T, Args...> The caller must control which allocator backs the new instance
storage->try_construct(Args...) has_try_construct_v<T, Args...> Two-phase, in-place construction into caller-owned storage
source.try_clone(reloco::allocator_ref) / source.try_clone() has_try_clone_v<T> An existing instance needs an independent, fallible copy
T::try_clone_at(reloco::allocator_ref, T *storage, const T &source) has_try_clone_at_v<T> An optimized in-place clone into caller-owned storage

vector<T> and string follow the protocol with these extra factories, which are not part of the detected set: vector<T>::try_create(cap) only reserves capacity (size() == 0, and data() asserts on an empty vector), while vector<T>::try_create_sized(count) / try_allocate_sized(alloc, count) return count value-initialized elements, ready to be filled in place (for example by a C API writing into data()):

// A buffer of exactly `n` zeroed bytes for a C read function to fill in; fails with an error instead of throwing.
auto buffer = reloco::vector<std::byte>::try_create_sized(n);
if (!buffer) { return reloco::unexpected(buffer.error()); }
read_into(buffer->data(), buffer->size()); // n == 0 would trip data()'s non-empty assertion, so check it first

Converting between views and owners

Borrowed types convert to their owning counterparts with a fallible copy. The conversion is a member of the view, but it is only instantiated where you call it, so the owner’s header must be included there (the view headers only forward-declare the owner, which keeps them free of include cycles):

From To Call Include
string_view string sv.try_to_string() / sv.try_to_string(alloc) string.hpp
span<T> / span<const T> vector<T> sp.try_to_vector() / sp.try_to_vector(alloc) vector.hpp
span<const T> any existing vector, sso_vector, inline_vector, outline_vector v.try_append(sp), v.try_assign(sp) the container’s header
span<const T> new vector, sso_vector, inline_vector, secure_vector, boxed_slice C::try_create_from(sp) / C::try_allocate_from(alloc, sp) (inline_vector has no allocator: only try_create_from) the container’s header
span<T> any of the above sp.try_to_vector<C>() (e.g. sp.try_to_vector<reloco::inline_vector<int, 8>>()) the container’s header
inline_vector / inline_string heap vector / string v.try_to_vector(), s.try_to_string() (already existed)
#include <reloco/string.hpp>
#include <reloco/vector.hpp>

// Own a copy of a borrowed name so it outlives the buffer it was parsed from.
reloco::result<reloco::string> keep(reloco::string_view name) noexcept { return name.try_to_string(); }

// Append bytes received from a C API. The span may even point into `buf` itself; that case is handled.
reloco::result<void> add(reloco::vector<std::byte> &buf, reloco::span<const std::byte> chunk) noexcept {
  return buf.try_append(chunk); // on allocation failure `buf` is unchanged
}

try_append reserves capacity first, so on failure (allocation failure, or error::capacity_exceeded for inline_vector/outline_vector) the container is unchanged; try_assign does the same. Both accept a span aliasing the container’s own elements, even across an sso_vector spilling from inline to heap storage. They require a copy-constructible element type. The deque family (vec_deque and friends) does not have these yet.

This is a convention, not an interface: implement whichever of the five functions make sense for a given type (most types only need one or two), and generic code that wants to work with any of them checks for each function with the matching trait. Ported from reloco_legacy’s concepts.hpp, with two changes to fit this repository’s conventions (see below). Rather than hand-writing the if constexpr dispatch every time, most code should reach for reloco::construction_helpers (see below and include/reloco/construction_helpers.hpp), which already implements it once for every type that follows this protocol; reloco::unique_ptr<T> (see unique_ptr.hpp) is a small, complete example of a type built entirely on top of it. reloco::string (see string.hpp) is a real-world example that implements the protocol itself – try_create, try_allocate, try_clone, and try_clone_at – rather than consuming it, which is why reloco::unique_ptr<reloco::string>::try_create(...) composes automatically through has_try_create_v.

1. try_create: the default-allocator factory

struct widget {
  int value;

  static reloco::result<widget> try_create(int v) noexcept {
    if (v < 0)
      return reloco::unexpected(reloco::error::invalid_argument);
    return widget{v};
  }
};

reloco::result<widget> made = widget::try_create(3);

Implement try_create when a type can be instantiated without the caller specifying an allocator, typically because it delegates internally to reloco::default_allocator() (see Extending reloco) or because it needs no allocation at all. This is the common case for application code that has not opted into explicit allocator control.

2. try_allocate: the explicit-allocator factory

static reloco::result<widget>
try_allocate(reloco::allocator_ref alloc, int v) noexcept {
  if (v < 0)
    return reloco::unexpected(reloco::error::invalid_argument);
  // ... use `alloc` for any nested allocation the type needs ...
  return widget{v};
}

Implement try_allocate instead of (or alongside) try_create when memory residency must be strictly controlled by the caller — kernel subsystems choosing between paged and non-paged pools, an arena scoped to a single request, a caller-supplied test allocator that tracks leaks. alloc is a reloco::allocator_ref, the type-erased handle from Extending reloco; it is a cheap, non-owning two-word value, so take it by value.

3. try_construct: two-phase in-place construction

struct handle {
  int fd = -1; // noexcept-default-constructible "shell" state

  reloco::result<void> try_construct(const char *path) noexcept {
    fd = open_device(path);
    if (fd < 0)
      return reloco::unexpected(reloco::error::invalid_argument);
    return {};
  }
};

alignas(handle) unsigned char storage[sizeof(handle)];
auto *h = new (storage) handle(); // noexcept shell construction
if (auto result = h->try_construct("/dev/example"); !result) {
  h->~handle(); // caller destroys the shell before reclaiming storage
  report(result.error());
}

Implement try_construct for zero-copy initialization directly into caller-owned storage: placement-new a noexcept-default-constructible “shell” object first, then call try_construct to perform the fallible part (resource acquisition, validation). If try_construct fails, the caller is responsible for invoking the destructor on the shell object before reclaiming the raw memory — the shell is a live object from the moment it is placement-newed, whether or not try_construct later succeeds.

4. try_clone: fallible copying

// Allocator-aware: for types owning allocator-backed nested resources.
reloco::result<widget> try_clone(reloco::allocator_ref alloc) const noexcept;

// Self-contained: for types with no allocator dependency.
reloco::result<widget> try_clone() const noexcept;

Implement one of these two shapes — never both — when a type needs an independent copy that can fail (allocation failure, a resource that cannot be duplicated). has_try_clone_v<T> is satisfied by either shape, so generic code does not need to know which one a given type chose; if generic code specifically needs to tell them apart (as construction_helpers:: try_clone does, to know whether to pass an allocator), it checks has_try_clone_allocator_aware_v<T>/has_try_clone_self_contained_v<T> individually instead.

5. try_clone_at: optimized in-place clone

static reloco::result<void>
try_clone_at(reloco::allocator_ref alloc, widget *storage, const widget &source) noexcept {
  new (storage) widget{source.value};
  return {};
}

Implement try_clone_at alongside (or instead of) try_clone when cloning directly into caller-owned, uninitialized storage avoids a move that try_clone would otherwise require — the same in-place-construction tradeoff try_construct makes for first-time initialization.

Dispatching generically over the protocol

Generic code that wants to construct or clone a type without knowing in advance which functions it implements checks the traits with if constexpr. reloco::construction_helpers (see include/reloco/construction_helpers.hpp) already does this once, choosing the most efficient available tier for a given T:

// Picks try_allocate, falling back to try_create, falling back to a plain
// noexcept constructor call -- whichever T actually implements.
reloco::result<widget> made =
    reloco::construction_helpers::try_allocate<widget>(alloc, 3);

// Two-phase, in-place construction into caller-owned storage: picks
// T::try_construct if available, otherwise placement-news T directly.
reloco::result<void> constructed =
    reloco::construction_helpers::try_construct<widget>(alloc, storage, 3);

// Fallible copy, dispatching to try_clone/try_clone_at (allocator-aware or
// self-contained, whichever T implements) or a plain copy constructor.
reloco::result<widget> cloned = reloco::construction_helpers::try_clone(alloc, source);

Under C++20, the underlying traits are also available as real concepts (reloco::has_try_create<T, Args...>, etc.), usable directly in a template constraint or requires clause instead of if constexpr:

template <reloco::has_try_clone T>
void register_clonable_type(); // only compiles for T satisfying has_try_clone

Both forms check exactly the same thing; include/reloco/concepts.hpp defines the _v trait once and derives the C++20 concept from it, so there is no risk of the two disagreeing.

Lazy singletons: fallible_singleton, atomic_fallible_singleton

include/reloco/fallible_singleton.hpp builds reloco::construction_helpers ::try_construct into two ready-made lazy-singleton wrappers, useful for globals whose setup is non-trivial and fallible (so they cannot be plain static T instance; globals) without reintroducing C++’s static initialization order fiasco:

struct config {
  static reloco::result<config> try_create() noexcept { /* parse, validate, ... */ }
};

// Not thread-safe: construct explicitly, once, from a single thread
// (e.g. early in main()) before any other thread can call instance().
reloco::result<config *> cfg = reloco::fallible_singleton<config>::instance();

reloco::fallible_singleton<T>::instance() (optionally instance(reloco::allocator_ref)) constructs T in static storage on its first call, via whichever try_construct/try_allocate/try_create/plain nothrow tier T implements (exactly the tiers construction_helpers already resolves), and returns the same T * on every later call. It is not thread-safe: only use it from a single, controlled initialization path.

reloco::atomic_fallible_singleton<T>::instance() is the thread-safe counterpart: a futex.hpp futex_word state (empty/initializing/ ready) lets every thread skip locking once initialization has completed (a lock-free acquire-load), falling back – only for the first, contended call – to a compare_exchange claim of the empty -> initializing transition. The single winner performs construction while every other concurrent caller blocks via futex_wait until the winner publishes the outcome and wakes them via futex_wake_all, exactly like once_lock<T>’s slow path. If construction fails, the state reverts to empty so a later call (from any thread) may retry. No lock is embedded or caller-supplied: futex.hpp itself is the customization point for a freestanding/kernel target with no std::mutex (via RELOCO_FUTEX_BACKEND_CUSTOM, see docs/futex.md), so atomic_fallible_singleton no longer needs its own separate escape hatch for that case.

Differences from reloco_legacy

reloco_legacy/include/reloco/concepts.hpp is the origin of this pattern, but one thing changed to fit this repository’s conventions: legacy took a fallible_allocator &, a virtual base class. reloco has no virtual allocator interface; has_try_allocate_v, has_try_clone_v, and has_try_clone_at_v instead expect a reloco::allocator_ref, the type-erased, non-virtual handle described in Extending reloco.

Both legacy and reloco require every one of these functions to report its outcome through the library’s one error type — reloco::error/ reloco::result<T> here (see error.hpp) — rather than an arbitrary per-type error enum. This is enforced by concepts.hpp’s detection traits themselves: has_try_create_v<T, Args...> (and the other four) only holds if T::try_create(Args...) returns exactly reloco::result<T>, so a type that reports failure through some other type is treated as not implementing the protocol at all.

reloco_legacy/include/reloco/fallible_singleton.hpp is the origin of fallible_singleton/atomic_fallible_singleton. Legacy dispatched construction through its own is_fallible_initializable/ fallible_constructed protocol — a T::try_init(constructor_key) member gated by a friend-only key type, entirely separate from try_create/try_allocate/try_construct. reloco instead builds directly on construction_helpers::try_construct, so any T that already works with unique_ptr<T> or the other helpers above works with fallible_singleton/atomic_fallible_singleton too, with no dedicated protocol or key type needed. As above, the allocator parameter is a reloco::allocator_ref rather than a fallible_allocator &.

Building strings from parts

// One allocation for the whole result; on failure nothing is leaked and the error says why.
auto path = reloco::string::try_concat(dir, "/", name);            // "dir/name"
auto csv  = reloco::string::try_join(fields, ",");                 // any range of string_view-convertibles
// Append several parts to an existing string; it grows at most once and is unchanged on failure.
// Views that alias the string itself (s.view()) are allowed.
auto ok   = path->try_append_all("/", ext);
// Explicit allocator: reloco::string::try_allocate_concat(alloc, a, b, ...)

More sequence helpers

reloco::vector<int> v = /* 1 2 5 */;
// Insert a range before index 2 (reserves first: unchanged on failure). The span may alias v itself.
auto ok = v.try_insert_span(2, reloco::span<const int>(mid, 2));
// Remove `count` elements starting at `first` in one pass.
ok = v.try_erase_range(1, 3);
// O(1) unordered removal: the last element takes the removed one's place.
ok = v.try_swap_remove(0);
v.truncate(2);                                   // shorten; no-op if already shorter
auto tail = v.try_split_off(1);                  // vector<int> with the elements from index 1; v keeps the first 1
// On a span: first index matching a value or predicate, and a fallible map into an owner.
auto at   = sp.position(8);                      // optional<size_t>
auto big  = sp.position_if([](int x) { return x > 10; });
auto twice = sp.try_map_to([](int x) { return x * 2; });   // result<vector<int>>
// Convert between owner flavours (copies; fails with capacity_exceeded for fixed-capacity targets).
auto small = v.try_convert_to<reloco::sso_vector<int, 8>>();
auto text  = reloco::string::try_create("x")->try_convert_to<reloco::sso_string<16>>();

vec_deque, sso_vec_deque and inline_vec_deque also have try_create_from(span), try_append(span) and try_assign(span). Unlike the vectors they reject a span that points into the deque’s own ring storage with error::invalid_argument (the ring can wrap and reallocate, so supporting aliasing would be fragile); clone first.

Spans, string views and byte reinterpretation

#include <reloco/span.hpp>
#include <reloco/string_view.hpp>   // string_view.hpp only forward-declares span; include span.hpp where you convert

// string_view <-> span<const char>, both implicit.
reloco::string_view sv = "hello";
reloco::span<const char> chars = sv;
reloco::string_view again = chars;                 // also from span<char>
auto text = reloco::string_view::from_bytes(reloco::span<const uint8_t>(raw, n));   // bytes as text, no validation

// "Downcast" to a smaller unit. sizeof(U) must divide sizeof(T), alignof(U) <= alignof(T), const is preserved,
// and U must be byte-like (char, signed/unsigned char, uint8_t, char8_t, std::byte) so strict aliasing holds.
reloco::span<uint32_t> words = /* ... */;
reloco::span<uint8_t> u8 = words.cast_to<uint8_t>();   // 4x the elements
auto c  = words.as_chars();                            // span<char>      (span<const char> for const T)
auto u  = words.as_uint8();                            // span<uint8_t>
auto wb = words.as_writable_bytes();                   // span<std::byte> (non-const only)
auto s8 = sv.as_uint8();                               // also on string_view; sv.as_bytes() -> span<const std::byte>
// char <-> uint8_t is the identity-size case: span<char>::as_uint8() just retypes the span.

// Any other trivially copyable U (e.g. uint64_t -> uint32_t) needs the explicit opt-in, because it can violate
// strict aliasing:
auto halves = words64.unsafe_cast_to<uint32_t>();

// The checked direction for parsing: bytes -> typed records. Fails (invalid_argument) if misaligned or the byte
// count is not a multiple of sizeof(U).
auto records = packet_bytes.try_cast_to<const Header>();

Header layout: byte_like.hpp (the is_byte_like_v trait) has no dependencies; string_view.hpp depends on it and forward-declares span, while span.hpp never includes string_view.hpp, so there is no include cycle (and string.hpp does not pull in span.hpp’s iterator machinery).