Title: Separating Interface and Implementation in C++

Client code makes use of an object via its public interface, without any recourse to implementation details. Since the authors of client code have to use an object through its public interface that interface is all they need to understand. This public interface typically comprises member function declarations.

// naive.h - implementation hiding example.
#ifndef INCLUDED_NAIVE_H
#define INCLUDED_NAIVE_H
#include <string>
#include <utility>
#include <map>

namespace naive {
/** Telephone list. Example of implementing a
*     telephone list using a naive implementation.
*/
class telephone_list {
public:
  /** Create a telephone list.
  * @param    name    The name of the list.
  */
  telephone_list(const std::string& name);

  /** Get the list's name.
  * @return   the list's name.
  */
  std::string get_name() const;

  /** Get a person's phone number.
  * @param    person   Person's name (exact match)
  * @return   pair of success flag and (if success)
  *             number.
  */
  std::pair<bool, std::string>
  get_number(const std::string& person) const;

  /** Add an entry. If an entry already exists for
  *     this person it is overwritten.
  *   @param  name    The person's name
  *   @param  number  The person's number
  */
  telephone_list&
  add_entry(const std::string& name, 
            const std::string& number);
private:
  typedef std::map<std::string, std::string> dictionary_t;
  std::string  name;
  dictionary_t dictionary;
  telephone_list(const telephone_list& rhs);
  telephone_list& operator=(const telephone_list& rhs);
};
} // namespace naive
#endif

C++ allows developers to separate the implementation code for member functions from the class definition, but there is no comparable support for separating the member data that implements an object's state (or, for that matter, for separating the declarations of private member functions). Consequently the implementation detail exposed in a class's definition is still there as background noise, providing users with an added distraction. The definition of a class is typically encumbered with implementation "noise" that is of no interest to the user and is inaccessible to the client code written by that user: the naïve implementation shows this with MyDict, myName and dict.

The purpose of defining a class in a header file is for the definition of that class to be included in any translation units that define the client code for that class. If classes are designed in a naïve manner this leads to compilation dependencies upon details of the implementation that are not only inaccessible to the client code but also (in most cases) do not affect it in any way.

These compilation dependencies are undesirable for two reasons:

In a medium to large system the effect of these compilation dependencies can multiply to an extent that causes excessive and problematic build times.

Library code frequently defines points of customisation for user code to exploit. One of the ways to do this is to specify an interface as a class and allow the user code to supply objects that conform to this interface.

Such a library is typically compiled before the user code is written. In this case the library contains the "client code" and for this to have compilation dependencies on the implementation would be problematic.

Clearly, the naïve implementation makes no provision for alternative implementations.

A private "representation" class is written that embodies the same functionality and interface as the naïve class - however, unlike the naïve version, this is defined and implemented entirely within the implementation file. The public interface of the class published in the header is unchanged, but the private implementation details are reduced to a single member variable that points to an instance of the "representation" class, each of its member functions forwards to the corresponding function of the "representation" class.

The term "Cheshire Cat" (see [Murray1993]) is an old one, coined by John Carollan over a decade ago. Sadly it seems to have disappeared from use in contemporary C++ literature. It appears described as a special case of the Bridge pattern in "Design Patterns" [GOF95], but the name "Cheshire Cat" is not mentioned. Herb Sutter (in [Sut00]) discusses it under the name "Pimpl idiom", but considers it only from the perspective if its use in reducing physical dependencies. It has also been called "Compilation Firewall".

Cheshire Cat requires "boilerplate" code in the form of forwarding functions (see "Cheshire Cat Implementation" sidebar below) that are tedious to write and (if the compiler fails to optimise them away) can introduce a slight performance hit. It also requires care with the copy semantics (although it is possible to factor this out into a smart pointer - see Griffiths99). As the relationship between the public and implementation classes is not explicit it can cause maintenance issues.

// cheshire_cat.h  Cheshire Cat -
//           implementation hiding example

#ifndef INCLUDED_CHESHIRE_CAT_H
#define INCLUDED_CHESHIRE_CAT_H
#include <string>
#include <utility>

