wip

Author: jll63

include/boost/openmethod/compiler.hpp

@@ -1206,9 +1206,8 @@ void compiler<Registry>::write_global_data() {
     ++trace << rflush(4, Registry::dispatch_data.size()) << " " << gv_iter
             << " end\n";
 
-    if constexpr (Registry::template has_policy<extern_vptr>) {
-        Registry::template policy<extern_vptr>::register_vptrs(
-            classes.begin(), classes.end());
+    if constexpr (is_not_void<typename Registry::vptr>) {
+        Registry::vptr::register_vptrs(classes.begin(), classes.end());
     }
 }
 

include/boost/openmethod/default_registry.hpp

@@ -22,11 +22,7 @@ struct release_registry
           policies::stderr_output> {};
 
 struct debug_registry
-    : registry<
-          policies::std_rtti, policies::fast_perfect_hash,
-          policies::vptr_vector, policies::default_error_handler,
-          policies::runtime_checks, policies::stderr_output, policies::trace> {
-};
+    : release_registry::with<policies::runtime_checks, policies::trace> {};
 
 #ifdef NDEBUG
 using default_registry = release_registry;

include/boost/openmethod/policies/default_error_handler.hpp

@@ -13,6 +13,8 @@
 
 namespace boost::openmethod::policies {
 
+//! Calls a function via an indirection.
+
 struct default_error_handler : error_handler {
     using error_variant = std::variant<
         not_initialized_error, not_implemented_error, ambiguous_error,

include/boost/openmethod/policies/std_rtti.hpp

@@ -16,41 +16,79 @@
 
 namespace boost::openmethod::policies {
 
+//! `rtti` policy using standard RTTI.
+//!
+//! This implementation of `rtti` uses the standard C++ RTTI system. It is the
+//! default RTTI policy.
+//!
+
 struct std_rtti : rtti {
 #ifndef BOOST_NO_RTTI
-
     template<class Registry>
     struct fn {
+        //! Returns `true` if `Class` is polymorphic.
+        //!
+        //! A polymorphic class, as defined by the C++ standard, is a class that
+        //! contains at least one virtual function.
+        //!
+        //! @tparam Class A class.
+
         template<class Class>
         static constexpr bool is_polymorphic = std::is_polymorphic_v<Class>;
 
+        //! Returns the @ref type_id of `Class` is polymorphic.
+        //!
+        //! Returns the address of the `std::type_info` object for `Class`, cast
+        //! to `type_id`.
+        //!
+        //! @note `Class` is not necessarily a @e registered class. This
+        //! function is also called to acquire the type_id of non-virtual
+        //! parameters, library types, etc, for diagnostic and trace purposes.
+        //!
+        //! @tparam Class A class.
+
         template<class Class>
         static auto static_type() -> type_id {
             return &typeid(Class);
         }
 
+        //! Returns the @ref type_id of `obj`.
+        //!
+        //! Returns the address of the `std::type_info` object for `obj`, cast to `type_id`.
+
         template<class Class>
         static auto dynamic_type(const Class& obj) -> type_id {
             return &typeid(obj);
         }
 
+        //! Writes the demangled name of the class identified by `type` to
+        //! `stream`.
+
         template<typename Stream>
         static auto type_name(type_id type, Stream& stream) -> void {
             stream << boost::core::demangle(
                 reinterpret_cast<const std::type_info*>(type)->name());
         }
 
+        //! Returns the `std::type_index` of `type`.
+        //!
+        //! This function is required because C++ does *not* guarantee that
+        //! there is a single instance of `std::type_info` per type.
+
         static auto type_index(type_id type) -> std::type_index {
             return std::type_index(
                 *reinterpret_cast<const std::type_info*>(type));
         }
 
+        //! Casts `obj` to type `D`.
+        //!
+        //! Casts `obj` to `D` using `dynamic_cast`.
+
         template<typename D, typename B>
         static auto dynamic_cast_ref(B&& obj) -> D {
             return dynamic_cast<D>(obj);
         }
     };
-
 #endif
 };
 

include/boost/openmethod/policies/vptr_map.hpp

@@ -15,7 +15,7 @@ namespace boost::openmethod {
 namespace policies {
 
 template<class MapAdaptor = mp11::mp_quote<std::unordered_map>>
-class vptr_map : public extern_vptr {
+class vptr_map : public vptr {
   public:
     template<class Registry>
     struct fn {

include/boost/openmethod/policies/vptr_vector.hpp

@@ -25,7 +25,7 @@ inline std::vector<const vptr_type*> vptr_vector_indirect_vptrs;
 
 namespace policies {
 
-struct vptr_vector : extern_vptr {
+struct vptr_vector : vptr {
   public:
     template<class Registry>
     struct fn {
@@ -35,8 +35,9 @@ struct vptr_vector : extern_vptr {
             std::size_t size;
 
             if constexpr (Registry::template has_policy<type_hash>) {
-                auto [_, max_value] = Registry::template policy<type_hash>::initialize(
-                    first, last);
+                auto [_, max_value] =
+                    Registry::template policy<type_hash>::initialize(
+                        first, last);
                 size = max_value + 1;
             } else {
                 size = 0;

include/boost/openmethod/registry.hpp

@@ -13,6 +13,33 @@ namespace boost::openmethod {
 
 //! Namespace containing the policy framework.
 //!
+//! A registry contains a list of policies that control how some operations are
+//! performed. Policies fall into categories, depending on which subset of
+//! operations they control. Each category has a corresponding class:
+//!
+//! - @ref vptr: v-table pointer acquisition.
+//!
+//! - @ref rtti: type information acquisition and manipulation.
+//!
+//! - @ref type_hash: hashing of `type_id`s.
+//!
+//! - @ref error_handler: perform operations when errors are detected.
+//!
+//! - @ref output: output stream for logging and debugging.
+//!
+//! - @ref runtime_checks: detect and report common errors.
+//!
+//! - @ref trace: report how dispatch tables are built.
+//!
+//! - @ref n2216: handle ambiguities according to the N2216 proposal.
+//!
+//! The last three policy categories act like flags. They can appear in the
+//! registry's policy list, and enable existing blocks of code.
+//!
+//! The other categories cannot be used directly. They must be subclassed, and
+//! the subclass must contain a `template<class Registry> struct fn` that
+//! provides a set of static members that depends on the policy's category.
+//!
 //! A @e policy is a class that controls how some fundamental operations are
 //! performed by the library: type information acquisition (`rtti`), v-table
 //! pointer acquisition (`vptr`), error handling (`error_handler`), etc.
@@ -36,12 +63,10 @@ namespace policies {
 //! A @e rtti policy is responsible for acquiring and manipulating type
 //! information, dynamic casting, and identifying polymorphic classes.
 //!
-//! Class `rtti` provides a default implementation for some of these operations.
-//!
 //! @par Requirements
 //!
-//! A @e rtti policy must derive from class `rtti`, and contain a `fn<Registry>`
-//! class template with the following public static members:
+//! A subclass of `rtti` must contain a `fn<Registry>` class template with the
+//! following public static members:
 //!
 //! - `template<class Class> constexpr bool is_polymorphic`: evaluates to `true`
 //!   if `Class` is polymorphic.
@@ -50,16 +75,21 @@ namespace policies {
 //!   for `Class`.
 //!
 //! - `template<class Class> type_id dynamic_type(const Class& obj)`:
-//!   returns the type_id of an object's dynamic type.
-//!
-//! - `template<typename Stream> void type_name(type_id type, Stream&
-//!   stream)`: writes a description of `type` to `stream`.
+//!   returns the type_id of the @e dynamic type of `obj`.
 //!
-//! - `template<typename Stream> void type_name(type_id type, Stream&
-//!   stream)`: writes a description of `type` to `stream`.
+//! - `template<typename Stream> void type_name(type_id type, Stream& stream)`:
+//!   writes a description of `type` to `stream`. `rtti::fn` provides a default
+//!   implementation.
 //!
 //! - `/* unspecified */ type_index(type_id type)`: returns a @e unique
-//!   identifier for `type`.
+//!   identifier for `type`. `rtti::fn` provides a default implementation.
+//!
+//! The following functions is required only if casting from base to derived
+//! class cannot be performed using a `static_cast` for some of the registered
+//! classes:
+//!
+//! - `template<typename D, typename B> D dynamic_cast_ref(B&& obj)`: casts
+//!   `obj` to reference type `D`.
 
 struct rtti {
     using category = rtti;
@@ -88,7 +118,7 @@ struct rtti {
     };
 };
 
-//! RTTI policy base class with defered type id collection.
+//! RTTI policy base class for defered type id collection.
 //!
 //! Some custom RTTI systems rely on static constructors to assign type ids.
 //! OpenMethod itself relies on static constructors to register classes, methods
@@ -104,9 +134,10 @@ struct deferred_static_rtti : rtti {};
 //!
 //! @par Requirements
 //!
-//! A subclass of `error_handler` contains a `fn<Registry>` struct that provides
-//! one or more `error` static functions that take an error object. `error` must
-//! be callable with an instance of any subclass of `openmethod_error`.
+//! A subclass of `error_handler` must contain a `fn<Registry>` struct that
+//! provides one or more `error` static functions that take an error object.
+//! `error` must be callable with an instance of any subclass of
+//! `openmethod_error`.
 
 struct error_handler {
     using category = error_handler;
@@ -118,48 +149,50 @@ struct error_handler {
 //!
 //! @par Requirements
 //!
-//! A subclass of `error_handler` contains a `fn<Registry>` struct that provides
+//! A subclass of `type_hash` must contain a `fn<Registry>` struct that provides
 //! the following static member functions:
+//!
 //! - auto initialize(ForwardIterator first, ForwardIterator last) -> [min,
 //!   max]: initialize the hash table with the values in the [iter, last) range.
 //!   `*iter` is an object of an unspecified type that has two members,
 //!   `type_id_begin()` and `type_id_end()`, which return iterators to a range
 //!   of `type_id`s. `initialize` returns a pair with the minimum and maximum
 //!   hash values.
+//!
 //! - auto hash(type_id type) -> std::size_t: returns a hash value for `type`.
 //!   The value must be in the range returned by `initialize`.
+//!
 //! - void finalize(): releases any resources allocated by `initialize`. This
 //!   member is optional.
 
 struct type_hash {
     using category = type_hash;
 };
 
-/**
-    Acquires a v-table pointer for an object.
-
-    @par Requirements
-
-    Any implementation of this policy must provide a meta-function `fn` that
-    in the form of:
-
-    @code
-    template<class Registry>
-    struct fn {
-        template<class Class> static auto dynamic_vptr(const Class& arg) -> const vptr_type&;
-    };
-    @endcode
-
-    @see policies::vptr_vector::fn::dynamic_vptr for an example.
-
-*/
+//! Acquires a v-table pointer for an object.
+//!
+//! @par Requirements
+//!
+//! A subclass of `type_hash` must contain a `fn<Registry>` struct that provides
+//! the following static member functions:
+//!
+//! - auto initialize(ForwardIterator first, ForwardIterator last) -> [min,
+//!   max]: initialize the hash table with the values in the [iter, last) range.
+//!   `*iter` is an object of an unspecified type that has two members,
+//!   `type_id_begin()` and `type_id_end()`, which return iterators to a range
+//!   of `type_id`s. `initialize` returns a pair with the minimum and maximum
+//!   hash values.
+//!
+//! - auto hash(type_id type) -> std::size_t: returns a hash value for `type`.
+//!   The value must be in the range returned by `initialize`.
+//!
+//! - void finalize(): releases any resources allocated by `initialize`. This
+//!   member is optional.
 
 struct vptr {
     using category = vptr;
 };
 
-struct extern_vptr : vptr {};
-
 struct indirect_vptr {
     using category = indirect_vptr;
     template<class Registry>
@@ -324,6 +357,7 @@ struct registry : detail::registry_base {
     static constexpr auto indirect_vptr = has_policy<policies::indirect_vptr>;
 
     using rtti = policy<policies::rtti>;
+    using vptr = policy<policies::vptr>;
     using error_handler = policy<policies::error_handler>;
     using output = policy<policies::output>;
     using trace = policy<policies::trace>;

test/test_intrusive.cpp

@@ -9,9 +9,8 @@
 #include <boost/openmethod/default_registry.hpp>
 
 namespace bom = boost::openmethod;
-struct test_registry
-    : bom::default_registry::without<
-          bom::policies::extern_vptr, bom::policies::type_hash> {};
+struct test_registry : bom::default_registry::without<
+                           bom::policies::vptr, bom::policies::type_hash> {};
 
 #define BOOST_OPENMETHOD_DEFAULT_REGISTRY test_registry