You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/PRO_DEF_FREE_AS_MEM_DISPATCH.md
+2-2
Original file line number
Diff line number
Diff line change
@@ -1,7 +1,7 @@
1
1
# Macro `PRO_DEF_FREE_AS_MEM_DISPATCH`
2
2
3
3
```cpp
4
-
#definePRO_DEF_FREE_AS_MEM_DISPATCH // see below
4
+
#definePRO_DEF_FREE_AS_MEM_DISPATCH // since 3.1, see below
5
5
```
6
6
7
7
Macro `PRO_DEF_FREE_AS_MEM_DISPATCH` defines dispatch types for free function expressions with accessibility via a member function. It supports two syntaxes:
Copy file name to clipboardExpand all lines: docs/basic_facade_builder.md
+65-5
Original file line number
Diff line number
Diff line change
@@ -25,23 +25,83 @@ using facade_builder = basic_facade_builder<std::tuple<>, std::tuple<>,
25
25
26
26
`class Cs`, `class Rs`, and `proxiable_ptr_constraints C` are the template parameters of `basic_facade_builder`. `basic_facade_builder` provides a member type `build` that compiles the template parameters into a [`facade`](facade.md) type. The template parameters can be modified via various member alias templates that specify `basic_facade_builder` with the modified template parameters.
27
27
28
+
## Notes
29
+
30
+
The design of `basic_facade_builder` utilizes template metaprogramming techniques. We recommend the following 2 guidelines when using `basic_facade_builder` to define a facade type.
31
+
32
+
- **Define a type for each facade.**
33
+
34
+
For example, when defining a `Formattable` facade, the following two definitions are both syntactically correct:
35
+
36
+
```cpp
37
+
// (1) Recommended
38
+
struct Formattable : pro::facade_builder
39
+
::support_format
40
+
::build {};
41
+
42
+
// (2) Discouraged
43
+
using Formattable = pro::facade_builder
44
+
::support_format
45
+
::build;
46
+
```
47
+
48
+
Definition `(2)` is a type alias, its "real" type may have a long name, and the type evaluation may be executed for multiple times even when compiling a single source file. Although the two type definitions are equivalent at runtime, definitions like `(2)` may significantly reduce compilation performance. Therefore, it is recommended always to define a facade as a type with inheritance, similar to definition `(1)`.
49
+
50
+
-**Use the `template` keyword on demand when defining a facade template.**
51
+
52
+
Consider the following facade template definitions:
Although GCC can usually compile the code above, it does not adhere to the C++ standard syntax, and as a result, it won't compile with Clang or MSVC ([live demo](https://godbolt.org/z/Gen74qY9r)). This is because type `add_facade<MovableCallable<Os...>>` depends on the template parameters, and an explicit `template` is required when specifying its member alias template `support_copy`. To fix the code, we could either add the keyword `template` before `support_copy`, or simply swap `add_facade` and `support_copy`. For instance:
| [`build`](basic_facade_builder/build.md) | Specifies a [`facade`](facade.md) type deduced from the template parameters of the `basic_facade_builder` |
|[`build`](basic_facade_builder/build.md)| Specifies a [`facade`](facade.md) type deduced from the template parameters of the `basic_facade_builder`|
90
+
|[`support_format`<br />`support_wformat`](basic_facade_builder/support_format.md)<br />*(since 3.2)*| Specifies the capability of formatting (via [formatting functions](https://en.cppreference.com/w/cpp/utility/format)) to the template parameters |
91
+
|[`support_rtti`<br />`support_indirect_rtti`<br />`support_direct_rtti`](basic_facade_builder/support_rtti.md)<br />*(since 3.2)*| Specifies the capability of RTTI (via `proxy_cast` and `proxy_typeid`) to the template parameters |
|[`add_convention`<br />`add_indirect_convention`<br />`add_direct_convention`](basic_facade_builder/add_convention.md)| Adds a convention to the template parameters |
39
-
| [`add_reflection`<br />`add_indirect_reflection`<br />`add_direct_reflection`](basic_facade_builder/add_reflection.md) | Adds a reflection to the template parameters |
40
98
|[`add_facade`](basic_facade_builder/add_facade.md)| Adds a facade to the template parameters |
99
+
|[`add_reflection`<br />`add_indirect_reflection`<br />`add_direct_reflection`](basic_facade_builder/add_reflection.md)| Adds a reflection to the template parameters |
100
+
|[`add_view`](basic_facade_builder/support_view.md)<br />*(since 3.2)*| Specifies the capability of implicit conversion to `proxy_view` to the template parameters |
41
101
|[`restrict_layout`](basic_facade_builder/restrict_layout.md)| Specifies maximum `max_size` and `max_align` of `C` in the template parameters |
42
102
|[`support_copy`](basic_facade_builder/support_copy.md)| Specifies minimum `copyability` of `C` in the template parameters |
43
-
| [`support_relocation`](basic_facade_builder/support_relocation.md) | Specifies minimum `relocatability` of `C` in the template parameters |
44
103
|[`support_destruction`](basic_facade_builder/support_destruction.md)| Specifies minimum `destructibility` of `C` in the template parameters |
104
+
|[`support_relocation`](basic_facade_builder/support_relocation.md)| Specifies minimum `relocatability` of `C` in the template parameters |
It is encouraged to inherit `build` with an empty `struct` before specifying a [`proxy`](../proxy.md), rather than `using` or `typedef` the `build` type into an alias, to improve compilation performance.
52
52
53
-
The default values of the fields of [`proxiable_ptr_constraints`](../proxiable_ptr_constraints.md) are based on our engineering practices. The default values of `max_size` and `max_alignment` are usually sufficient for many implementations of [fancy pointers](https://en.cppreference.com/w/cpp/named_req/Allocator#Fancy_pointers), such as [`std::unique_ptr`](https://en.cppreference.com/w/cpp/memory/unique_ptr), [`std::shared_ptr`](https://en.cppreference.com/w/cpp/memory/shared_ptr), and [boost::interprocess::offset_ptr](https://www.boost.org/doc/libs/1_85_0/doc/html/interprocess/offset_ptr.html). A larger combination of size and alignment ensures better compatibility with the implementation of the underlying pointers and reduces heap allocation when the element type fits in the buffer (see [function template `make_proxy`](../make_proxy.md)), at the cost of making the corresponding [`proxy`](../proxy.md) objects larger.
53
+
The default values of the fields of [`proxiable_ptr_constraints`](../proxiable_ptr_constraints.md) are based on our engineering practices. The default values of `max_size` and `max_alignment` are usually sufficient for many implementations of [fancy pointers](https://en.cppreference.com/w/cpp/named_req/Allocator#Fancy_pointers), such as [`std::unique_ptr`](https://en.cppreference.com/w/cpp/memory/unique_ptr), [`std::shared_ptr`](https://en.cppreference.com/w/cpp/memory/shared_ptr), and [`boost::interprocess::offset_ptr`](https://www.boost.org/doc/libs/1_85_0/doc/html/interprocess/offset_ptr.html). A larger combination of size and alignment ensures better compatibility with the implementation of the underlying pointers and reduces heap allocation when the element type fits in the buffer (see [function template `make_proxy`](../make_proxy.md)), at the cost of making the corresponding [`proxy`](../proxy.md) objects larger.
using support_format = basic_facade_builder</* see below */>;
5
+
6
+
using support_wformat = basic_facade_builder</* see below */>;
7
+
```
8
+
9
+
The member types `support_format` and `support_wformat` of `basic_facade_builder<Cs, Rs, C>` add necessary convention and reflection types to the template parameters, enabling specializations of [`std::formatter<proxy_indirect_accessor<F>, CharT>`](../formatter_proxy_indirect_accessor.md) where `F` is a [facade](../facade.md) type built from `basic_facade_builder`, `CharT` is `char` (if `support_format` is specified) or `wchar_t` (if `support_wformat` is specified).
10
+
11
+
`support_format` and `support_wformat` also add constraints to a facade type `F` built from `basic_facade_builder`, requiring a contained value of `proxy<F>` be *formattable*. Formally, let `p` be a contained value of `proxy<F>`, `CharT` be `char` (if `support_format` is specified) or `wchar_t` (if `support_wformat` is specified), `T` be `std::decay_t<decltype(*std::as_const(p))>`, `std::formatter<T, CharT>` shall be an enabled specialization of `std::formatter`.
12
+
13
+
## Example
14
+
15
+
```cpp
16
+
#include<format>
17
+
#include<iostream>
18
+
19
+
#include"proxy.h"
20
+
21
+
structFormattable : pro::facade_builder
22
+
::support_format
23
+
::build {};
24
+
25
+
int main() {
26
+
pro::proxy<Formattable> p = pro::make_proxy<Formattable>(123);
using support_indirect_rtti = basic_facade_builder</* see below */>;
7
+
8
+
using support_direct_rtti = basic_facade_builder</* see below */>;
9
+
```
10
+
11
+
The member types `support_rtti`, `support_indirect_rtti` and `support_direct_rtti` add necessary convention and reflection types to the template parameters, enabling [RTTI](https://en.wikipedia.org/wiki/Run-time_type_information) support for [`proxy<F>`](../proxy.md), where `F` is a [facade](../facade.md) type built from `basic_facade_builder`. For an RTTI-enabled facade `F`, non-member functions `proxy_typeid` (similar to [`std::any::type`](https://en.cppreference.com/w/cpp/utility/any/type)) and `proxy_cast` (similar to [`std::any_cast`](https://en.cppreference.com/w/cpp/utility/any/any_cast)) are available for [`proxy_indirect_accessor<F>`](../proxy_indirect_accessor.md) (if `support_rtti` or `support_indirect_rtti` is specified) or [`proxy<F>`](../proxy.md) (if `support_direct_rtti` is specified).
0 commit comments