namespace cheshire_cat {
class telephone_list {
public:
  telephone_list(const std::string& name);
  ~telephone_list();

  std::string get_name() const;

  std::pair<bool, std::string>
  get_number(const std::string& person) const;

  telephone_list&
  add_entry(const std::string& name, 
            const std::string& number);
private:
  class telephone_list_implementation;
  telephone_list_implementation* rep;
  telephone_list(const telephone_list& rhs);
  telephone_list& operator=(
                 const telephone_list& rhs);
};
} // namespace cheshire_cat
#endif

One or more areas of the class functionality are factored out from the naïve implementation into separate helper classes. The class published in the header holds a pointer to each of these classes and delegates responsibility for the corresponding functionality by forwarding the corresponding operations. This is similar to Cheshire Cat, except that some implementation may remain exposed (like myName in the example) and there may be more than one helper class. (The helper classes may be defined and implemented in the implementation file - as in the sample code - or placed in a header file and made available for use by other code.)

Delegation is attractive where there is a distinct area of functionality that can be factored out or shared with another class. In maintenance and performance terms it is similar to Cheshire Cat.

// delegation.h - Delegation implementation hiding
//   example.

#ifndef INCLUDED_DELEGATION_H
#define INCLUDED_DELEGATION_H
#include <string>
#include <utility>

namespace delegation {
class telephone_list {
public:
  telephone_list(const std::string& name);
  ~telephone_list();

  std::string get_name() const;

  std::pair<bool, std::string>
  get_number(const std::string& person) const;

  telephone_list&
  add_entry(const std::string& name, 
            const std::string& number);
private:
  std::string name;
  class dictionary;
  dictionary* lookup;
  telephone_list(const telephone_list& rhs);
  telephone_list& operator=(
                 const telephone_list& rhs);
};
} // namespace delegation
#endif

As with Cheshire Cat a private "representation" class is written which implements the same functionality and interface as the naïve class but is defined and implemented entirely within the implementation file. The variations from Cheshire Cat are:

This is described in some detail in Coplien's "Advanced C++ Style and Idioms" [Cope92].

Frankly Envelope/Letter confuses us - we don't see what advantage it gives over Cheshire Cat. (Maybe it is just a misguided attempt to represent the correspondence of interface and implementation functions explicitly?) But please read Coplien and make up your own mind! In performance terms each client call initiates two function calls dispatched via the v-table - so it is the slowest of the idioms. (However it is rare that the overhead of a virtual function call is significant.)

// envelope_letter.h - Envelope/Letter
//   implementation hiding example.

#ifndef INCLUDED_ENVELOPE_LETTER_H
#define INCLUDED_ENVELOPE_LETTER_H
#include <string>
#include <utility>

namespace envelope_letter {
class telephone_list {
public:
  telephone_list(const std::string& name);
  virtual ~telephone_list();

  virtual std::string get_name() const;

  virtual std::pair<bool, std::string>
  get_number(const std::string& person) const;

  virtual telephone_list&
  add_entry(const std::string& name, 
            const std::string& number);
protected:
  telephone_list();
private:
  telephone_list* rep;
  telephone_list(const telephone_list& rhs);
  telephone_list& operator=(
                 const telephone_list& rhs);
};
} // namespace envelope_letter
#endif

All member data is removed from the naïve class and all member functions are made pure virtual. In the implementation file a derived class is defined that implements these member functions. The derived class is not used directly by client code, which sees only a pointer to the public class.

This is described in some detail in Mark Radford's "C++ Interface Classes - An Introduction" [Radford04].

Conceptually the Interface Class idiom is the simplest of those we consider. However, it may be necessary to provide an additional component and interface in order to create instances. Interface Classes, being abstract, can not be instantiated by the client. If a derived "implementation" class implements the pure virtual member functions of the Interface Class, then the client can create instances of that class. (But making the implementation class publicly visible re-introduces noise.) Alternatively, if the implementation class is provided with the Interface Class and (presumably) buried in an implementation file, then provision of an additional instantiation mechanism - e.g. a factory function - is necessary. This is shown as a static create function in the corresponding sidebar.

