skip to content

In C++, how does an inline namespace let a library ship a new version of its types while users keep writing geo::Point?

level: seniorimportance: nice to knowfreq 25%

answer

  1. members act as the parent's
  2. the version stays in the symbol
  3. old versions remain reachable
  4. specialize as if in the parent

basics

~20 s

Members of an inline namespace are used as if declared in the enclosing namespace, so geo::Point names geo::v2::Point. The version stays in mangled names, so code built against v1 and code built against v2 refer to different symbols for functions that use Point.

solid answer

~40 s

An **inline namespace**, written `inline namespace v2 { ... }` inside `geo` (C++11), makes its members usable in most respects as members of `geo`: `geo::Point` finds `geo::v2::Point`, ADL treats `geo` and `geo::v2` as one, and users may specialize a template declared in `v2` as though it were declared in `geo`. A library ships version 2 by moving the `inline` from `v1` to `v2`; old code can still name `geo::v1::Point` explicitly. Because the real name includes `v2`, function symbols that mention it change, so code compiled against the old headers keeps referring to `v1` symbols and either links to retained `v1` code or fails to link, rather than calling `v2` code with the old layout. libc++'s `std::__1` and libstdc++'s `std::__cxx11` are two implementations' uses of this. The `inline` must appear on the namespace's first definition.

code

cpp · 29 lines
cpp
#include <cstddef>
#include <functional>
#include <iostream>

namespace geo {
namespace v1 {
struct Point { float x, y; };
}
inline namespace v2 {   // the current version
struct Point { double x, y, z; };
double norm2(const Point& p) { return p.x * p.x + p.y * p.y + p.z * p.z; }
}
}  // namespace geo

// Specialize std::hash for the type users know as geo::Point.
template <>
struct std::hash<geo::Point> {
    std::size_t operator()(const geo::Point& p) const noexcept {
        return std::hash<double>{}(p.x) ^ (std::hash<double>{}(p.y) << 1);
    }
};

int main() {
    geo::Point p{1, 2, 2};            // names geo::v2::Point
    geo::v1::Point old{1, 2};         // the old layout is still reachable
    std::cout << geo::norm2(p) << ' ' << sizeof(p) << ' ' << sizeof(old) << '\n';
    std::size_t h = std::hash<geo::Point>{}(p);
    (void)h;
}

go deeper

for a junior

Know that inline namespace members can be named through the enclosing namespace, and that this is unrelated to inline functions.

for a middle

Explain the lookup, argument-dependent lookup and specialization rules that make the inline namespace transparent, and the rule that inline must be on the first definition.

for a senior

Show how a library versions types with it, why the version in the symbol turns silent layout mismatches into link errors, and name the libc++ and libstdc++ uses as implementation choices.

for a principal

Decide whether a library's versioning scheme needs inline namespaces at all, and what it promises about keeping old versions' definitions in later releases.

