Suppose I have class like this (simplified):
class Foo_p;
class Foo
{
private:
Foo_p *p;
public:
Foo();
/* methods, etc... */
};
This class is a part of an API.
The Foo_p is all the private parts of the class, which are not
declared in the class Foo itself as usual, but rather in a separate forward-declared class that is only used by the underlying implementation not visible on the outside.
I've seen this pattern used in a couple of projects, is there a name for it?
Also, how do I use it properly (e.g. exception safety, etc.)? Where should the actual implementation go? In class Foo, as usual, only using Foo_p for storage of data, or in the Foo_p class with Foo being just a wrapper?
That is the pimpl idiom
See
Handle/Body Idiom - close cousin and the seminal idea for pimpl EDIT Found an online copy of this original James Coplien talk
GotW #100: Compilation Firewalls (Difficulty: 6/10)
GotW #101: Compilation Firewalls, Part 2 (Difficulty: 8/10) for the most recent on this
This is known is PIMPL. private/pointer-to-private implementation. The class, Foo_p, your class would have been is implemented privately and accessed through a pointer to it so that rather than displaying the true class to clients, they only get to see the public interface you chose to expose. It essentially abstracts away from the header the vestiges of implementation detail present in the protected and private members.
I've found it unwieldy in VC++- it breaks code completion. It is useful if you are very sure of your implementation and don't want the private and protected members on display in the header.
I put the actual implementation of class Foo_p in the cpp file for class Foo, although this may have been the cause of the code-completion breaking, at least I don't have to run the risk of the class being reused by inclusion of its header.
It's a d-pointer which is a type of opaque-pointer. Similar to the PIMPL idiom.
One type of opaque pointer commonly used in C++ class declarations is
the d-pointer. The d-pointer is the only private data member of the
class and points to an instance of a struct. Named by Arnt Gulbrandsen
of Trolltech, this method allows class declarations to omit private
data members, except for the d-pointer itself.[6] The result is that
more of the class' implementation is hidden from view, that adding new
data members to the private struct does not affect binary
compatibility, and that the header file containing the class
declaration only has to #include those other files that are needed for
the class interface, rather than for its implementation. As a side
benefit, compiles are faster because the header file changes less
often. The d-pointer is heavily used in the Qt and KDE libraries.
https://en.wikipedia.org/wiki/Opaque_pointer#C.2B.2B
Related
Bear with me here.
I am trying to figure out at what point do you draw the line regarding putting helper methods in anon vs. detail namespace vs. private vs. creating pimpl or friend class.
Here's my take.. Please let me know your thoughts.
So, if I have
foo.hpp
foo.cpp
and I have some free function bar that do not access any data members in foo, and furthermore no clients need to know those free functions and only foo.cpp's method need them just directly put them in anon namespace in foo.cpp and be done with it.
If however, bar needs access to foo's data members we can make bar private method of foo. But that means that even though foo's client don't really care about bar, everytime bar changes, we have a recompilation.
(This part I am a bit fuzzy):
However, atleast using a detail namespace in this case, helps readers of foo.hpp not to bother looking at bar, since they really don't need to know it. Is this the general usecase for detail namespace convention?
Now, if we have bunch of bar_1, bar_2...bar_n and they kind of relate together and they need access to data members , I can make a friend class baz to foo , and put the bars there.
If however, I am really concerned about compilation time and hiding the interface i can resort to pimpl (again very fuzzy on this part, usually if I see this, alarm bell goes off and tells me something is off in the design).
Your thoughts...
As someone commented earlier, it would be better to provide an example of code with your question as the concepts you are describing are pretty abstract and complex.
Here is my take on the items you want to know more about: Private methods, Private implementation, Unnamed namespace non-member function, non-member function in a "named" namespace and friend non-member function.
Private Methods: First you will have to declare those in your class declaration so their prototype will be publicly visible even if nobody outside of your class can call it. This is a little non-sensical. You should use those methods in 2 kind of situations:
You need to access something that is private to your class in the implementation of this method.
You are implementing a virtual method using the NVI idiom.
Private Implementation: You should use this to hide the implementation details of your class. AKA its data members. One thing I do often is to forward declare my pImpl type in my class header file and make my class friend of the private implementation class in the cpp file.
Unnamed namespace non-member function: These are more or less equivalent to non-member functions declared with the static keyword in your implementation file. You should shoot for those as much as possible. A good rule of thumb is that all non-virtual private methods should be implementable as non-friend, non-member functions declared un the unnamed namespace. This has the advantage that it forces you to use the public interface of your class in the implementation of such functions. One important warning: Never ever use the unnamed namespace in a header file. (.h or .hpp) If you do, every prototype in those files will have a unique symbol each time that file in included. This can rapidly result in a symbol mess.
Non-member non-friend function within a namespace: Most of the time, you will use these functions when you want to add services to your class or provide helper functions that are not bound to a class. The advantage of these functions is that they use only the public interface of your classes. One good example of a good usage of these methods is when you implement operators for your class.
Let's say you have class "A" and class "B". and you want to add an instance of A to an instance of B. The transitivity rule says that you could also add B to A with the same result. If you make the operator+ non member, you don't have to modify either classes to implement this feature. If you do it as a public method you will have to do it in both classes. I would recommend you Scott Meyers "Effective C++" if you want to know more on that subject.
Friend non-member functions: You should avoid these as much as possible. The reason being that their implementation rely on private details of your class. Why else would you have made them friend? It is accepted that the private implementation details of a class can change at any time which may break your function or worse: Make it behave in a different way than intended.
So there you have it, use the private method when you have virtual methods to declare through the NVI idiom, put your data members in Private implementations, declare all your non-virtual private methods in your implementation file under the unnamed namespace, declare public services as non-member non-friend functions as much as possible and do not use any friend non-member functions.
First things first: I know thats it's quite probable that my question is based on a general missunderstanding, but I hope I can make my point clear to you.
I know that when putting code into diffrent files in C++ we have do create a .h (for Definitions) and a .cpp (for implementations).
When writing a class-library for example I have to put a definitioj of both, private and public members in the header. But what to do if - for some reason - I want to hide the private things from the user?
Thanks!
You use the Pimpl idiom. Pimpl stands for "pointer to implementation". Basically, you don't store the implementation details in the class. Instead you store an opaque pointer to implementation as such:
class MyClass
{
public:
//public functions here
private:
class Impl; //no definition, opaque
Impl* pimpl;
};
And then you go on to define your MyClass::Impl class in the .cpp file only, because only the function definitions need it.
The PIMPL idiom has the additional benefit that as long as the interface of the class does not change, any changes made to the implementation do not require the recompilation of class clients.
You can't. This is one of the drawbacks of C++: things marked private are still part of the class declaration and so will be present in the header.
If you really want to hide the functionality, then using the pImpl Idiom can help. Personally though I prefer to live with the drawback as using the idiom can cause other problems such as your class no longer being trivially copyable.
See Why should the "PIMPL" idiom be used?
While looking over some code, I ran into the following:
.h file
class ExampleClass
{
public:
// methods, etc
private:
class AnotherExampleClass* ptrToClass;
}
.cpp file
class AnotherExampleClass
{
// methods, etc
}
// AnotherExampleClass and ExampleClass implemented
Is this a pattern or something beneficial when working in c++? Since the class is not broken out into another file, does this work flow promote faster compilation times?
or is this just the style this developer?
This is variously known as the pImpl Idiom, Cheshire cat technique, or Compilation firewall.
Benefits:
Changing private member variables of a class does not require recompiling classes that depend on it, thus make times are faster, and
the FragileBinaryInterfaceProblem is reduced.
The header file does not need to #include classes that are used 'by value' in private member variables, thus compile times are faster.
This is sorta like the way SmallTalk automatically handles classes... more pure encapsulation.
Drawbacks:
More work for the implementor.
Doesn't work for 'protected' members where access by subclasses is required.
Somewhat harder to read code, since some information is no longer in the header file.
Run-time performance is slightly compromised due to the pointer indirection, especially if function calls are virtual (branch prediction for indirect branches is generally poor).
Herb Sutter's "Exceptional C++" books also go into useful detail on the appropriate usage of this technique.
The most common example would be when using the PIMPL pattern or similar techniques. Still, there are other uses as well. Typically, the distinction .hpp/.cpp in C++ is rather (or, at least can be) one of public interface versus private implementation. If a type is only used as part of the implementation, then that's a good reason not to export it in the header file.
Apart from possibly being an implementation of the PIMPL idiom, here are two more possible reason to do this:
Objects in C++ cannot modify their this pointer. As a consequence, they cannot change type in mid-usage. However, ptrToClass can change, allowing an implementation to delete itself and to replace itself with another instance of another subclass of AnotherExampleClass.
If the implementation of AnotherExampleClass depends on some template parameters, but the interface of ExampleClass does not, it is possible to use a template derived from AnotherExampleClass to provide the implementation. This hides part of the necessary, yet internal type information from the user of the interface class.
In my company's C++ codebase I see a lot of classes defined like this:
// FooApi.h
class FooApi {
public:
virtual void someFunction() = 0;
virtual void someOtherFunction() = 0;
// etc.
};
// Foo.h
class Foo : public FooApi {
public:
virtual void someFunction();
virtual void someOtherFunction();
};
Foo is this only class that inherits from FooApi and functions that take or return pointers to Foo objects use FooApi * instead. It seems to mainly be used for singleton classes.
Is this a common, named way to write C++ code? And what is the point in it? I don't see how having a separate, pure abstract class that just defines the class's interface is useful.
Edit[0]: Sorry, just to clarify, there is only one class deriving from FooApi and no intention to add others later.
Edit[1]: I understand the point of abstraction and inheritance in general but not this particular usage of inheritance.
The only reason that I can see why they would do this is for encapsulation purposes. The point here is that most other code in the code-base only requires inclusion of the "FooApi.h" / "BarApi.h" / "QuxxApi.h" headers. Only the parts of the code that create Foo objects would actually need to include the "Foo.h" header (and link with the object-file containing the definition of the class' functions). And for singletons, the only place where you would normally create a Foo object is in the "Foo.cpp" file (e.g., as a local static variable within a static member function of the Foo class, or something similar).
This is similar to using forward-declarations to avoid including the header that contains the actual class declaration. But when using forward-declarations, you still need to eventually include the header in order to be able to call any of the member functions. But when using this "abstract + actual" class pattern, you don't even need to include the "Foo.h" header to be able to call the member functions of FooApi.
In other words, this pattern provides very strong encapsulation of the Foo class' implementation (and complete declaration). You get roughly the same benefits as from using the Compiler Firewall idiom. Here is another interesting read on those issues.
I don't know the name of that pattern. It is not very common compared to the other two patterns I just mentioned (compiler firewall and forward declarations). This is probably because this method has quite a bit more run-time overhead than the other two methods.
This is for if the code is later added on to. Lets say NewFoo also extends/implements FooApi. All the current infrastructure will work with both Foo and NewFoo.
It's likely that this has been done for the same reason that pImpl ("pointer to implementation idiom", sometimes called "private implementation idiom") is used - to keep private implementation details out of the header, which means common build systems like make that use file timestamps to trigger code recompilation will not rebuild client code when only implementation has changed. Instead, the object containing the new implementation can be linked against existing client object(s), and indeed if the implementation is distributed in a shared object (aka dynamic link library / DLL) the client application can pick up a changed implementation library the next time it runs (or does a dlopen() or equivalent if it's linking at run-time). As well as facilitating distribution of updated implementation, it can reduce rebuilding times allowing a faster edit/test/edit/... cycle.
The cost of this is that implementations have to be accessed through out-of-line virtual dispatch, so there's a performance hit. This is typically insignificant, but if a trivial function like a get-int-member is called millions of times in a performance critical loop it may be of interest - each call can easily be an order of magnitude slower than inlined member access.
What's the "name" for it? Well, if you say you're using an "interface" most people will get the general idea. That term's a bit vague in C++, as some people use it whenever a base class has virtual methods, others expect that the base will be abstract, lack data members and/or private member functions and/or function definitions (other than the virtual destructor's). Expectations around the term "interface" are sometimes - for better or worse - influenced by Java's language keyword, which restricts the interface class to being abstract, containing no static methods or function definitions, with all functions being public, and only const final data members.
None of the well-known Gang of Four Design Patterns correspond to the usage you cite, and while doubtless lots of people have published (web- or otherwise) corresponding "patterns", they're probably not widely enough used (with the same meaning!) to be less confusing than "interface".
FooApi is a virtual base class, it provides the interface for concrete implementations (Foo).
The point is you can implement functionality in terms of FooApi and create multiple implementations that satisfy its interface and still work with your functionality. You see some advantage when you have multiple descendants - the functionality can work with multiple implementations. One might implement a different type of Foo or for a different platform.
Re-reading my answer, I don't think I should talk about OO ever again.
class MyClassPrivate
{
//My members.
};
//and then
class MyClass {
private:
MyClassPrivate* const d;
};
What is the reason of using this 'pattern'? How it's correctly called?
This is called "Pointer to implementation" or "pimpl". See http://en.wikibooks.org/wiki/C++_Programming/Idioms#Pointer_To_Implementation_.28pImpl.29
When you use this pattern you would forward declare the implementation class, and declare the body elsewhere, i.e.:
// header
class MyClassPrivate;
class MyClass {
public:
MyClass();
~MyClass();
private:
MyClassPrivate* const d;
};
// cpp
class MyClassPrivate {
};
MyClass::MyClass() : d(new MyClassPrivate) {}
MyClass::~MyClass() { delete d; }
The advantage of doing this is that the implementation of MyClass is not exposed to other users of MyClass. If the implementation changes, the other users of MyClass does not need to be recompiled. Any header files that has to be included for members also need not be exposed, which improves compilation time.
The most usage is Pimlp idiom.
Why should the “PIMPL” idiom be used?
Pimpl idiom
The Pimpl
The Pimpl idiom describes a way for making your header files
impervious to change. You often hear advices like "Avoid change your
public interface!" So you can modify your private interface, but how
can you avoid recompilation when your header file defines the private
methods. This is what the Pimpl does – Reduce compilation damages when
your private interface changes[3].
From Here:
Benefits:
Changing private member variables of a class does not require recompiling classes that depend on it, thus make times are faster, and the FragileBinaryInterfaceProblem is reduced.
The header file does not need to #include classes that are used 'by value' in private member variables, thus compile times are faster.
This is sorta like the way SmallTalk automatically handles classes... more pure encapsulation.
Drawbacks:
More work for the implementer.
Doesn't work for 'protected' members where access by subclasses is required.
Somewhat harder to read code, since some information is no longer in the header file.
Run-time performance is slightly compromised due to the pointer indirection, especially if function calls are virtual (branch prediction for indirect branches is generally poor).
How to do it:
Put all the private member variables into a struct.
Put the struct definition in the .cpp file.
In the header file, put only the ForwardDeclaration of the struct.
In the class definition, declare a (smart) pointer to the struct as the only private member variable.
The constructors for the class need to create the struct.
The destructor of the class needs to destroy the struct (possibly implicitly due to use of a smart pointer).
The assignment operator and CopyConstructor need to copy the struct appropriately or else be disabled.
You can use this for the PIMPL idiom, when you want to separate interface from iplementation.
Many design patterns use a "pointer" to a private attribute as well, such as the Strategy Pattern. This patterns allows you to select a different algorithm at run-time.
Also, if you make the manipulation of your data adhere to the same interface, you can encapsulate the data in a Private Class, make this class a part of a hierarchy and switch between different data implementations during run time (or compile time for that matter :)).
A good example of this is a geometrical class that holds data on polygons. Each Polygon provides access to the points, you can also delete the Polygon edge and do various other topological operations. If you provide an abstract base class for the Polygon class with the methods such as deletePoint, addPoint, swapEdge, you can test different Polygon implementations.
You may define a polygon as a list of Point types directly, and store the points in different contaienrs (list or vector). The Polygon class may be defined via indirect addressing, where the polygon is actually a list of IDs to the list of points (I am talking about lists in the general sense). This way, you can test different algorithms of the PolygonGeometry class and see how they work with differtn Polygon implementations.
There is a design principle behind this: Prefer Composition to Inheritance. Whenever you are using Composition and you are relying on the type to be deterimined at run-time, you will have a private attribute pointer.