This struct depends on a parameter ObjectType and provides a typedef, namely Type_, to the smart pointer class that points to objects of type ObjectType.

For instance, in bridge-example/PtrTraits.h we have:

namespace keyvalue {
namespace value {

template <typename ObjectType>
struct PtrTraits {
  typedef ::boost::shared_ptr<ObjectType> Type_;
};

} // namespace value
} // namespace keyvalue

This tells KeyValue that, as far as the bridge-example library is concerned, a pointer to ObjectType is a ::boost::shared_ptr<ObjectType>.

The general implementation of value::PtrTraits defines the smart pointer for each specific type of object. However, KeyValue's repository is a container for uniform storage, that is, stored pointers must have the same type. This situation is analogous to the classic example of polymorphism found in many C++ text books where a ::std::vector<Shape*> stores pointers to several types of shapes like Square, Circle, etc.

The specialization of value::PtrTraits for void tells KeyValue what is the type of pointer that the repository stores.

For instance, in bridge-example/PtrTraits.h we have:

namespace keyvalue {
namespace value {

template <>
struct PtrTraits<void> {
  typedef ::boost::shared_ptr< ::core::Polygon> Type_;
};

} // namespace value
} // namespace keyvalue

This means that KeyValue uniformly stores ::boost::shared_ptr<::core::Polygon>s. Hence, when a ::boost::shared_ptr<::core::Triangle> is given to KeyValue, it is cast to a ::boost::shared_ptr<::core::Polygon> before being stored. Later, when the bridge-example library asks for this object back, KeyValue does the oposite cast.

As we have seen, KeyValue casts pointers to specific types to pointers to the generic type and vice versa. The cast specific-to-generic is performed by a constructor and this point is explained in more details in Section 14.3. The generic-to-specific cast is performed by a template function which, essentially, has the following signature:

template <typename ObjectType>
value::PtrTraits<ObjectType>::Type_
dynamic_pointer_cast(const value::PtrTraits<void>::Type_& genericPointer);

The implementation must obey the semantics of the C++ built-in cast operator dynamic_cast. Specifically, if genericPointer does point to an ObjectType, then dynamic_pointer_cast returns a value::PtrTraits<ObjectType>::Type_ pointing to the same object. Otherwise, a NULL value::PtrTraits<ObjectType>::Type_ is returned.

This function is named after ::boost::dynamic_pointer_cast which satisfies the requirement describe above. Hence, for some boost smart pointers, ::boost::dynamic_pointer_cast is exactly what is needed. More precisely, PtrTraits.h should not implement dynamic_pointer_cast when the bridge library uses either ::boost::shared_ptr or ::boost::intrusive_ptr. In this case, KeyValue calls ::boost::dynamic_pointer_cast.

For example, bridge-example/PtrTraits.h sets the specific pointer to be ::boost::shared_ptr<ObjectType> and the generic pointer to be ::boost::shared_ptr<::core::Polygon>. Hence, it does not implement dynamic_pointer_cast. Notice that, in this case, the signature above reads

template <typename ObjectType>
::boost::shared_ptr<ObjectType>
dynamic_pointer_cast(const ::boost::shared_ptr<::core::Polygon>& genericPointer);

and matches the one in namespace ::boost whose implementation is #included into bridge-example/PtrTraits.h through boost/shared_ptr.hpp.

If you do need to implement dynamic_pointer_cast, then you can place it in one of the following namespaces:

Briefly, this macro can be uniformly set in this way:

#ifndef KEYVALUE_PTR_TRAITS_FILE
#define KEYVALUE_PTR_TRAITS_FILE __FILE__
#endif

Section 14.2 provides detailed information about this macro.

Given the popularity of boost libraries, KeyValue provides three examples of pointer traits files based on some boost smart pointers. Bridge developers can use any of them almost out of the box:

None of the files above (or their derivatives) needs to provide the implementation of dynamic_pointer_cast. Indeed, for the first two the implementation is provided by boost and for the third one the implementation is provided by KeyValue.