<HTML>
<HEAD>
   <style>
     <!--
       P.indented {margin-left: 4em}
       XMP.indented {margin-left: 4em}
     -->
   </style>
   <TITLE>
       Adding "extern template"
   </TITLE>
</HEAD>

<BODY>

<TABLE ALIGN=RIGHT CELLSPACING=0 CELLPADDING=0 >
<TR>
<TD ALIGN=RIGHT>Document number:</TD>

<TD>&nbsp;06-0030/N1960</TD>
</TR>

<TR>
<TD ALIGN=RIGHT>Date:</TD>

<TD>&nbsp;2006-02-21</TD>
</TR>

<TR>
<TD ALIGN=RIGHT>Author:</TD>

<TD>&nbsp;John Spicer, Edison Design Group</TD>
</TR>

<TR>
<TD></TD>

<TD>&nbsp;<TT>jhs@edg.com</TT></TD>
</TR>
</TABLE>

<BR CLEAR=ALL>

<CENTER>
<H2>
Adding "extern template"
</H2>
</center>

<h3>
Introduction:
</h3>

A common technique for implementing automatic instantiation is for the
compiler to instantiate a function in each translation unit in which it
is referenced and for the linker to eliminate redundant copies of the
instantiation.  A drawback of this technique is that for some programs
the cost can be large both in compilation time and object file size.

A number of compilers allow the programmer to suppress the
implicit instantiation of templates by prefixing an explicit instantiation
directive with the <code>extern</code> keyword.

This document proposes specific semantics for this feature.

<h3>
Semantic Summary:
</h3>

<p>
This feature was first proposed to the committee in N1448 by Mat Marcus
and Gabriel Dos Reis.  While there was widespread agreement on the need
to support "extern template", there was not support for having
"extern template" suppress the instantiation of inline functions.  In
addition, N1448 proposed "extern template" as a mechanism to provide
greater control over the point of instantiation of a template.  It should
be noted that the current standard provides no such guarantees, even in
the presence of explicit instantiations, and this proposal does not
attempt to provide such a feature.

<p>
As a result of reflector discussions and discussions in the Core and
Evolution groups, the following rules are proposed:

<ol>
<li>
If an <code>extern template</code> directive appears in a translation unit,
an explicit instantiation of the entity must appear in another translation
unit, or later in the same translation unit.
<li>
An <code>extern template</code> directive may not name a static function
(but may name a static class member).
<li>
An <code>extern template</code> directive that names a class applies to
the members of the class, not the class itself.  It results in the implicit
instantiation of the class as well as that of any nested classes.
<li>
<code>extern template</code> has no normative affect on inline functions.
A note should be included indicating that implementations are encouraged to
suppress out-of-line copies of inline functions that were declared with
<code>extern template</code>.  Such inline functions are instantiated
though (so that they can be inlined).
</ol>


<h3>
Drafting notes:
</h3>

<p>
An issue I ran into when drafting this is that something that used to
say "If X is explicitly instantiated" is transformed to
"If X is the subject of an explicit instantiation declaration".
A more pithy phrase would be helpful.  One possibility is
"If X is explicitly instantiation-declared".

<h3>
Working Paper Changes:
</h3>

<p>
Revise 7.1.1 paragraph  5 as follows:

<blockquote>
The extern specifier can be applied only to the names of objects and functions,
or in an explicit instantiation ([temp.explicit]).
</blockquote>

<p>
Revise 14.6.4.1 paragraph 5 as follows:

<blockquote>
An explicit instantiation <ins>definition</ins> is an instantiation
point for the specialization ...
</blockquote>

<p>
Revise 14.7 paragraph 5 as follows:

<blockquote>
<ul>
<li>
an explicit instantiation <ins>definition</ins> shall appear at most
once in a program.
</ul>
</blockquote>

<p>
Revise 14.7.2, paragraph 2 as follows:

<blockquote>
<pre>
<em>explicit-instantiation:</em>
     template <em>declaration</em>
<ins>     extern template</code> <em>declaration</em></ins>
</pre>

<p>
<ins>
There are two forms of explicit instantiation: an explicit instantiation
definition and an explicit instantiation declaration.  An explicit
instantiation declaration begins with the <code>extern</code> keyword.
</ins>
</blockquote>

<p>
Revise 14.7.2 paragraph 4 as follows:

<blockquote>
<ul>
<li>
Otherwise, <ins>for an explicit instantiation definition</ins>
the definition of a non-exported ...
</ul>
</blockquote>

<p>
Revise 14.7.2 paragraph 7 as follows:

<blockquote>
<del>The</del><ins>An</ins>
explicit instantiation
<ins>that names</ins>
<del>of</del> a class template specialization
<ins>is an</ins> <del>also</del> explicit instantiat<ins>ion</ins><del>es</del>
<ins>of the same kind (declaration or definition) of</ins>
each of its members (not including members inherited from base classes)
<del>whose definition is visible at the point of instantiation and</del>
that has not been previously explicitly specialized in the translation
unit containing the explicit specialization, except as described below.
</blockquote>

<p>
At the end of 14.7.2 paragraph 7, add the following:

<blockquote>
<p>
An explicit instantiation definition that names a class template specialization
is also an explicit instantiation definition of the class template
specialization and is only an explicit instantiation definition of members
whose definition is visible at the point of instantiation.
<p>
An explicit instantiation declaration that names a class template
specialization has no effect on the class template specialization
itself (except for perhaps resulting in its implicit instantiation).
Other explicit instantiation declarations have the effect of suppressing
the implicit instantiation of the entity to which they refer, except
that an explicit instantiation declaration of an inline function has no
effect.  [<em>Note:</em> The intent is that an inline function
that is the subject of an explicit instantiation declaration will still be
implicitly instantiated when used so that the body can be considered for
inlining, but that no out-of-line copy of the inline function would be
generated in the translation unit. -- <em>end note</em>]

<p>
If an entity is the subject of both an explicit instantiation declaration
and an explicit instantiation definition in the same translation unit,
the definition shall follow the declaration.

An entity that is the subject of an explicit instantiation declaration and that
is also used in the translation unit shall be the subject of an explicit
instantiation definition somewhere in the program; otherwise the program
is ill-formed, no diagnostic required.  [<em>Note:</em> this rule does
apply to inline functions even though an explicit instantiation declaration
of such an entity has no other normative effect.  This is needed to ensure that
if the address of an inline function is taken in a translation unit in which
the implementation chose to suppress the out-of-line body, that another
translation unit will supply the body. <em>--end note</em>]

An explicit instantiation declaration shall not name a specialization of
a template with internal linkage.
</blockquote>

<h3>End of document.</h3>

</body>
</html>



