doc

include/yorel/yomm2/policy.hpp

@@ -332,7 +332,7 @@ struct yOMM2_API_gcc vptr_vector : virtual external_vptr {
     }
 
     template<class Class>
-    static auto dynamic_vptr(const Class& arg) {
+    static const std::uintptr_t* dynamic_vptr(const Class& arg) {
         auto index = Policy::dynamic_type(arg);
 
         if constexpr (has_facet<Policy, type_hash>) {

reference.in/method.cpp

@@ -20,7 +20,7 @@ definitions can be added with the [`method::add_function`](#add_function) and
 
 At least one of the `Args` parameter types must be decorated with ->virtual_.
 
-`Key` is a user-suplied type that makes it possible to have distinct methods
+`Key` is a user-supplied type that makes it possible to have distinct methods
 with the same signature.
 
 ### member functions

reference.in/type_hash.md

@@ -0,0 +1,4 @@
+<sub>/ ->home / ->reference </sub>
+
+entry: yorel::yomm2::policy::type_hash
+headers: yorel/yomm2/policy.hpp, yorel/yomm2/keywords.hpp

reference.in/vptr.cpp

@@ -6,8 +6,6 @@
 
 entry: yorel::yomm2::policy::vptr
 entry: yorel::yomm2::policy::external_vptr
-entry: yorel::yomm2::policy::vptr_vector
-entry: yorel::yomm2::policy::vptr_map
 headers: yorel/yomm2/policy.hpp, yorel/yomm2/keywords.hpp
 
 ---
@@ -43,22 +41,46 @@ facet is optional.
 `external_vptr` is a sub-category of `facet`. If present, it provides a
 `register_vptrs` function, called by `update`.
 
-`vptr_vector` is an implementation of `external_vptr` that stores vptrs in a
-`std::vector`. If the policy contains a `type_hash` facet, it is used to convert
-the `type_id` to an index in the vector; otherwise, the `type_id` is used as the
-index.
-
-The default policy uses ->`std_rtti`, ->`simple_perfect_hash` and `vptr_vector`
-to implement efficient method dispatch. Calling a method with a single virtual
-parameter takes only ~33% more time than calling a native virtual function call.
-
-`vptr_map` (also a `external_vptr`) stores vptrs in a `std::unordered_map` keyed
-by the `type_id`. Method dispatch is slower than `vptr_vector` with
-`simple_perfect_hash` (75% slower than native virtual function). However,
-`vptr_map` has some advantages: `simple_perfect_hash` takes more time to
-initialize. It also sacrifices memory space for speed, as it uses a hash
-function that is not suitable for perfect _and_ minimal hashing. Using
-`virtual_ptr`s extensively can mitigate the speed disadvantage of `vptr_map`.
+### Requirements for implementations of `vptr`
+
+An implementation of `vptr` must provide the following static function template:
+
+|                               |                                                 |
+| ----------------------------- | ----------------------------------------------- |
+| [dynamic_vptr](#dynamic_vptr) | return the address of the v-table for an object |
+
+
+### dynamic_vptr
+```c++
+struct vptr_facet {
+    template<class Class>
+    static const std::uintptr_t* dynamic_vptr(const Class& arg);
+};
+```
+
+### Requirements for implementations of `external_vptr`
+
+In addition to the requirements for `vptr`, an implementation of `external_vptr`
+must provide the following static function template:
+
+|                                   |                                         |
+| --------------------------------- | --------------------------------------- |
+| [register_vptrs](#register_vptrs) | implementation dependent initialization |
+
+
+### register_vptrs
+
+```c++
+struct external_vptr_facet {
+    template<typename ForwardIterator>
+    static void register_vptrs(ForwardIterator first, ForwardIterator last)};
+```
+
+This function is called by `update`, after the v-tables have been set up, with a
+range of pairs. The first member is a `type_index` of a registered class; the
+second member is a pointer to a pointer to the v-table for that class. The vptrs
+(`**iter.second`) change after a call to `update`, as the v-tables are rebuilt.
+However, the pointers to the vptrs (`*iter.second`) are stable across updates.
 
 ## Example
 

reference.in/vptr_vector.md

@@ -0,0 +1,58 @@
+<sub>/ ->home / ->reference </sub>
+
+entry: yorel::yomm2::policy::vptr_vector
+headers: yorel/yomm2/policy.hpp, yorel/yomm2/core.hpp, yorel/yomm2/keywords.hpp
+
+---
+```
+template<class Policy>
+struct vptr_vector;
+```
+---
+
+`vptr_vector` is an implementation of [`external_vptr`](external_vptr.md) that stores pointers to
+v-tables in a `std::vector`. If the policy contains a ->`type_hash` facet, it is
+used to convert the ->`type_id` to an index in the vector; otherwise, the
+`type_id` is used as the index.
+
+The default policy uses ->`std_rtti`, ->`simple_perfect_hash` and `vptr_vector`
+to implement efficient method dispatch. Calling a method with a single virtual
+parameter takes only ~33% more time than calling a native virtual function call.
+
+### Template parameters
+
+**Policy** - the policy containing the facet.
+
+### static member functions
+|                                   |                                                    |
+| --------------------------------- | -------------------------------------------------- |
+| [dynamic_vptr](#dynamic_vptr)     | return the address of the v-table for an object    |
+| [register_vptrs](#register_vptrs) | store the vptrs, initialize `type_hash` if present |
+
+### dynamic_vptr
+
+```c++
+template<class Policy>
+template<class Class>
+const std::uintptr_t* vptr_vector<Policy>::dynamic_vptr(const Class& object);
+```
+
+Return a pointer to the v-table for `object`.
+
+Call `Policy::dynamic_type` for `object`. If `Policy` contains a `type_hash`
+facet, use it to convert the resulting `type_id` to an index; otherwise, use the
+`type_id` as the index.
+
+### register_vptrs
+
+```c++
+template<class Policy>
+template<typename ForwardIterator>
+void vptr_vector<Policy>::register_vptrs(ForwardIterator first, ForwardIterator last);
+```
+
+If `Policy` contains a `type_hash` facet, call its `type_hash_initialize`
+function.
+
+Store the pointers to the v-tables in a vector, indexed by the (possibly hashed)
+`type_id`s.

reference/method.md

@@ -20,7 +20,7 @@ definitions can be added with the [`method::add_function`](#add_function) and
 
 At least one of the `Args` parameter types must be decorated with [virtual_](/reference/virtual_.md).
 
-`Key` is a user-suplied type that makes it possible to have distinct methods
+`Key` is a user-supplied type that makes it possible to have distinct methods
 with the same signature.
 
 ### member functions

reference/vptr.md

@@ -3,8 +3,6 @@
 
 **yorel::yomm2::policy::vptr**<br>
 **yorel::yomm2::policy::external_vptr**<br>
-**yorel::yomm2::policy::vptr_vector**<br>
-**yorel::yomm2::policy::vptr_map**<br>
 <sub>defined in <yorel/yomm2/policy.hpp>, also provided by<yorel/yomm2/keywords.hpp></sub>
 
 ---
@@ -40,15 +38,6 @@ facet is optional.
 `external_vptr` is a sub-category of `facet`. If present, it provides a
 `register_vptrs` function, called by `update`.
 
-`vptr_vector` is an implementation of `external_vptr` that stores vptrs in a
-`std::vector`. If the policy contains a `type_hash` facet, it is used to convert
-the `type_id` to an index in the vector; otherwise, the `type_id` is used as the
-index.
-
-The default policy uses ->`std_rtti`, ->`simple_perfect_hash` and `vptr_vector`
-to implement efficient method dispatch. Calling a method with a single virtual
-parameter takes only ~33% more time than calling a native virtual function call.
-
 `vptr_map` (also a `external_vptr`) stores vptrs in a `std::unordered_map` keyed
 by the `type_id`. Method dispatch is slower than `vptr_vector` with
 `simple_perfect_hash` (75% slower than native virtual function). However,
@@ -57,6 +46,47 @@ initialize. It also sacrifices memory space for speed, as it uses a hash
 function that is not suitable for perfect _and_ minimal hashing. Using
 `virtual_ptr`s extensively can mitigate the speed disadvantage of `vptr_map`.
 
+### Requirements for implementations of `vptr`
+
+An implementation of `vptr` must provide the following static function template:
+
+|                               |                                                 |
+| ----------------------------- | ----------------------------------------------- |
+| [dynamic_vptr](#dynamic_vptr) | return the address of the v-table for an object |
+
+
+### dynamic_vptr
+```c++
+struct vptr_facet {
+    template<class Class>
+    static const std::uintptr_t* dynamic_vptr(const Class& arg);
+};
+```
+
+### Requirements for implementations of `external_vptr`
+
+In addition to the requirements for `vptr`, an implementation of `external_vptr`
+must provide the following static function template:
+
+|                                   |                                         |
+| --------------------------------- | --------------------------------------- |
+| [register_vptrs](#register_vptrs) | implementation dependent initialization |
+
+
+### register_vptrs
+
+```c++
+struct external_vptr_facet {
+    template<typename ForwardIterator>
+    static void register_vptrs(ForwardIterator first, ForwardIterator last)};
+```
+
+This function is called by `update`, after the v-tables have been set up, with a
+range of pairs. The first member is a `type_index` of a registered class; the
+second member is a pointer to a pointer to the v-table for that class. The vptrs
+(`**iter.second`) change after a call to `update`, as the v-tables are rebuilt.
+However, the pointers to the vptrs (`*iter.second`) are stable across updates.
+
 ## Example
 
 Virtual functions are sometimes criticized for having a non-zero overhead.

reference/vptr_vector.md

@@ -0,0 +1,58 @@
+<sub>/ [home](/reference//README.md) / [reference](/reference//reference/README.md) </sub>
+
+**yorel::yomm2::policy::vptr_vector**<br>
+<sub>defined in <yorel/yomm2/policy.hpp>, also provided by<yorel/yomm2/core.hpp>, <yorel/yomm2/keywords.hpp></sub>
+
+---
+```
+template<class Policy>
+struct vptr_vector;
+```
+---
+
+`vptr_vector` is an implementation of [`external_vptr`](external_vptr.md) that stores pointers to
+v-tables in a `std::vector`. If the policy contains a [`type_hash`](/reference/type_hash.md) facet, it is
+used to convert the ->`type_id` to an index in the vector; otherwise, the
+`type_id` is used as the index.
+
+The default policy uses ->`std_rtti`, ->`simple_perfect_hash` and `vptr_vector`
+to implement efficient method dispatch. Calling a method with a single virtual
+parameter takes only ~33% more time than calling a native virtual function call.
+
+### Template parameters
+
+**Policy** - the policy containing the facet.
+
+### static member functions
+|                                   |                                                    |
+| --------------------------------- | -------------------------------------------------- |
+| [dynamic_vptr](#dynamic_vptr)     | return the address of the v-table for an object    |
+| [register_vptrs](#register_vptrs) | store the vptrs, initialize `type_hash` if present |
+
+### dynamic_vptr
+
+```c++
+template<class Policy>
+template<class Class>
+const std::uintptr_t* vptr_vector<Policy>::dynamic_vptr(const Class& object);
+```
+
+Return a pointer to the v-table for `object`.
+
+Call `Policy::dynamic_type` for `object`. If `Policy` contains a `type_hash`
+facet, use it to convert the resulting `type_id` to an index; otherwise, use the
+`type_id` as the index.
+
+### register_vptrs
+
+```c++
+template<class Policy>
+template<typename ForwardIterator>
+void vptr_vector<Policy>::register_vptrs(ForwardIterator first, ForwardIterator last);
+```
+
+If `Policy` contains a `type_hash` facet, call its `type_hash_initialize`
+function.
+
+Store the pointers to the v-tables in a vector, indexed by the (possibly hashed)
+`type_id`s.