call_location / call_location_ref

include/reloco/call_location.hpp

An optional, compile-time-stripable file:line caller location, for passing into assert/fault-reporting-style functions without forcing every build (or every call site) to pay for it.

call_location is the plain {file, line} pair. call_location_ref is the thin (pointer plus int), trivially-copyable wrapper actually passed around by value – a default-constructed ref (or call_location_ref::none()) means “no location is available”; call_location_ref::current() captures the location of its own caller.

Every location-aware API takes exactly one call_location_ref parameter rather than inventing a bespoke optional-pair convention per call site. Some call sites architecturally cannot supply a location at all – a fixed-signature function pointer slot (an extern "C" callback table entry, a trap handler vector, anything crossing an ABI boundary the kernel does not control the shape of) cannot grow an extra parameter just because one caller happens to know its own source location. For exactly these cases, a location-aware kernel API ships a location-less export alongside the location-aware one, both forwarding into one shared implementation that takes a call_location_ref – call_location_ref::none() for the former, a captured location for the latter. See the header’s @file block for the full worked example.

current() vs. a __FILE__/__LINE__ macro

A macro expanding to call_location{__FILE__, __LINE__} looks like the obvious way to capture a caller’s location, but silently breaks the moment it is used as a default argument: default-argument expressions are bound once, at the point a function is declared, so a where = SOME_MACRO() default would always report call_location.hpp’s own declaration site, never the real caller’s. current() instead uses the GCC/Clang __builtin_FILE()/__builtin_LINE() intrinsics (the same mechanism std::source_location::current() is built on, available before C++20 and without pulling in <source_location>) as its own parameters’ default values – these are specially re-evaluated at each omitted-argument call site, including transitively through a chain of default arguments, so current() correctly reports whichever real call site ultimately triggered it. RELOCO_CALL_LOCATION_HAS_BUILTINS (defined by the header itself, from __has_builtin) is 1 when this is available; on a compiler without these intrinsics, current() falls back to plain __FILE__/__LINE__, which is still correct when current() is called directly/explicitly at the real call site, but not when relied upon as some other function’s default argument.

RELOCO_ENABLE_CALL_LOCATION (see reloco_config.hpp) is the build-time switch controlling whether current() actually captures a location, or defaults to none() instead – set it to 0 to strip every caller-location string this header would otherwise contribute to the binary’s rodata, for size-constrained builds (early boot stages, ROM-resident firmware) that cannot justify the cost.

debug_call_location_ref vs. release_call_location_ref

debug_call_location_ref is just an alias for call_location_ref. release_call_location_ref is its permanently empty companion type (no data members, has_value() unconditionally false, no value()) for an inter-module ABI boundary – a stable shared-library export, a versioned driver/plugin interface – that must never change shape depending on RELOCO_ENABLE_CALL_LOCATION/ RELOCO_CALL_LOCATION_HAS_BUILTINS, or any field call_location ever grows in the future. An API that wants both ships one overload per type. RELOCO_CALL_LOCATION_DEBUG (see reloco_config.hpp) selects which overload’s parameter actually gets a default argument – RELOCO_CALL_LOCATION_DEFAULT_IF_DEBUG/ RELOCO_CALL_LOCATION_DEFAULT_IF_RELEASE are a complementary pair of default-argument clauses (each already includes its own leading =, written directly after the parameter name), exactly one of which is ever non-empty – so an omitted-argument call is never ambiguous between the two overloads:

class mutex {
public:
  // Debug builds (RELOCO_CALL_LOCATION_DEBUG != 0): the default
  // argument lives here, so an omitted-argument call resolves to this
  // overload and captures a real location.
  void lock(reloco::debug_call_location_ref where RELOCO_CALL_LOCATION_DEFAULT_IF_DEBUG) {
    lock_impl(where);
  }

  // Release builds (RELOCO_CALL_LOCATION_DEBUG == 0): the default
  // argument lives here instead, so an omitted-argument call resolves
  // to this overload -- always zero-sized, frozen shape.
  void lock(reloco::release_call_location_ref where RELOCO_CALL_LOCATION_DEFAULT_IF_RELEASE) {
    (void)where;
    lock_impl(reloco::call_location_ref::none());
  }

private:
  void lock_impl(reloco::call_location_ref where);
};

See the header’s @file block for the full worked version of this example.