As objects are dynamically allocated and accessed via pointers this solution requires the client code to manage the object lifetime. This is not a handicap where the domain understanding implies objects are to be managed by a smart pointer (or handle) but it may be significant in some cases.

Note: Interfaces may play an additional role in design to that addressed in this article - they may be used to delineate each of several roles supported by a concrete type. This allows for client code that depend only on (the interface to) the relevant role.

// interface_class.h - Interface Class
//   implementation hiding example.

#ifndef INCLUDED_INTERFACE_CLASS_H
#define INCLUDED_INTERFACE_CLASS_H
#include <string>
#include <utility>

namespace interface_class {
class telephone_list {
public:
  static telephone_list*
                   create(const std::string& name);
  virtual ~telephone_list()   {}

  virtual std::string get_name() const = 0;

  virtual std::pair<bool, std::string>
  get_number(const std::string& person) const = 0;

  virtual telephone_list&
  add_entry(const std::string& name, 
            const std::string& number) = 0;
protected:    
  telephone_list()   {}
  telephone_list(const telephone_list& rhs) {}
private:
  telephone_list& operator=(
                 const telephone_list& rhs);
};
} // namespace interface_class
#endif

All member data is removed from the naïve class, the public interface becomes non-virtual forwarding functions that delegate to corresponding private pure virtual functions. As with Interface Class the implementation file defines a derived class that implements these member functions. The derived class is not used directly by client code, which sees only a pointer to the public class.

This is described in some detail in Sutter's "Exceptional C++ Style" [Sut04].

We had thought Non-Virtual Public Interface an idea that had been tried and discarded as introducing unjustified complexity. While the standard library uses this idiom in the iostreams design we've yet to see an implementation of the library that exploits the additional flexibility (in implementing the public functions) it offers over Interface Class. Further, there are some costs to providing this flexibility:

// non_virtual_public_interface.h - Non-Virtual
//   Public Interface implementation hiding example

#ifndef INCLUDED_NONVIRTUAL_PUBLIC_INTERFACE_H
#define INCLUDED_NONVIRTUAL_PUBLIC_INTERFACE_H
#include <string>
#include <utility>

namespace non_virtual_public_interface {
class telephone_list {
public:
  static telephone_list* create(
                          const std::string& name);
  virtual ~telephone_list() {}

  std::string get_name() const
    { return do_get_name(); }

  std::pair<bool, std::string>
  get_number(const std::string& person) const
    { return do_get_number(person); }

  virtual telephone_list&
  add_entry(const std::string& name, 
            const std::string& number)
    { return do_add_entry(name, number); }
protected:    
  telephone_list()    {}
  telephone_list(const telephone_list& rhs) {}
private:
  telephone_list& operator=(
                 const telephone_list& rhs);
  virtual std::string do_get_name() const = 0;
  virtual std::pair<bool, std::string>
  do_get_number(const std::string& person) const = 0;
  virtual telephone_list&
  do_add_entry(const std::string& name, 
               const std::string& number) = 0;
};
} // namespace non_virtual_public_interface
#endif

All the idioms considered address this problem reasonably successfully. The only implementation detail any of these idioms expose is the mechanism by which they support the separation:

Delegation is in a way the odd one out, because it does not by nature conceal all the implementation detail. This point is illustrated in our example implementation where the std::string member myName is visible in the definition of TelephoneList. Delegation reduces the implementation noise exposed to clients, but - unless all functionality is delegated to one (or more) other classes - it leaves the class still vulnerable to the problems suffered by the naïve implementation.

// MCheshireCat.cpp - implementation hiding example.

#include "cheshire_cat.h"
#include <map>

