[轉] Policies/Binary Compatibility Issues With C++Policies/Binary Compatibility Issues With C+

<a href="http://techbase.kde.org/Policies/Binary_Compatibility_Issues_With_C%2B%2B#Definition">1 Definition</a>

<a href="http://techbase.kde.org/Policies/Binary_Compatibility_Issues_With_C%2B%2B#Note_about_ABI">2 Note about ABI</a>

<a href="http://techbase.kde.org/Policies/Binary_Compatibility_Issues_With_C%2B%2B#The_Do.27s_and_Don.27ts">3 The Do's and Don'ts</a>

<a href="http://techbase.kde.org/Policies/Binary_Compatibility_Issues_With_C%2B%2B#Techniques_for_Library_Programmers">4 Techniques for Library Programmers</a>

<a href="http://techbase.kde.org/Policies/Binary_Compatibility_Issues_With_C%2B%2B#Bitflags">4.1 Bitflags</a>

<a href="http://techbase.kde.org/Policies/Binary_Compatibility_Issues_With_C%2B%2B#Using_a_d-Pointer">4.2 Using a d-Pointer</a>

<a href="http://techbase.kde.org/Policies/Binary_Compatibility_Issues_With_C%2B%2B#Trouble_shooting">5 Trouble shooting</a>

<a href="http://techbase.kde.org/Policies/Binary_Compatibility_Issues_With_C%2B%2B#Adding_new_data_members_to_classes_without_d-pointer">5.1 Adding new data members to classes without d-pointer</a>

<a href="http://techbase.kde.org/Policies/Binary_Compatibility_Issues_With_C%2B%2B#Adding_a_reimplemented_virtual_function">5.2 Adding a reimplemented virtual function</a>

<a href="http://techbase.kde.org/Policies/Binary_Compatibility_Issues_With_C%2B%2B#Using_a_new_class">5.3 Using a new class</a>

<a href="http://techbase.kde.org/Policies/Binary_Compatibility_Issues_With_C%2B%2B#Adding_new_virtual_functions_to_leaf_classes">5.4 Adding new virtual functions to leaf classes</a>

<a href="http://techbase.kde.org/Policies/Binary_Compatibility_Issues_With_C%2B%2B#Using_signals_instead_of_virtual_functions">5.5 Using signals instead of virtual functions</a>

<a></a>

A library is <b>binary compatible</b>, if a program linked dynamically to a former version of the library continues running with newer versions of the library without the need to recompile.

If a program needs to be recompiled to run with a new version of library but doesn't require any further modifications, the library is <b>source compatible</b>.

Binary compatibility saves a lot of trouble. It makes it much easier to distribute software for a certain platform. Without ensuring binary compatibility between releases, people will be forced to provide statically linked binaries. Static binaries are bad because they

waste resources (especially memory)

don't allow the program to benefit from bugfixes or extensions in the libraries

In the KDE project, we will provide binary compatibility within the life-span of a major release for the core libraries (kdelibs kdepimlibs).

Some of the constraints specified here may not apply to a given compiler. The goal here is to list the most restrictive set of conditions when writing cross-platform C++ code, meant to be compiled with several different compilers.

This page is updated when new binary incompatibility issues are found.

You can...

add new non-virtual functions including signals and slots and constructors.

add a new enum to a class.

append new enumerators to an existing enum.

