GeoData API - Internal programming documentation

Topics
  1. Topics
    2.
  2. Introduction
    3.
  3. "implicit sharing"
    4.
  4. How "implicit sharing" and derivation can work together
    5.
  5. serialization and deserialization
    6.

Introduction

The geodata-API should be used to contain easy and complex geographical data. It consists currently of three main types:

From each of those three multiple classes are derived. The first two are most interesting because of a feature seldomly found in APIs. Each derived class can be stored in its base class and can later be transformed back again. This means that the following code is possible: 

GeoDataPlacemark placemark;
GeoDataFeature placemarkAsFeature = placemark;
GeoDataPlacemark other = placemarkAsFeature;

return (placemark == other); // should return true
This feature is useful so that you can easily store classes which inherit GeoDataFeature in a QVector<GeoDataFeature> which would only be possible with Vectors normally. This is roughly the same as storing a QString in a QVariant (there are no GeoDataFeatures though that can be added at runtime). As an example: 

GeoDataPlacemark placemark;
QVector<GeoDataFeature> m_vector;

m_vector.append( placemark );
GeoDataFeature placeMarkAsFeature = m_vector.last();
GeoDataPlacemark other = placemarkAsFeature;

return (placemark == other); // should return true
This feature is the base for the GeoDataContainer classes and for the GeoDataMultiGeometry class.

"implicit sharing"

The GeoDataFeature and GeoDataGeometry classes do use implicit-sharing which means that after copying, only a shallow copy is done. Only after a write access to the data of the object (calling a non-const function) a copy of the whole data is done. This makes copying those data structures rather cheap, even if they contain a lot of other GeoDataObjects (as without writing there is not much more copying done than with a pointer.

As done already now, there is a private class which contains all the data members and gets accessed from the main classes accessor functions. This way you can keep binary compatibility over a long time without being restricted to the data members you chose in the beginning. When copying a d-pointer'ed class, you must put a new private class object on the stack though and copy the values from its origin. Implicit sharing now means, that in the moment of copying, you only copy the address of the private d pointer but you increment the reference counter of that object. After that there are two objects with the same private class object. If somebody tries to change something in one of those two objects, he must call a non-const function which in return will call a function called void detach(). This function copies the private object and decrements the reference counter. If one of the base objects gets deleted, it decrements the reference counter too as long as there are more objects connected to this private object. If the counter reaches 0 again, the private object gets deleted too. This is mostly hidden by QSharedData/QSharedDataPointer so that you don't have to worry about that.

The problems arise, when you try to derive from an implicitly shared class. The detach() function is not virtual in the current implementation of QVector and thus will not call the function from the derived class if changes occur through the interface of the base class. This leads to both GeoDataContainer and GeoDataMultiGeometry not inheriting QVector but rather rebuilding the interface.

How "implicit sharing" and derivation can work together

As described above, we can't use QSharedData directly if we want to use implicit sharing and derivation. Instead we do this on our own. Our Private classes are all contained in a *_p.h header file. They are derived from the private class of the base class (of the current class). Besides the data members, each private class contains a function void *copy() which returns a new copy of the private object. As needed an assignment operator may occur. The private classes also do contain a function virtual EnumFeatureId featureId() const / virtual EnumGeometryId geometryId() const but those are mostly a convenience solution to provide a way to check the type of your data when it is contained in the base class. Each of the base classes contains a void* pointer which holds the address of the private d pointer. Instead of having one d pointer per derivation step, we only have one per object. With a function p() which is contained by each derived class a pointer casted to the Private class of the class is returned. All of the private classes are derived from each other, in the same way as their connected classes. In the base class (in this case GeoDataFeature and GeoDataGeometry) a function void detach() is implemented which calls the void* copy() function of the private class. This way a copy will always result in the same type as the original, even though it might occur in a different wrapper (one of the type classes e.g.). Above mentioned reference counting is done in the detach function.

serialization and deserialization

The idea of a full serialization of GeoData-API is to use that for saving and reloading binary representations of GeoData-objects. For this to happen you simply need to call the pack() or unpack() function for the base GeoDataDocument providing a QDataStream. As the saved amount in space, is very small, Marble itself still uses a lossy implementation for that.