Skip to content

Commit

Permalink
more renames and doc
Browse files Browse the repository at this point in the history
  • Loading branch information
@jll63
jll63 committed Feb 4, 2024
1 parent 5d550c8 commit c46a8c3
Show file tree
Hide file tree
Showing 8 changed files with 106 additions and 74 deletions.
28 changes: 14 additions & 14 deletions include/yorel/yomm2/policy.hpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -293,7 +293,7 @@ template<class Policy, class Facet>
constexpr bool has_facet = Policy::template has_facet<Facet>;

template<class Policy>
struct yOMM2_API_gcc external_vptr_vector : virtual external_vptr {
struct yOMM2_API_gcc vptr_vector : virtual external_vptr {
static std::vector<const std::uintptr_t*> vptrs;

template<typename ForwardIterator>
Expand All @@ -303,7 +303,7 @@ struct yOMM2_API_gcc external_vptr_vector : virtual external_vptr {
size_t size;

if constexpr (has_facet<Policy, type_hash>) {
size = Policy::hash_type_initialize(first, last);
size = Policy::type_hash_initialize(first, last);
} else {
size = 1 + std::max_element(first, last, [](auto a, auto b) {
return a < b;
Expand Down Expand Up @@ -344,10 +344,10 @@ struct yOMM2_API_gcc external_vptr_vector : virtual external_vptr {
};

template<class Policy>
std::vector<const std::uintptr_t*> external_vptr_vector<Policy>::vptrs;
std::vector<const std::uintptr_t*> vptr_vector<Policy>::vptrs;

template<class Policy>
struct yOMM2_API_gcc external_vptr_map : virtual external_vptr {
struct yOMM2_API_gcc vptr_map : virtual external_vptr {
static std::unordered_map<type_id, const std::uintptr_t*> vptrs;

static void resize_vptrs(size_t n) {
Expand All @@ -372,7 +372,7 @@ struct yOMM2_API_gcc external_vptr_map : virtual external_vptr {

template<class Policy>
std::unordered_map<type_id, const std::uintptr_t*>
external_vptr_map<Policy>::vptrs;
vptr_map<Policy>::vptrs;

template<class Policy>
struct yOMM2_API_gcc basic_indirect_vptr : virtual indirect_vptr {
Expand Down Expand Up @@ -418,13 +418,13 @@ struct yOMM2_API_gcc simple_perfect_hash : virtual type_hash {

template<typename ForwardIterator>
static size_t
hash_type_initialize(ForwardIterator first, ForwardIterator last) {
type_hash_initialize(ForwardIterator first, ForwardIterator last) {
std::vector<type_id> buckets;
return hash_type_initialize(first, last, buckets);
return type_hash_initialize(first, last, buckets);
}

template<typename ForwardIterator>
static size_t hash_type_initialize(
static size_t type_hash_initialize(
ForwardIterator first, ForwardIterator last,
std::vector<type_id>& buckets);
};
Expand Down Expand Up @@ -462,8 +462,8 @@ struct yOMM2_API_gcc checked_simple_perfect_hash

template<typename ForwardIterator>
static size_t
hash_type_initialize(ForwardIterator first, ForwardIterator last) {
return simple_perfect_hash<Policy>::hash_type_initialize(
type_hash_initialize(ForwardIterator first, ForwardIterator last) {
return simple_perfect_hash<Policy>::type_hash_initialize(
first, last, control);
}
};
Expand Down Expand Up @@ -573,7 +573,7 @@ method_call_error_handler
template<class Policy, class... Facets>
struct yOMM2_API_gcc basic_static_policy
: basic_policy<
Policy, external_vptr_vector<Policy>, std_rtti,
Policy, vptr_vector<Policy>, std_rtti,
vectored_error_handler<Policy>, Facets...> {};

template<class Policy, class... Facets>
Expand All @@ -599,20 +599,20 @@ struct debug_shared;

#if defined(_MSC_VER) && !defined(yOMM2_DLL)
extern template class __declspec(dllimport) basic_domain<debug_shared>;
extern template class __declspec(dllimport) external_vptr_vector<debug_shared>;
extern template class __declspec(dllimport) vptr_vector<debug_shared>;
extern template class __declspec(dllimport)
vectored_error_handler<debug_shared>;
extern template class __declspec(dllimport) simple_perfect_hash<debug_shared>;
extern template class __declspec(dllimport) basic_policy<
debug_shared, external_vptr_vector<debug_shared>, std_rtti,
debug_shared, vptr_vector<debug_shared>, std_rtti,
checked_simple_perfect_hash<debug_shared>, basic_error_output<debug_shared>,
basic_update_output<debug_shared>,
backward_compatible_error_handler<debug_shared>>;
#endif

struct yOMM2_API_gcc debug_shared
: basic_policy<
debug_shared, external_vptr_vector<debug_shared>, std_rtti,
debug_shared, vptr_vector<debug_shared>, std_rtti,
checked_simple_perfect_hash<debug_shared>,
basic_error_output<debug_shared>, basic_update_output<debug_shared>,
backward_compatible_error_handler<debug_shared>> {};
Expand Down
2 changes: 1 addition & 1 deletion include/yorel/yomm2/runtime.hpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1237,7 +1237,7 @@ namespace policy {

template<class Policy>
template<typename ForwardIterator>
size_t simple_perfect_hash<Policy>::hash_type_initialize(
size_t simple_perfect_hash<Policy>::type_hash_initialize(
ForwardIterator first, ForwardIterator last,
std::vector<type_id>& buckets) {
using namespace policy;
Expand Down
20 changes: 10 additions & 10 deletions reference.in/policy.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

entry: yorel::yomm2::policy::basic_policy
entry: yorel::yomm2::default_policy
headers: yorel/yomm2/core.hpp, yorel/yomm2/keywords.hpp
headers: yorel/yomm2/policy.hpp, yorel/yomm2/core.hpp, yorel/yomm2/keywords.hpp

---
```
Expand Down Expand Up @@ -35,21 +35,21 @@ functionality is not available.
YOMM2 supports the following facet categories, and provides at least one
implementation for each category. They are summed up in the following table.

| facet category | responsibility | implementations |
| ------------------- | ------------------------------- | ---------------------------------------------------------------------------- |
| vptr, external_vptr | fetch vptr for virtual argument | **external_vptr_vector\<...>** (D, R), external_vptr_map\<...> |
| rtti, deferred_rtti | type information | **std_rtti** (D, R), no_rtti |
| type_hash | map type info to integer index | **simple_perfect_hash\<...>** (R), **checked_simple_perfect_hash`<...>** (D) |
| error | report errors | vectored_error_handler\<...> |
| error_output | describe error | **basic_error_output\<...>** (D) |
| update_output | trace `update` | **basic_update_output\<...>** (D) |
| facet category | responsibility | implementations |
| ----------------------- | ------------------------------- | ---------------------------------------------------------------------------- |
| vptr, external_vptr | fetch vptr for virtual argument | **vptr_vector\<...>** (D, R), vptr_map\<...> |
| **rtti**, deferred_rtti | type information | **std_rtti** (D, R), final_only_rtti |
| type_hash | map type info to integer index | **simple_perfect_hash\<...>** (R), **checked_simple_perfect_hash`<...>** (D) |
| error_handler | report errors | vectored_error_handler\<...> |
| error_output | describe error | **basic_error_output\<...>** (D) |
| update_output | trace `update` | **basic_update_output\<...>** (D) |

Facet categories in bold are required for YOMM2 to work at all. Facet
implementations in bold are used in the default policy, either in debug (D) or
release (R) builds only, or in both (D, R). A policy needs a `rtti` facet to be
useable. All others are optional.

Most facets are [CRTP](https://en.cppreference.com/w/cpp/language/crtp) class
Several facets are [CRTP](https://en.cppreference.com/w/cpp/language/crtp) class
templates, taking the policy as the first template argument. Some facets contain
static, global data; parameterizing the facet by the policy ensures that each
policy gets its own global data. Some facets also need to access other facets in
Expand Down
48 changes: 32 additions & 16 deletions reference.in/vptr.cpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,28 +4,27 @@
/***
<sub>/ ->home / ->reference </sub>
entry: yorel::yomm2::policy::vptr entry: yorel::yomm2::policy::external_vptr
entry: yorel::yomm2::policy::external_vptr_vector entry:
yorel::yomm2::policy::external_vptr_map headers: yorel/yomm2/core.hpp,
yorel/yomm2/keywords.hpp
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
---
```
struct vptr;
struct external_vptr;
template<class Policy> struct external_vptr_vector;
template<class Policy> struct external_vptr_map;
template<class Policy> struct vptr_vector;
template<class Policy> struct vptr_map;
```
---
A `vptr` facet is provides a static function that returns a pointer to the
dispatch data for a virtual argument's dynamic class.
The `vptr` facet is responsible for retrieving a pointer to the v-table for an
object.
YOMM2 implements method dispatch in a way similar to native virtual function
dispatch: for each virtual argument, fetch a pointer to the dispatch data
(the v-table), and use it to select a pointer to a function. Method v-tables
dispatch: for each virtual argument, fetch a pointer to the dispatch data (known
as the v-table), and use it to select a pointer to a function. YOMM2 v-tables
contain pointers to functions for unary methods, and, for multi-methods,
pointers to, and coordinates in, a multi-dimensional table of pointers to
functions.
Expand All @@ -41,8 +40,25 @@ statically from the policy's `static_vptr<Class>` member. It is conceivable
to organize an entire program around the "final" constructs; thus, the `vptr`
facet is optional.
`external_vptr` is a sub-category of `facet`. If present, the runtime calls
its static functions to allow it to initialize its data structures.
`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`.
## Example
Expand Down Expand Up @@ -226,7 +242,7 @@ define_method(
//***

/***
And now let's test:
Here is a test:
***/

//***
Expand Down
20 changes: 10 additions & 10 deletions reference/policy.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

**yorel::yomm2::policy::basic_policy**<br>
**yorel::yomm2::default_policy**<br>
<sub>defined in <yorel/yomm2/core.hpp>, also provided by<yorel/yomm2/keywords.hpp></sub>
<sub>defined in <yorel/yomm2/policy.hpp>, also provided by<yorel/yomm2/core.hpp>, <yorel/yomm2/keywords.hpp></sub>

---
```
Expand Down Expand Up @@ -35,21 +35,21 @@ functionality is not available.
YOMM2 supports the following facet categories, and provides at least one
implementation for each category. They are summed up in the following table.

| facet category | responsibility | implementations |
| ------------------- | ------------------------------- | ---------------------------------------------------------------------------- |
| vptr, external_vptr | fetch vptr for virtual argument | **external_vptr_vector\<...>** (D, R), external_vptr_map\<...> |
| rtti, deferred_rtti | type information | **std_rtti** (D, R), no_rtti |
| type_hash | map type info to integer index | **simple_perfect_hash\<...>** (R), **checked_simple_perfect_hash`<...>** (D) |
| error | report errors | vectored_error_handler\<...> |
| error_output | describe error | **basic_error_output\<...>** (D) |
| update_output | trace `update` | **basic_update_output\<...>** (D) |
| facet category | responsibility | implementations |
| ----------------------- | ------------------------------- | ---------------------------------------------------------------------------- |
| vptr, external_vptr | fetch vptr for virtual argument | **vptr_vector\<...>** (D, R), vptr_map\<...> |
| **rtti**, deferred_rtti | type information | **std_rtti** (D, R), final_only_rtti |
| type_hash | map type info to integer index | **simple_perfect_hash\<...>** (R), **checked_simple_perfect_hash`<...>** (D) |
| error_handler | report errors | vectored_error_handler\<...> |
| error_output | describe error | **basic_error_output\<...>** (D) |
| update_output | trace `update` | **basic_update_output\<...>** (D) |

Facet categories in bold are required for YOMM2 to work at all. Facet
implementations in bold are used in the default policy, either in debug (D) or
release (R) builds only, or in both (D, R). A policy needs a `rtti` facet to be
useable. All others are optional.

Most facets are [CRTP](https://en.cppreference.com/w/cpp/language/crtp) class
Several facets are [CRTP](https://en.cppreference.com/w/cpp/language/crtp) class
templates, taking the policy as the first template argument. Some facets contain
static, global data; parameterizing the facet by the policy ensures that each
policy gets its own global data. Some facets also need to access other facets in
Expand Down
48 changes: 32 additions & 16 deletions reference/vptr.md
View file
Original file line number Diff line number Diff line change
@@ -1,28 +1,27 @@

<sub>/ [home](/reference//README.md) / [reference](/reference//reference/README.md) </sub>

**yorel::yomm2::policy::vptr entry: yorel::yomm2::policy::external_vptr**<br>
**yorel::yomm2::policy::external_vptr_vector entry:**<br>
yorel::yomm2::policy::external_vptr_map headers: yorel/yomm2/core.hpp,
yorel/yomm2/keywords.hpp
**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>

---
```
struct vptr;
struct external_vptr;
template<class Policy> struct external_vptr_vector;
template<class Policy> struct external_vptr_map;
template<class Policy> struct vptr_vector;
template<class Policy> struct vptr_map;
```
---
A `vptr` facet is provides a static function that returns a pointer to the
dispatch data for a virtual argument's dynamic class.

The `vptr` facet is responsible for retrieving a pointer to the v-table for an
object.

YOMM2 implements method dispatch in a way similar to native virtual function
dispatch: for each virtual argument, fetch a pointer to the dispatch data
(the v-table), and use it to select a pointer to a function. Method v-tables
dispatch: for each virtual argument, fetch a pointer to the dispatch data (known
as the v-table), and use it to select a pointer to a function. YOMM2 v-tables
contain pointers to functions for unary methods, and, for multi-methods,
pointers to, and coordinates in, a multi-dimensional table of pointers to
functions.
Expand All @@ -38,8 +37,25 @@ statically from the policy's `static_vptr<Class>` member. It is conceivable
to organize an entire program around the "final" constructs; thus, the `vptr`
facet is optional.

`external_vptr` is a sub-category of `facet`. If present, the runtime calls
its static functions to allow it to initialize its data structures.
`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`.

## Example

Expand Down Expand Up @@ -199,7 +215,7 @@ define_method(
}
```

And now let's test:
Here is a test:

```c++
#include <sstream>
Expand Down
2 changes: 1 addition & 1 deletion src/yomm2.cpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ namespace yomm2 {
namespace policy {

template class yOMM2_API_msc basic_domain<debug_shared>;
template class yOMM2_API_msc external_vptr_vector<debug_shared>;
template class yOMM2_API_msc vptr_vector<debug_shared>;
template class yOMM2_API_msc basic_indirect_vptr<debug_shared>;
template class yOMM2_API_msc vectored_error_handler<debug_shared>;
template class yOMM2_API_msc backward_compatible_error_handler<debug_shared>;
Expand Down
Loading

0 comments on commit c46a8c3

Please sign in to comment.