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

User · Answer

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   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  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

User · Answer

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  p      X  amp r      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 amp      X amp    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- gt someMethod            compiler error          int i   m- gt 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 lt T gt  requires its parameter to be a complete type  while boost  container  vector lt T gt  does not  Sometimes  a complete type is required only if you use certain member functions  this is the case for std  unique ptr lt T gt   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

User · Answer

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 amp   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

User · Answer

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  lt typename gt  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  lt typename T gt  class Foo       X lt T gt   ptr      X lt T gt  amp  ref      Declare a member to be a pointer or a reference to one of its incomplete instantiations   class Foo       X lt int gt   ptr      X lt int gt  amp  ref      Declare function templates or member function templates which accept return incomplete types   template  lt typename T gt     void      f1 X lt T gt    template  lt typename T gt     X lt T gt     f2     Declare functions or member functions which accept return one of its incomplete instantiations   void      f1 X lt int gt    X lt int gt     f2     Define function templates or member function templates which accept return pointers references to the incomplete type  but without using its members    template  lt typename T gt     void      f3 X lt T gt    X lt T gt  amp      template  lt typename T gt     X lt T gt  amp    f4 X lt T gt  amp  in    return in    template  lt typename T gt     X lt T gt     f5 X lt T gt   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 lt int gt    X lt int gt  amp      X lt int gt  amp    f4 X lt int gt  amp  in    return in    X lt int gt     f5 X lt int gt   in    return in     Use it as a base class of another template class  template  lt typename T gt  class Foo   X lt T gt        OK as long as X is defined before                        Foo is instantiated   Foo lt int gt  a1     Compiler error   template  lt typename T gt  struct X     Foo lt int gt  a2     OK since X is now defined   Use it to declare a member of another class template   template  lt typename T gt  class Foo       X lt T gt  m     OK as long as X is defined before                Foo is instantiated       Foo lt int gt  a1     Compiler error   template  lt typename T gt  struct X     Foo lt int gt  a2     OK since X is now defined   Define function templates or methods using this type  template  lt typename T gt    void    f1 X lt T gt  x           OK if X is defined before calling f1 template  lt typename T gt    X lt T gt     f2   return X lt T gt           OK if X is defined before calling f2  void test1        f1 X lt int gt          Compiler error    f2 lt int gt            Compiler error    template  lt typename T gt  struct X      void test2        f1 X lt int gt          OK since X is defined now    f2 lt int gt            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 lt int gt        compiler error   Use one of its instantiations to declare a member   class Foo       X lt int gt  m     compiler error      Define functions or methods using one of its instantiations  void      f1 X lt int gt  x                   compiler error  X lt int gt     f2    return X lt int gt            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 lt int gt   m                  void method                             m- gt someMethod            compiler error          int i   m- gt someField     compiler error            Create explicit instantiations of the class template  template struct X lt int gt

User · Answer

In file in which you use only Pointer or Reference to a class And no member member function should be invoked thought those Pointer  reference   with class Foo   forward declaration  We can declare data members of type Foo  or Foo amp    We can declare  but not define  functions with arguments  and or return values  of type Foo   We can declare static data members of type Foo  This is because static data members are defined outside the class definition

User · Answer

The main rule is that you can only forward-declare classes whose memory layout  and thus member functions and data members  do not need to be known in the file you forward-declare it   This would rule out base classes and anything but classes used via references and pointers

User · Answer

Take it that forward declaration will get your code to compile  obj is created   Linking however  exe creation  will not be successfull unless the definitions are found

User · Answer

As  Luc Touraille has already explained it very well where to use and not use forward declaration of the class   I will just add to that why we need to use it   We should be using Forward declaration wherever possible to avoid the unwanted dependency injection   As  include header files are added on multiple files therefore  if we add a header into another header file it will add unwanted dependency injection in various parts of source code which can be avoided by adding  include header into  cpp files wherever possible rather than adding to another header file and use class forward declaration wherever possible in header  h files

User · Answer

As long as you don t need the definition  think pointers and references  you can get away with forward declarations  This is why mostly you d see them in headers while implementation files typically will pull the header for the appropriate definition s

User · Answer

I just want to add one important thing you can do with a forwarded class not mentioned in the answer of Luc Touraille   What you can do with an incomplete type   Define functions or methods which accept return  pointers references to the incomplete type and forward that pointers references  to another function        void  f6 X            void  f7 X amp            void  f8 X  x ptr  X amp  x ref    f6 x ptr   f7 x ref       A module can pass through an object of a forward declared class to another module

User · Answer

Lakos distinguishes between class usage   in-name-only  for which a forward declaration is sufficient  and in-size  for which the class definition is needed     I ve never seen it pronounced more succinctly

User · Answer

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

User · Answer

The general rule I follow is not to include any header file unless I have to   So unless I am storing the object of a class as a member variable of my class I won t include it  I ll just use the forward declaration

[c++] When can I use a forward declaration?

Examples related to c++

Examples related to forward-declaration

Examples related to c++-faq