<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <title>Explicit Virtual Function Overrides</title>
    <base href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/" />
    <meta http-equiv="content-type" content="text/html; charset=utf-8" />
<style type="text/css">
  p {text-align:justify}
  li {text-align:justify}
  ins {background-color:#FFFF99}
  del {background-color:#FF9999}
</style>
  </head>
  <body>
    document number: N2928=09-0118<br />
    Ville Voutilainen &lt;Ville.Voutilainen@ixonos.com&gt;<br />
    Alisdair Meredith &lt;public@alisdairm.net&gt;<br />
    Jens Maurer &lt;Jens.Maurer@gmx.net&gt;<br/>
    Chris Uzdavinis &lt;cuzdav@gmail.com&gt;<br/>
    2009-07-17
    
    <h1>Explicit Virtual Overrides</h1>

    This paper directly addresses ballot comments US-41 and FI-1 registered
    against the CD Ballot for the revised C++ standard, N2800.
    
    <h2>Problem Summary</h2>
    
    We would like to tighten the rules for overriding virtual functions, to
    detect these problems:
    <ul>
      <li>
        a base class <code>B</code> has a virtual function <code>f</code>, and
        the user declares their own <code>f</code> in derived class
        <code>D</code>, thereby accidentally overriding <code>B::f</code>.
      </li>
      <li>
        a base class <code>B</code> has a virtual function <code>f</code>, and
        the user wishes to override that function in the derived class
        <code>D</code>, but misspells the name as <code>D::foo</code>.
      </li>
      <li>
        a base class <code>B</code> has a virtual function <code>f</code>, and
        the user wishes to override that function in the derived class
        <code>D</code>, but inadvertently alters the parameter list.
      </li>
    </ul>

    We are deliberately not solving the problem that a base class
    <code>B1</code> has a virtual function <code>f</code>, another base class
    <code>B2</code> also has a virtual function <code>f</code> with the same
    signature, the user derives a class <code>D</code> from both
    <code>B1</code> and <code>B2</code> and declares <code>D::f</code> to
    override both <code>B1::f</code> and <code>B2::f</code>, one of which may
    have been inadvertent. (This is sometimes referred to as the Siamese Twins
    problem.)
    
    <p>
      The scope of the problem was reduced to the minimal necessary to solve
      the common real-world problems. This means it does not tackle ideas such
      as 'final overriders' or function renaming, both of which would be
      available if a scheme closer to the C++/CLI standard was pursued.
    </p>
    
    
    <h2>History</h2>
    
    <a href="2005/n1827.htm">N1827</a> was presented at the Mont Tremblant
    meeting as a first pass at this problem. Feedback was positive, but
    concerned about the 'viral' nature of that proposal. It marked the base
    class as special and implied that all descendants must be treated as
    special as well, even when not marked.
    <p>
    <a href="2006/n2108.html">N2108</a> was presented at the Portland meeting
    and introduced the concept of an explicit polymorphic class as a
    refinement of the existing polymorphic class type. The virtual function
    syntax wording could then be updated to use the new class type, while
    deferring the final choice of syntax to mark the class as explicit to a
    later paper.  This resolved the viral problem by marking the derived class 
    instead of the base, and that is more frequently under the developer's 
    control.  Feedback was to advance to Core once a suitable mark-up could
    be found.
    </p>
    <p>
    Attributes for C++0x were initially proposed in 
    <a href="2007/n2236.pdf">N2236</a> and subsequently adopted in
    <a href="2008/n2751.pdf">N2751</a>.  They provide a suitable
    markup mechanism without overloading existing keywords or introducing
    new ones.
    </p>
    <p>
    <a href="2007/n2365.html">N2365</a> was produced from feedback at the
    Toronto 2007 meeting, adopting the attribute syntax.  The main change
    was a direct request to solve the similar problems with name-hiding.
    There remained some reservation that while any program marked up with
    the feature that successfully translated would have identical meaning
    (the attributes purely add additional checks and do not affect semantics)
    there were still some subtle changes in the definition of the virtual keyword.
    </p>
    <p>
    <a href="2009/n2852.html">N2852</a> resolved the outstanding issues 
    in direct response to
    national body comments from the first CD ballot.  The notion of an
    explicitly polymorphic class was no longer needed, and a new attribute
    was introduced to explicitly mark a function that should override, rather
    than add subtle extra meaning to the virtual keyword.
    </p>
    <p>
    This paper is a response to the Core Working Group review of the
    N2852 version. This paper renames [[check_names]] to [[base_check]].
    </p>
    
    <h2>Proposed Solution</h2>
    <p>
    We propose to introduce three new attributes to support compile-time checks
    that name hiding and virtual function overrides occur exactly as intended.
    </p>

    <p>
    The <code>[[override]]</code> attribute indicates that a member function
    override a virtual function in at least one of its direct or indirect 
    base classes.  If no appropriate virtual function can be found, the program
    is ill-formed.
    </p>

    <p>
    The <code>[[hiding]]</code> attribute indicates that a class member hides
    a name found in at least one of its direct or indirect base classes.
    If no members with such a name are found, the program is ill-formed.
    </p>

    <p>
    The <code>[[base_check]]</code> attribute for a class definition
    indicates that any name hiding or virtual function overriding within
    that class shall be marked with the appropriate attribute.  If there is
    any 'implicit' overriding or hiding then the program is ill-formed.
    </p>

    <p>
    This design meets three key compatibility requirements:
    <li>
      Use of the attributes does not depend on their being used in a base
      class
    </li>
    <li>
      Use of the attributes in a library class is invisible to users of that
      class
    </li>
    <li>
      The meaning of a program does not change if a compiler ignores the
      attributes
    </li>
    </p>

    <h3>Implicit virtual and the Accidental Override</h3>
    <p>
    The 'simple' syntax for overriding virtual functions in C++ today is
    convenient, but potentially misleading.  Take the following example:
    </p>
<pre>
struct base {
  virtual void some_func();
};

struct derived : base {
  void some_func();
};

</pre>
    <p>
    Is the use of some_func in derived intentionally an override, or an
    accidental name clash? Without clear documentation or a detailed analysis
    of the use/implementation it is hard to be sure.<br />

    The common assumption is that all such use is deliberate, and to ignore
    the question.  Yet while it is reasonable to assume that competent developers
    would not accidentally make such a mistake, it is easily introduced by
    dependencies on third party libraries.  Maintenance of the base classes might
    introduce such a clash without clear notice in the code, and the ensuing bugs
    can be very hard to track down.  Worse, even a rigorous set of unit tests does
    not guarantee protection, as it is the base class, not the derived, that is
    changing behaviour and so the effects are not guaranteed to be covered by
    existing tests. Likewise, source analysis tools can offer little help here
    without an additional hint from the coder. To that end, we offer the
    [[base_check]] attribute and the requirement in such a marked class that
    intentional overrides use the [[override]] attribute.
    </p>
<pre>
struct base {
  virtual void some_func();
};

struct derived1 <ins>[[base_check]]</ins> : base {
  void some_func();  // error, accidental override with base_check attribute
};

struct derived2 <ins>[[base_check]]</ins> : base {
  void some_func <ins>[[override]]</ins> (); // OK, override with override attribute
};

</pre>
    <p>
    </p>
    <h3>Mis-spellings and mistaken signature</h3>
    <p>
    A second set of problems arise when a user intends to override a function, but gets
    the signature wrong in some way.  Common examples are mis-spelling the name 
    (transposing two characters, bad capitalization); using the wrong data type (double
    instead of float); or missing the cv-qualification.
    </p>
    <p>
    All these classes of errors can be detected in the same way.  When the virtual
    keyword is used in a class defined with the </code>[[base_check]]</code> attribute,
    a matching declaration <b>must</b> be found in one of the base classes for it to
    override.  In implementation terms it would suffice to check the inherited vtable,
    rather than search the full DAG of base classes looking for a match.
    </p>
    Note: This kind of problem should also be detected with a good set of unit tests.
    It is hard to solve in a lexical analysis tool without a further hint, see next point!
    <p>
<pre>
struct base {
  virtual void some_func1();
  virtual void some_func2(float);
  virtual void some_func3() const;
  virtual long some_func4(int);
};

struct derived : base {
  void sone_func1 <ins>[[override]]</ins> ();  // error, mis-spelled name
  void some_func2 <ins>[[override]]</ins> (double); // error, bad argument type
  void some_func3 <ins>[[override]]</ins> (); // error, missing cv-qualification
  int some_func4 <ins>[[override]]</ins> (int); // ill-formed: return type does not match B::h
};
</pre>
    </p>
    <h3>Introducing new virtual functions</h3>
    <p>
    In an earlier version of this paper, a [[new]] attribute was necessary to
    introduce a new virtual function into a name-checked class.  The addition
    of the [[override]] attribute means that this is no longer necessary, and
    this paragraph is mostly to demonstrate that no features have been lost.
    A new virtual function is automatically introduced by using the virtual
    keyword and <b>not</b> supplying the [[override]] attribute.
    </p>
    <p>
<pre>
struct base {
  virtual void some_func1();
};

struct derived <ins>[[base_check]]</ins> {
  virtual void some_func1(); // error, accidental override
  virtual void some_func2(); // OK, new virtual function introduced
};
</pre>
    </p>
    <p>
    We do <b>not</b> propose a facility to introduce a virtual function with an identical 
    signature to that of a virtual function in a base class, that <i>hides</i> rather than
    <i>overrides</i> the base member.  This facility is available in other languages, but
    adding it to C++ at this late stage would be disruptive, and violate one of the goals of
    the attribute form of this proposal: Any program that compiles with the attributes will
    behave exactly as if they were not present.  They are a pure syntax-checking device, and
    have no impact on semantics.
    </p>
    <h3>Deliberate name hiding</h3>
    <p>
    Another problem that catches people out when defining classes is that
    introducing a name will hide occurrences of the same name from any base
    classes.  Sometimes this is intentional, but there is little chance of a
    warning when it occurs accidentally.  The language-supplied workaround in
    those cases is a using declaration, but you only apply the workaround when
    you are aware of the problem.  The <code>[[base_check]]</code> attribute
    will require the compiler inform you of accidental hiding.  The <code>
    [[hiding]]</code> attribute will allow you to tell the compiler that the
    hiding is intentional, and the program remains well-formed.
    </p>
    <p>
      Example:
    </p>
<pre>
class B {
  typedef B self;
  virtual void some_func1();
  virtual void some_func2(float);
  virtual void some_func3() const;
  virtual long some_func4(int);
  virtual void f();
  virtual void h(int);
  void j(int);
  void k(int);
};

class D <ins>[[base_check]]</ins> : public B {
  using B::j;
  void sone_func1 <ins>[[override]]</ins> ();  // ill-formed: mis-spelled name
  void some_func2 <ins>[[override]]</ins> (double); // ill-formed: bad argument type
  void some_func3 <ins>[[override]]</ins> (); // ill-formed: missing cv-qualification
  int some_func4 <ins>[[override]]</ins> (int); // ill-formed: return type does not match B::some_func4
  virtual void f <ins>[[override]]</ins> (); // OK: overrides B::f
  virtual void g(long);      // new virtual function introduced
  void h(int);               // ill-formed: overriding without [[override]]
  virtual void h(double);    // ill-formed: new virtual function hides void h(int)
  virtual void h <ins>[[hiding]]</ins> (char *);  // OK, new virtual function hides base
  virtual   int j( double );           // OK, using declaration prevents hiding
  int k( double );           // ill-formed: name hiding and no using declaration
  double k <ins>[[hiding]]</ins> ( char * ); // OK, hiding is clearly indicated
  double m <ins>[[hiding]]</ins> ( char * ); // ill-formed, hiding is requested, but not present
  typedef D self; // ill-formed, new type definition hides the definition in B
};
</pre>


    </p>
    <h3>Corner cases</h3>
    <p>
    A really determined user should be able to combine the [[hiding]] and [[override]] attributes
    although it seems unlikely to be used in practice beyond test suites.
<pre>
struct A {
  virtual void fn();
};

struct B : A {
  void fn [[hiding]] (int);
};

struct C : B {
  void fn [[override, hiding]]();
};
</pre>


    <h2>Proposed Wording</h2>

    Add a new section 7.6.5(new) dcl.attr.override between the current sections
    7.6.4 and 7.6.5:
    <blockquote>
      7.6.5(new) Class member name checking attributes
      <p>
        The <em>attribute-token</em> <code>override</code> asserts
        that a virtual member function overrides a function in a base
        class.  It shall appear at most once in each
        <em>attribute-list</em> and no
        <em>attribute-argument-clause</em> shall be present.  The
        attribute applies to virtual member functions being declared
        in a class definition.
      </p>
      <p>
        If a virtual member function <code>f</code> is marked
        <code>override</code> and does not override (10.3
        class.virtual) a member function of a base class the program
        is ill-formed.
      </p>
      <p>
        The <em>attribute-token</em> <code>hiding</code> asserts that
        a class member name hides a name in a base class.  It shall
        appear at most once in each <em>attribute-list</em> and no
        <em>attribute-argument-clause</em> shall be present.  The
        attribute applies to class members being declared in a class
        definition.
      </p>
      <p>
        If a class member is marked <code>hiding</code> and its name
        does not hide (3.3.10 basic.scope.hiding, 10.2
        class.member.lookup) a class member name in a base class the
        program is ill-formed.
      </p>
      <p>
        The <em>attribute-token</em> <code>base_check</code>
        specifies that overriding and hiding of base members is strictly checked within a class.  It shall appear at most once in
        each <em>attribute-list</em> and no
        <em>attribute-argument-clause</em> shall be present. The
        attribute applies to a class definition.
      </p>
      <p>
        In a class definition marked <code>base_check</code>, if a
        virtual member function that is neither implicitly-declared nor a destructor overrides (10.3 class.virtual) a
        member function of a base class and it is not marked
        <code>override</code>, the program is ill-formed.  Similarly,
        in such a class definition, if a class member name other than that of an implicitly-declared special member function hides
        (3.3.10 basic.scope.hiding, 10.2 class.member.lookup) a class 
        member name in a base class and it is not marked 
        <code>hiding</code>, the program is ill-formed.  [ Note: A
        <em>using-declaration</em> makes the potentially hidden name
        visible, avoiding the need for the <code>hiding</code>
        attribute. -- end note ]
      </p>
      <p>
      [<i>Example:</i>
      <pre> class B {
    virtual void some_func();

    virtual void f(int);
    virtual void h(int);
    void j(int);
    void k();
    typedef B self;
 };

 class D [[base_check]] : public B {
    void sone_func [[override]] ();          // error: mis-spelled name

    void f [[override]] (int);               // ok: f implicitly virtual, overrides B::f
    virtual void f [[override]] (long);      // error: non-matching argument type
    virtual void f [[override]] (int) const; // error: non-matching cv-qualification
    virtual int  f [[override]] (int);       // error: non-matching return type

    virtual void g(long);      // ok: new virtual function introduced

    void h(int);               // error: h implicitly virtual, but overriding without marker
    virtual void h(double);    // error: hides B::h without marker
    virtual void h [[hiding]] (char *);      // ok

    using B::j;
    int j(double);                   // ok: not hiding due to "using"
    void j(int);                     // ok, despite 'obscuring' B::j(int)
    virtual int j [[hiding]] (void); // error: not hiding due to "using"

    int k;                           // error: hides B::k without marker

    int m [[hiding]] ( int );        // error: no hiding despite marker
    typedef D self;                  // error: hides B::self without marker
 };
	</pre>
      <i>end example</i> ]
      </p>
    </blockquote>

  </body>
</html>