reimplement virtual functions defined in the primary base class hierarchy (that is, virtuals defined in the first non-virtual base class, or in that class's first non-virtual base class, and so forth) <b>if</b> it is safe that programs linked with the prior version of the library call the implementation in the base class rather than the new one. This is tricky and might be dangerous. Think twice before doing it. Alternatively see below for a workaround.

change an inline function or make an inline function non-inline <b>if</b> it is safe that programs linked with the prior version of the library call the old implementation. This is tricky and might be dangerous. Think twice before doing it.

remove private non-virtual functions <b>if</b> they are not called by any inline functions (and have never been).

remove private static members <b>if</b> they are not called by any inline functions (and have never been).

add new <b>static</b> data members.

change the default arguments of a method. It requires recompilation to use the actual new default argument values, though.

add new classes.

export a class that was not previously exported.

add or remove friend declarations to classes.

rename reserved member types

extend reserved bit fields, provided this doesn't cause the bit field to cross the boundary of its underlying type (8 bits for char &amp; bool, 16 bits for short, 32 bits for int, etc.)

add the Q_OBJECT macro to a class if the class already inherits from QObject

add a Q_PROPERTY, Q_ENUMS or Q_FLAGS macro as that only modifies the meta-object generated by moc and not the class itself

You cannot...

For existing classes:

For template classes:

For existing functions of any type:

remove it.

Remove the implementation of existing declared functions. The symbol comes from the implementation of the function, so this is effectively the function.

add an overload (BC, but not SC: makes &amp;func ambiguous), adding overloads to already overloaded functions is ok (any use of &amp;func already needed a cast).

change its signature. This includes:

changing the const/volatile qualifiers of the function

extending a function with another parameter, even if this parameter has a default argument. See below for a suggestion on how to avoid this issue

Exception: non-member functions declared with extern "C" can change parameter types (be very careful).

For virtual member functions:

Remove a virtual function, even if it is a reimplementation of a virtual function from the base class

For static non-private members or for non-static non-member public data:

Remove or unexport it

For non-static members:

add new, data members to an existing class.

change the order of non-static data members in a class.

change the type of the member, except for signedness

remove existing non-static data members from an existing class.

If you need to add extend/modify the parameter list of an existing function, you need to add a new function instead with the new parameters. In that case, you may want to add a short note that the two functions shall be merged with a default argument in later versions of the library:

You should...

In order to make a class to extend in the future you should follow these rules:

add d-pointer. See below.

add non-inline virtual destructor even if the body is empty.

reimplement event in widget classes, even if the body for the function is empty.

make all constructors non-inline.

write non-inline implementations of the copy constructor and assignment operator unless the class cannot be copied by value (e.g. classes inherited from QObject can't be)

The biggest problem when writing libraries is, that one cannot safely add data members since this would change the size and layout of every class, struct, or array containing objects of the type, including subclasses.

One exception are bitflags. If you use bitflags for enums or bools, you can safely round up to at least the next byte minus 1. A class with members

without breaking binary compatibility. Please round up to a maxmimum of 7 bits (or 15 if the bitfield was already larger than 8). Using the very last bit may cause problems on some compilers.

Bitflags and predefined reserved variables are nice, but far from being sufficient. This is where the d-pointer technique comes into play. The name "d-pointer" stems from Trolltech's Arnt Gulbrandsen, who first introduced the technique into Qt, making it one of the first C++ GUI libraries to maintain binary compatibility even between bigger release. The technique was quickly adapted as general programming pattern for the KDE libraries by everyone who saw it. It's a great trick to be able to add new private data members to a class without breaking binary compatibility.

<b>Remark:</b> The d-pointer pattern has been described many times in computer science history under various names, e.g. as pimpl, as handle/body or as cheshire cat. Google helps finding online papers for any of these, just add C++ to the search terms.

In your class definition for class Foo, define a forward declaration

and the d-pointer in the private section:

The FooPrivate class itself is purely defined in the class implementation file (usually *.cpp ), for example:

All you have to do now is to create the private data in your constructors or your init function with

and to delete it again in your destructor with

In most circumstances you will want to make the dpointer constant to catch situations where it's accidentally getting modified or copied over so you'd loose ownership of the private object and create a memory-leak:

This allows you to modify the object pointed to by d but not the value of the pointer after it has been initialized.

You may not want all member variables to live in the private data object, though. For very often used members, it's faster to put them directly in the class, since inline functions cannot access the d-pointer data. Also note that all data covered by the d-pointer is obviously private. For public or protected access, provide both a set and a get function. Example

The basic trick in your class implementation of class Foo is:

Create a private data class FooPrivate.

Create a static QHash&lt;Foo *, FooPrivate&gt;.

Note that some compilers/linkers (almost all, unfortunately) do not manage to create static objects in shared libraries. They simply forget to call the constructor. Therefore you should use the Q_GLOBAL_STATIC macro to create and access the object:

Now you can use the d-pointer in your class almost as simple as in the code before, just with a function call to d(this). For example:

Add a line to your destructor:

Do not forget to add a BCI remark, so that the hack can be removed in the next version of the library.

Do not forget to add a d-pointer to your next class.

As already explained, you can safely reimplement a virtual function defined in one of the base classes only if it is safe that the programs linked with the prior version call the implementation in the base class rather than the new one. This is because the compiler sometimes calls virtual functions directly if it can determine which one to call. For example, if you have

then B::foo() is called directly. If class B inherits from class A which implements foo() and B itself doesn't reimplement it, then C::foo() will in fact call A::foo(). If a newer version of the library adds B::foo(), C::foo() will call it only after a recompilation.

Another more common example is:

then the call to foo() will not use the virtual table. That means that if B::foo() didn't exist in the library but now does, code that was compiled with the earlier version will still call A::foo().

If you can't guarantee things will continue to work without a recompilation, move functionality from A::foo() to a new protected function A::foo2() and use this code:

All calls to A::foo() for objects of type B (or inherited) will result in calling B::foo(). The only case that will not work as expected are calls to A::foo() that explicitly specify A::foo(), but B::foo() calls A::foo2() instead and there should not be other places doing so.

A relatively simple method of "extending" a class can be writing a replacement class that will include also the new functionality (and that may inherit from the old class to reuse the code). This of course requires adapting and recompiling applications using the library, so it is not possible this way to fix or extend functionality of classes that are used by applications compiled against an older version of the library. However, especially with small and/or performance-critical classes it may be simpler to write them without making sure they'll be simple to extend in the future and if the need arises later write a new replacement class that will provide new features or better performance.

This technique is one of cases of using a new class that can help if there's a need to add new virtual functions to a class that should stay binary compatible and there is no class inheriting from it that should also stay binary compatible (i.e. all classes inheriting from it are in applications). In such case it's possible to add a new class inheriting from the original one that will add them. Applications using the new functionality will of course have to be modified to use the new class.

It is not possible to use this technique when there are other inherited classes that should also stay binary compatible because they'd have to inherit from the new class.

Function bar() will act like a virtual function, barslot() implements the actual functionality of it. Since signals have void return value, data must be returned using arguments. As there will be only one slot connected to the signal returning data from the slot this way will work without problems. Note that with Qt4 for this to work the connection type will have to be Qt::DirectConnection.

If an inherited class will want to re-implement the functionality of bar() it will have to provide its own slot:

Now B::barslot() will act like virtual reimplementation of A::bar(). Note that it is necessary to specify barslot() again as a slot in B and that in the constructor it is necessary to first disconnect and then connect again, that will disconnect A::barslot() and connect B::barslot() instead.

Note: the same can be accomplished by implementing a virtual slot.

本文轉自 zhenjing 部落格園部落格，原文連結：  http://www.cnblogs.com/zhenjing/archive/2011/03/15/Binary_Compatibility.html ，如需轉載請自行聯系原作者