P1815R2: Translation-unit-local entities

Audience: CWG
S. Davis Herring <herring@lanl.gov>
Los Alamos National Laboratory
February 14, 2020

History

Introduction

This paper is a replacement for P1498R1 that includes the wording promised for it and thereby addresses US35. While its general principle of forbidding exposure of internal-linkage constructs to other translation units is followed, this paper presents rules that differ for consistency, especially for templates. It also includes wording (which would conflict) for P2003R1 and P1884R0 and thereby addresses US133 and US134 (and, in a sense, US36).

The function to which a dependent name refers cannot, of course, be determined merely from the template declaration that contains it. P1347R1 proposed forbidding such a call that selects an internal-linkage function via overload resolution. Such overload resolution can in general require undesirably extensive analysis of otherwise-local declarations, so P1498R1 goes further and (with a single exception for certain constants) forbids any use of such a name in a context where code generation might occur for another translation unit. (This includes, for example, the return type of a non-template function with more than internal linkage; while it need not be mangled, it is accessible via decltype anywhere the function is.) We can consider such overload sets to be poisoned by their mere inclusion of an unusable candidate. The unusable candidate might be a template; templates whose declarations involve internal entities must themselves be internal to avoid needing to perform template argument deduction for them (even if the resulting specialization might not involve any internal types). (As a reminder, export is irrelevant here because the client translation unit might be in the same module.)

However, ADL considers a set of functions and function templates which itself cannot be known until instantiation. It is therefore impossible to reliably preclude poisoned overload sets by any reasonable restriction on (non-internal) templates.

This paper therefore merely proscribes the external use of internal entities and of poisoned overload sets, and does so for the definition of a template only during instantiation. Even a template that unambiguously calls an internal function can have non-internal linkage so long as the only specializations used in other translation units are those generated by an explicit specialization or instantiation. (Implicit instantiation of a template does not preclude other implicit instantiations and so does not allow usage from other translation units.) Local/anonymous classes (including closure types) are internal based on where they are defined, regardless of whether they (attempt to) use internal entities, partly to avoid any need to include in an invented name for the class an internal-linkage name introduced by the enclosing definition.

It would of course be possible to discard certain overload resolution candidates before deciding whether an overload set is poisoned. Most simply, any that do not support the number of arguments given in the call could be excluded. More sophisticated analysis might exclude functions or function templates with parameter types not convertible from a (non-dependent) argument type, as well as those whose constraints are known not to be met for any instantiation. Preferring future flexibility and compatibility over invention, this paper simply poisons overload sets unconditionally.

Wording

A definition domain is a private-module-fragment or the portion of a translation unit before its private-module-fragment (if any). A definition of an inline function or variable shall be reachable from the end of every definition domain in which it is odr-used outside of a discarded statement.

module Q; import N; namespace S { struct Z { template operator T(); }; } void test() { auto x = make(); // OK, decltype(x) is R::X in module M R::f(x); // error: R and R::f are not visible here f(x); // OK, calls R::f from interface of M f(x, S::Z()); // error: S::f in module M not considered // even though S is an associated namespace apply(x, S::Z()); // ~~OK,~~error: S::f is visible in instantiation context, ~~and~~but // R::g ~~is visible even though it~~ has internal linkage and cannot be used outside TU #2 }

A declaration D names an entity E if

D contains a lambda-expression whose closure type is E,

E is not a function or function template and D contains an id-expression, type-specifier, nested-name-specifier, template-name, or concept-name denoting E, or

E is a function or function template and D contains an expression that names E ([basic.def.odr]) or an id-expression that refers to a set of overloads that contains E. [Note: Non-dependent names in an instantiated declaration do not refer to a set of overloads ([temp.nondep]). — end note]

A declaration is an exposure if it either names a TU-local entity (defined below), ignoring

the function-body for a non-inline function or function template (but not the deduced return type for a (possibly instantiated) definition of a function with a declared return type that uses a placeholder type ([dcl.spec.auto])),

the initializer for a variable or variable template (but not the variable’s type),

friend declarations in a class definition, and

any reference to a non-volatile const object or reference with internal or no linkage initialized with a constant expression that is not an odr-use ([basic.def.odr]),

or defines a constexpr variable initialized to a TU-local value (defined below). [Note: An inline function template can be an exposure even though explicit specializations of it might be usable in other translation units. — end note]

An entity is TU-local if it is

a type, function, variable, or template that

has a name with internal linkage, or

does not have a name with linkage and is declared, or introduced by a lambda-expression, within the definition of a TU-local entity,

a type with no name that is defined outside a class-specifier, function body, or initializer or is introduced by a defining-type-specifier that is used to declare only TU-local entities,

a specialization of a TU-local template,

a specialization of a template with any TU-local template argument, or

a specialization of a template whose (possibly instantiated) declaration is an exposure. [Note: The specialization might have been implicitly or explicitly instantiated. — end note]

A value or object is TU-local if either

it is, or is a pointer to, a TU-local function or the object associated with a TU-local variable,

it is an object of class or array type and any of its subobjects or any of the objects or functions to which its non-static data members of reference type refer is TU-local and is usable in constant expressions.

If a (possibly instantiated) declaration of, or a deduction guide for, a non-TU-local entity in a module interface unit (outside the private-module-fragment, if any) or module partition ([module.unit]) is an exposure, the program is ill-formed. Such a declaration in any other context is deprecated ([depr.local]).

If a declaration that appears in one translation unit names a TU-local entity declared in another translation unit that is not a header unit, the program is ill-formed. A declaration instantiated for a template specialization ([temp.spec]) appears at the point of instantiation of the specialization ([temp.point]).

[Example:
Translation unit #1:

export module A;
static void f() {}
inline void it() {f();} // error: is an exposure of f
static inline void its() {f();} // OK
template<int> void g() {its();} // OK
template void g<0>();

decltype(f) *fp;  // error: f (though not its type) is TU-local
auto &fr=f;                     // OK
constexpr auto &fr2=fr;         // error: is an exposure of f
constexpr static auto fp2=fr;   // OK

struct S {void (&ref)();} s{f};             // OK: value is TU-local
constexpr extern struct W {S &s;} wrap{s};  // OK: value is not TU-local

static auto x=[]{f();};  // OK
auto x2=x;               // error: the closure type is TU-local
int y=([]{f();}(),0);    // error: the closure type is not TU-local
int y2=(x,0);            // OK

namespace N {
  struct A {};
  void adl(A);
  static void adl(int);
}
void adl(double);

inline void h(auto x) {adl(x);} // OK, but a specialization might be an exposure

Translation unit #2:

module A;
void other() {
  g<0>();  // OK: specialization is explicitly instantiated
  g<1>();  // error: instantiation uses TU-local its
  h(N::A{});  // error: overload set contains TU-local N::adl(int)
  h(0);  // OK: calls adl(double)
  adl(N::A{});  // OK: N::adl(int) not found; calls N::adl(N::A)
  fr();                   // OK: calls f
  constexpr auto ptr=fr;  // error: fr is not usable in constant expressions here
}

— end example]

Non-local use of TU-local entities [depr.local]

A declaration of a non-TU-local entity that is an exposure ([basic.link]) is deprecated. [Note: Such a declaration in an importable module unit is ill-formed. — end note] [Example:

namespace {
  struct A {
    void f() {}
  };
}
A h();                      // deprecated: not internal linkage
inline void g() {A().f();}  // deprecated: inline and not internal linkage

— end example]