When can I use a forward declaration?

Question

I am looking for the definition of when I am allowed to do forward declaration of a class in another class's header file:

Am I allowed to do it for a base class, for a class held as a member, for a class passed to member function by reference, etc. ?

Answer 1

Put yourself in the compiler's position: when you forward declare a type, all the compiler knows is that this type exists; it knows nothing about its size, members, or methods. This is why it's called an incomplete type. Therefore, you cannot use the type to declare a member, or a base class, since the compiler would need to know the layout of the type.

Assuming the following forward declaration.

class X;

Here's what you can and cannot do.

What you can do with an incomplete type:

• Declare a member to be a pointer or a reference to the incomplete type:

  class Foo {
      X *pt;
      X &pt;
  };
  

• Declare functions or methods which accept/return incomplete types:

  void f1(X);
  X    f2();
  

• Define functions or methods which accept/return pointers/references to the incomplete type (but without using its members):

  void f3(X*, X&) {}
  X&   f4()       {}
  X*   f5()       {}
  

What you cannot do with an incomplete type:

• Use it as a base class

  class Foo : X {} // compiler error!
  

• Use it to declare a member:

  class Foo {
      X m; // compiler error!
  };
  

• Define functions or methods using this type

  void f1(X x) {} // compiler error!
  X    f2()    {} // compiler error!
  

• Use its methods or fields, in fact trying to dereference a variable with incomplete type

  class Foo {
      X *m;            
      void method()            
      {
          m->someMethod();      // compiler error!
          int i = m->someField; // compiler error!
      }
  };
  

---

When it comes to templates, there is no absolute rule: whether you can use an incomplete type as a template parameter is dependent on the way the type is used in the template.

For instance, std::vector<T> requires its parameter to be a complete type, while boost::container::vector<T> does not. Sometimes, a complete type is required only if you use certain member functions; this is the case for std::unique_ptr<T>, for example.

A well-documented template should indicate in its documentation all the requirements of its parameters, including whether they need to be complete types or not.

Answer 2

You will usually want to use forward declaration in a classes header file when you want to use the other type (class) as a member of the class. You can not use the forward-declared classes methods in the header file because C++ does not know the definition of that class at that point yet. That's logic you have to move into the .cpp-files, but if you are using template-functions you should reduce them to only the part that uses the template and move that function into the header.

Answer 3

I'm writing this as a separate answer rather than just a comment because I disagree with Luc Touraille's answer, not on the grounds of legality but for robust software and the danger of misinterpretation.

Specifically, I have an issue with the implied contract of what you expect users of your interface to have to know.

If you are returning or accepting reference types, then you are just saying they can pass through a pointer or reference which they may in turn have known only through a forward declaration.

When you are returning an incomplete type X f2(); then you are saying your caller must have the full type specification of X. They need it in order to create the LHS or temporary object at the call site.

Similarly, if you accept an incomplete type, the caller has to have constructed the object which is the parameter. Even if that object was returned as another incomplete type from a function, the call site needs the full declaration. i.e.:

class X;  // forward for two legal declarations 
X returnsX();
void XAcceptor(X);

XAcepptor( returnsX() );  // X declaration needs to be known here

I think there's an important principle that a header should supply enough information to use it without a dependency requiring other headers. That means header should be able to be included in a compilation unit without causing a compiler error when you use any functions it declares.

Except

1. If this external dependency is desired behaviour. Instead of using conditional compilation you could have a well-documented requirement for them to supply their own header declaring X. This is an alternative to using #ifdefs and can be a useful way to introduce mocks or other variants.

2. The important distinction being some template techniques where you are explicitly NOT expected to instantiate them, mentioned just so someone doesn't get snarky with me.

Answer 4

None of the answers so far describe when one can use a forward declaration of a class template. So, here it goes.

A class template can be forwarded declared as:

template <typename> struct X;

Following the structure of the accepted answer,