namespace cheshire_cat {
// Declare the implementation class
class telephone_list::telephone_list_implementation {
public:
  telephone_list_implementation(
                           const std::string& name);
  ~telephone_list_implementation();
  std::string get_name() const;
  std::pair<bool, std::string>
  get_number(const std::string& person) const;
  void add_entry(const std::string& name,
                 const std::string& number);
private:
  typedef std::map<std::string, std::string>
                                       dictionary_t;
  std::string  name;
  dictionary_t dictionary;
};

// Implement the stubs for the wrapper class
telephone_list::telephone_list(
                            const std::string& name)
   : rep(new telephone_list_implementation(name)) {}

telephone_list::~telephone_list() { delete rep; }

std::string telephone_list::get_name() const {
  return rep->get_name();
}

std::pair<bool, std::string> telephone_list::
get_number(const std::string& person) const {
  return rep->get_number(person);
}


telephone_list& telephone_list::add_entry(
                        const std::string& name,
                        const std::string& number) {
  rep->add_entry(name, number);
  return *this;
}

// Implement the implementation class
telephone_list::telephone_list_implementation::
          telephone_list_implementation(
                            const std::string& name)
   : name(name) {}

telephone_list::telephone_list_implementation::
          ~telephone_list_implementation() {}

std::string telephone_list::
   telephone_list_implementation::get_name() const {
  return name;
}

std::pair<bool, std::string>
telephone_list::telephone_list_implementation::
       get_number(const std::string& person) const {

  dictionary_t::const_iterator i
       = dictionary.find(person);

  return(i != dictionary.end()) ? 
      std::make_pair(true, (*i).second) :
      std::make_pair(true, std::string());
}

void telephone_list::telephone_list_implementation::
add_entry(const std::string& name,
          const std::string& number) {
  dictionary[name] = number;
}
} // namespace cheshire_cat

When the principal concern is reducing compile time dependencies the size (including indirect inclusions) of the header is more significant than that of the implementation file. However, in most cases, there is very little difference between the header files required by the different idioms - in our example they all have the same includes and the file lengths are as follows:

$ wc *.h | sort
   62    163   1580  cheshire_cat.h
   62    184   1677  interface_class.h
   65    162   1535  naive.h
   66    163   1554  delegation.h
   66    164   1605  envelope_letter.h
   94    285   2688  non_virtual_public_interface.h

The lack of variation is not surprising: all of the examples have eliminated the <map> header file and the only substantial difference is that Non-Virtual Public Interface declares twice as many functions (having both public and private versions of each).

It should be noted that only Interface Class and Non-Virtual Public Interface allow user implementation - the other idioms do not publish an implementation interface.

When our principal concern is that of simplifying the task of implementing the class then the size of the implementation file is most significant:

$ wc interface_class.cpp /
                  non_virtual_public_interface.cpp
   85   147  2013  interface_class.cpp
   89   151  2186  non_virtual_public_interface.cpp

There is no substantial difference in implementation cost between these approaches as they contain almost identical code.

// MAbstractBaseClass.cpp - implementation hiding
// example.
#include "interface_class.h"
#include <map>

// Declare the implementation class
namespace {
class telephone_list_implementation
   : public interface_class::telephone_list {
public:
  telephone_list_implementation(const std::string& name);
  virtual ~telephone_list_implementation();
private:
  virtual std::string get_name() const;
  virtual std::pair<bool, std::string>
  get_number(const std::string& person) const;
  virtual interface_class::telephone_list&
  add_entry(const std::string& name,
            const std::string& number);
  typedef std::map<std::string, std::string>
                                       dictionary_t;
  std::string name;
  dictionary_t dictionary;
};
} // anonymous namespace

// Implement the stubs for the base class
namespace interface_class {
telephone_list* telephone_list::create(
                          const std::string& name) {
  return new telephone_list_implementation(name);
}
} // namespace interface_class


// Implement the implementation class
namespace {
telephone_list_implementation::
telephone_list_implementation(const std::string& name)
   : name(name) {}

telephone_list_implementation::
~telephone_list_implementation() {}

std::string telephone_list_implementation::get_name() const
  { return name; }

std::pair<bool, std::string>
telephone_list_implementation::
get_number(const std::string& person) const {
  std::pair<bool, std::string> rc(false,
                                  std::string());
  dictionary_t::const_iterator i
      = dictionary.find(person);
  return(i != dictionary.end()) ? 
      std::make_pair(true, (*i).second) :
      std::make_pair(true, std::string());
}

interface_class::telephone_list&
telephone_list_implementation::
add_entry(const std::string& name, const std::string& number) {
  dictionary[name] = number;
  return *this;
}
} // anonymous namespace