<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
<html> <head>
<title>Unique Instantiations of Templates</title>
</head>
<body>
<h1>C++ Extension Proposal: Unique Instantiations</h1>
<h2>The Problem: Weak Symbols are Inefficient</h2>
<p>C++ template instantiations for a particular entity can, and often
do, occur in many different translation units. The symbols associated
with template instantiations are therefore emitted as "weak", so the
linker can coalesce them. However, coalescing weak symbols takes time
(especially in the dynamic linker where it matters), so we want to
reduce the number of weak symbols in shared libraries to improve
application load times.</p>
<p>To reduce the number of weak symbols, one can use C++ explicit
instantiation <i>declarations</i> (called "extern templates" in GCC), which
tell the compiler to suppress the generation of template
instantiations for a particular template and set of template
arguments. For example, the following explicit instantiation
declaration suppresses instantiations of the
<code>basic_string<char></code> template's member functions,
reducing the number of weak symbols:
<pre>
extern template class basic_string<char>;
</pre>
</p>
<p>Explicit instantiation declarations suppress template
instantiations, so they are paired with explicit instantiation
<i>definitions</i>, which force the compiler to instantiate the
template at that point in the source code. So, for example, a shared
library's sources would contain the corresponding
<code>basic_string<char></code> instantiation:
<pre>
template class basic_string<char>;
</pre>
</p>
<p>That reduces the number of weak symbols created overall (since
users of <code>basic_string<char></code> won't implicitly get
instantiations of its member functions in their own translation
units), but because the C++ language allows explicit instantiation
declarations and implicit instantiations to coexist in different
translation units, the explicit instantiation definitions must still
produce weak symbols. In the common case, however, the explicit
instantiation definition is globally unique, in which case we could
further eliminate weak symbols by emitting non-weak symbols for
explicit instantiation definitions that follow explicit instantiation
declarations. The explicit instantiation declaration, in this case,
ensures that no implicit instantiations will generate weak
symbols. The only pitfall is that we have no guarantee that the
explicit instantiation definition is globally unique.</p>
<h2>Proposed Solution: An Attribute for "Unique" Instantiations</h2>
<p>To address this problem, we propose the introduction of a new
attribute, <code>unique_instantiation</code>, that can be added to
explicit instantiations to signal that the corresponding explicit
instantiation definition is globally unique. Since it guarantees that
no other explicit instantiations exist, an explicit instantiation
definition marked <code>unique_instantiation</code> can produce
non-weak symbols for its member functions, vtable, RTTI data, etc., so
long as the explicit instantiation declaration ensures that weak
symbols will not be emitted for these entities.</p>
<p>The use pattern for <code>unique_instantiation</code> is simple:
place <code>__attribute__((__unique_instantiation__))</code> on both
the explicit instantiation declaration and on the explicit
instantiation definition for commonly-used template specializations
such as <code>basic_string<char></code>, where the explicit
instantiation declaration is in the header defining
<code>basic_string</code> and the explicit instantiation definition is
in a single source file in the shared library responsible for
<code>basic_string</code>, e.g.,
<pre>
// <string> header
template<typename CharT,
typename Traits = char_traits<CharT>,
typename Allocator = allocator<CharT>>
class basic_string { /* ... */ };
extern template class __attribute__((__unique_instantiation__)) basic_string<char>;
// string.cpp in the shared library
template class __attribute__((__unique_instantiation__)) basic_string<char>;
</pre>
</p>
<p>An explicit instantiation that has the
<code>unique_instantiation</code> attribute is called a <i>unique</i>
explicit instantiation. Semantically,
<code>unique_instantiation</code> has the following restrictions:
<ul>
<li>The <code>unique_instantiation</code> attribute shall only
appertain to an explicit instantiation.</li>
<li>If an entity is subject to a unique explicit instantiation, then
all explicit instantiations of that entity shall have the
<code>unique_instantiation</code> attribute.</li>
<li>If an entity is subject to a unique explicit instantiation in
one translation unit and either
<ul>
<li>the entity is used ([basic.def.odr]) in another translation
unit where it is not subject to a unique explicit instantiation, or</li>
<li>the entity is subject to an explicit template instantiation
definition in more than one translation unit</li>
</ul>
then the program is ill-formed; no diagnostic required.
</li>
<li>A unique explicit instantiation definition shall follow an explicit
instantiation declaration of the same entity. [<i>Note</i>: this
requirement encourages a programming style that uses unique explicit
instantiation declarations (typically in a header) to suppress
implicit instantiations of a template or its members, so that the
unique explicit instantiation definition of that template or its members
is unique. <i>- end note</i>]</li>
</ul>
</p>
<hr>
<address></address>
<!-- hhmts start --> Last modified: Sat Dec 3 13:01:45 PST 2011 <!-- hhmts end -->
</body> </html>