Here's what you can and cannot do.

What you can do with an incomplete type:

• Declare a member to be a pointer or a reference to the incomplete type in another class template:

  template <typename T>
  class Foo {
      X<T>* ptr;
      X<T>& ref;
  };
  

• Declare a member to be a pointer or a reference to one of its incomplete instantiations:

  class Foo {
      X<int>* ptr;
      X<int>& ref;
  };
  

• Declare function templates or member function templates which accept/return incomplete types:

  template <typename T>
     void      f1(X<T>);
  template <typename T>
     X<T>    f2();
  

• Declare functions or member functions which accept/return one of its incomplete instantiations:

  void      f1(X<int>);
  X<int>    f2();
  

• Define function templates or member function templates which accept/return pointers/references to the incomplete type (but without using its members):

  template <typename T>
     void      f3(X<T>*, X<T>&) {}
  template <typename T>
     X<T>&   f4(X<T>& in) { return in; }
  template <typename T>
     X<T>*   f5(X<T>* in) { return in; }
  

• Define functions or methods which accept/return pointers/references to one of its incomplete instantiations (but without using its members):

  void      f3(X<int>*, X<int>&) {}
  X<int>&   f4(X<int>& in) { return in; }
  X<int>*   f5(X<int>* in) { return in; }
  

• Use it as a base class of another template class

  template <typename T>
  class Foo : X<T> {} // OK as long as X is defined before
                      // Foo is instantiated.
  
  Foo<int> a1; // Compiler error.
  
  template <typename T> struct X {};
  Foo<int> a2; // OK since X is now defined.
  

• Use it to declare a member of another class template:

  template <typename T>
  class Foo {
      X<T> m; // OK as long as X is defined before
              // Foo is instantiated. 
  };
  
  Foo<int> a1; // Compiler error.
  
  template <typename T> struct X {};
  Foo<int> a2; // OK since X is now defined.
  

• Define function templates or methods using this type

  template <typename T>
    void    f1(X<T> x) {}    // OK if X is defined before calling f1
  template <typename T>
    X<T>    f2(){return X<T>(); }  // OK if X is defined before calling f2
  
  void test1()
  {
     f1(X<int>());  // Compiler error
     f2<int>();     // Compiler error
  }
  
  template <typename T> struct X {};
  
  void test2()
  {
     f1(X<int>());  // OK since X is defined now
     f2<int>();     // OK since X is defined now
  }
  

What you cannot do with an incomplete type:

• Use one of its instantiations as a base class

  class Foo : X<int> {} // compiler error!
  

• Use one of its instantiations to declare a member:

  class Foo {
      X<int> m; // compiler error!
  };
  

• Define functions or methods using one of its instantiations

  void      f1(X<int> x) {}            // compiler error!
  X<int>    f2() {return X<int>(); }   // compiler error!
  

• Use the methods or fields of one of its instantiations, in fact trying to dereference a variable with incomplete type

  class Foo {
      X<int>* m;            
      void method()            
      {
          m->someMethod();      // compiler error!
          int i = m->someField; // compiler error!
      }
  };
  

• Create explicit instantiations of the class template

  template struct X<int>;
  

Answer 5

As well as pointers and references to incomplete types, you can also declare function prototypes that specify parameters and/or return values that are incomplete types. However, you cannot define a function having a parameter or return type that is incomplete, unless it is a pointer or reference.

Examples:

struct X;              // Forward declaration of X

void f1(X* px) {}      // Legal: can always use a pointer
void f2(X&  x) {}      // Legal: can always use a reference
X f3(int);             // Legal: return value in function prototype
void f4(X);            // Legal: parameter in function prototype
void f5(X) {}          // ILLEGAL: *definitions* require complete types

Answer 6

Lakos distinguishes between class usage

1. in-name-only (for which a forward declaration is sufficient) and
2. in-size (for which the class definition is needed).

I've never seen it pronounced more succinctly :)