## The rule An **inline namespace** is declared with the `inline` keyword before `namespace` (since C++11). The draft states that its members can be used in most respects as though they were members of the innermost enclosing namespace, and spells out what that means: - a using-directive naming the inline namespace is implicitly inserted into the enclosing namespace, so unqualified and qualified lookup in the enclosing namespace include its members; - the inline namespace and its enclosing namespace are both added to the associated namespaces of **argument-dependent lookup** whenever one of them is; - a member template of the inline namespace can be explicitly specialized, partially specialized or explicitly instantiated **as though it were a member of the enclosing namespace**; - the properties are transitive through nested inline namespaces. One rule about the keyword itself: `inline` may appear on a definition that reopens a namespace only if it was used on the definition that first declared it. Clang reports `non-inline namespace cannot be reopened as inline` for the reverse, and warns when an inline namespace is reopened without the keyword. ## Versioning a library with it ```cpp namespace geo { namespace v1 { struct Point { float x, y; }; } inline namespace v2 { // the current version struct Point { double x, y, z; }; double norm2(const Point& p); } } ``` User code keeps writing `geo::Point` and `geo::norm2(p)` and gets the version 2 entities; anyone who needs the old layout can still write `geo::v1::Point`. To release version 3, the library adds `v3`, moves `inline` to it, and ships. The value lies in the **real name**. `geo::norm2` is really `geo::v2::norm2`, and on the Itanium C++ ABI used by clang on macOS and Linux its symbol is `_ZN3geo2v25norm2ERKNS0_5PointE`, which `c++filt` shows as `geo::v2::norm2(geo::v2::Point const&)`. An object file compiled against version 1 headers references `geo::v1::norm2(geo::v1::Point const&)`. When it is linked with the version 2 library, two things can happen: 1. The library still ships the `v1` definitions, and the old object calls code that matches its layout. 2. The library dropped them, and the link fails with an undefined symbol. What does **not** happen is the old object calling version 2 code with a version 1 `Point`, which is the silent layout mismatch that versioned namespaces exist to prevent. The protection follows names: a function whose signature does not mention a versioned type keeps its old symbol. The material on ABI covers that boundary in depth. ## Two standard libraries that do this These are implementation choices, not requirements of the standard: - **libc++** declares the standard library inside `inline namespace _LIBCPP_ABI_NAMESPACE`, which is `__1` by default, so `std::vector` is really `std::__1::vector`, as `nm -C` on any libc++ program shows. - **libstdc++** puts its C++11-conforming `std::string` and `std::list` in `inline namespace __cxx11` (with an ABI tag) under its dual-ABI scheme, selected by the `_GLIBCXX_USE_CXX11_ABI` macro, so the old and the new layouts can both be present in the same library. In both cases users write `std::string` and never see the version. ## Inline namespace, using-directive or alias? | Tool | Qualified `geo::name` includes `v2` members | ADL for a `v2` type also searches `geo` | Name in symbols | |---|---|---|---| | `inline namespace v2` | always, even beside a same-named `geo` declaration | yes | includes `v2` | | `using namespace v2;` inside `geo` | only when `geo` itself declares no such name | no | includes `v2` | | `namespace current = v2;` alias | no, users write `geo::current::Point` | no | includes `v2` | The ADL column is why a plain using-directive is not enough. Argument-dependent lookup ignores using-directives, so for a `geo::v2::Point` argument it searches only `geo::v2`: a `draw(Point)` that the library declares directly in `geo` is not found by an unqualified `draw(p)`, and clang reports `use of undeclared identifier 'draw'; did you mean 'geo::draw'?`. With `v2` inline, `geo` is an associated namespace too and the call compiles. ## Syntax since C++20 C++17 added nested namespace definitions such as `namespace geo::detail { }`. C++20 allowed `inline` inside them, so `namespace geo::inline v2 { ... }` is equivalent to the two-level form above. Clang accepts it in C++17 mode only with the warning `inline nested namespace definition is a C++20 extension`. ## Interview summary - Members of an inline namespace behave as members of its parent for lookup, ADL and specialization. - The version is part of the real name, so mismatched builds fail to link instead of misbehaving silently. - Both major standard libraries use it, each in its own way.

  • Why is a using-directive inside geo not a substitute for an inline namespace?
    A using-directive makes v2's names visible to ordinary lookup in geo, but argument-dependent lookup ignores directives: for a geo::v2::Point argument it searches only geo::v2, so an unqualified call to a helper declared directly in geo fails. Qualified lookup differs too: geo::name includes inline members even beside a same-named declaration in geo, while a directive's members count only when geo declares none. An inline v2 makes both namespaces behave as one.
  • Does an inline namespace by itself guarantee binary compatibility between versions?
    No. It only makes mismatches visible in symbol names that mention the versioned entities. A struct declared outside the versioned namespace that holds a geo::Point member keeps its own unversioned name, so functions taking that struct do not change symbol when Point's layout does. Real ABI policy needs more than namespaces.

  • An inline namespace is about inlining the functions declared in it
  • geo::Point is ambiguous once both geo::v1 and inline geo::v2 declare Point
  • Inline namespaces are invisible in mangled symbol names
  • You can add inline to a namespace when you reopen it later
  • An inline namespace makes old and new layouts binary compatible

Assumes C++20 for the namespace geo::inline v2 shorthand; inline namespaces themselves exist since C++11.