Skip to content

Add independent named function dispatch and access - #100

Merged
mingxwa merged 2 commits into
ngcpp:feature/v5from
mingxwa:user/mingxwa/named-dispatch
Nov 15, 2026
Merged

mingxwa merged 2 commits into
ngcpp:feature/v5from
mingxwa:user/mingxwa/named-dispatch

Conversation

@mingxwa

@mingxwa mingxwa commented Nov 10, 2026 •

Copy link
Copy Markdown
Member

Motivation

  • A dispatch type defined by PRO_DEF_MEM_DISPATCH, PRO_DEF_FREE_DISPATCH or PRO_DEF_FREE_AS_MEM_DISPATCH carries its own accessor, so the function it calls also fixes the name and kind of the function exposed on a proxy. A dispatch type that carries an accessor is the v4 design that v5 removes.
  • Calling one function and exposing it under another name, or as a member instead of a free function, required a hand-written dispatch type.

Design

  • member_dispatch<"name"> calls the member function name, and free_dispatch<"name"> calls the free function name. member_access<"name"> defines the member function name on proxy, and free_access<"name"> defines the friend function name.
  • The dispatch types carry no accessor. As with operator_dispatch, basic_facade_builder gives a convention of member_dispatch<"name"> the access type member_access<"name"> and a convention of free_dispatch<"name"> the access type free_access<"name">, and weak_dispatch of either shares that access type. A hand-written convention can pair either dispatch type with any access type.
  • PRO_ENABLE_MEMBER(name) and PRO_ENABLE_FREE(name) define the dispatch and access specializations for name at global namespace scope. Each name is enabled at most once per translation unit for each macro.
  • The primary templates assert that their name is enabled. Using a name that is not enabled, naming an access type whose name is not enabled, or enabling a name after its first use is diagnosed at compile time instead of removing an accessor silently or leaving the program ill-formed with no diagnostic.
  • free_dispatch performs ordinary lookup from its own scope, then the namespace pro::inline v5, the namespace pro and its inline namespaces, and finally the global namespace. Argument-dependent lookup happens at instantiation. Overloads that differ between translation units violate the one-definition rule, which the library cannot detect, so the documentation states how to avoid it.

Changes

  • Added the class templates member_dispatch, member_access, free_dispatch and free_access, declared next to operator_dispatch so that proxy_macros.h stays a macro-only header, and exported them from the proxy.v5 module.
  • Defined the primary templates of the four class templates, operator_dispatch and operator_access with a static_assert. The condition detail::dependent_false keeps the assertion dependent for compilers without CWG2518, such as Clang 16, MSVC before 19.40 and NVHPC 24.1.
  • Changed detail::sign<N> so that N is the array length including the terminating null character. This removed its deduction guide and makes GCC and Clang print the whole string in diagnostics.
  • Made member_access and free_access the default access types of member_dispatch and free_dispatch in basic_facade_builder.
  • Added PRO_ENABLE_MEMBER and PRO_ENABLE_FREE with their version-qualified forms and the ambiguity diagnostics of the other version-less macros. The version-less forms are object-like aliases, so that a macro argument is stringized as written.
  • Added PRO5D_DEF_FREE_ACCESSOR for access types that define friend functions, and PRO5D_GEN_DEBUG_SYMBOL_FOR_FREE_ACCESSOR, which it, the reflection accessor of free_access and the legacy free accessor share.
  • Added specification pages with examples for the four class templates and the two macros, covering the accessor of each descriptor, the lookup rules of free_dispatch, the one-definition rule across translation units and module usage, and listed the new types in the builder rules, ProAccess, the specification index, the FAQ and the README.
  • Added guidance to ProAccess that an accessor formed from several descriptors is subject to the overloading rules of C++, and that an access type is encouraged to diagnose combinations it does not support.
  • Stated in operator_dispatch and operator_access that instantiating them with an unsupported Sign or Rhs is ill-formed.
  • Added named dispatch tests that mirror the per-aspect tests of the existing macros, covering overload resolution, qualified overloads, weak_dispatch, direct conventions, reflections, access types independent of the dispatch type and the size of aggregated accessors.
  • Checked the default access types that the builder gives the new dispatch types, including through weak_dispatch, and moved the module test onto member_dispatch.
  • Defined the facades of the traits tests with the builder or by hand instead of shadowing the members of a built facade.

@mingxwa
mingxwa force-pushed the user/mingxwa/named-dispatch branch 2 times, most recently from c779fe6 to 9a4e20e Compare November 14, 2026 14:05
**NOTE**: This targets `feature/v5`.

**Motivation**
- A dispatch type defined by `PRO_DEF_MEM_DISPATCH`, `PRO_DEF_FREE_DISPATCH` or `PRO_DEF_FREE_AS_MEM_DISPATCH` carries its own accessor, so the function it calls also fixes the name and kind of the function exposed on a `proxy`. A dispatch type that carries an accessor is the v4 design that v5 removes.
- Calling one function and exposing it under another name, or as a member instead of a free function, required a hand-written dispatch type.

**Design**
- `member_dispatch<"name">` calls the member function `name`, and `free_dispatch<"name">` calls the free function `name`. `member_access<"name">` defines the member function `name` on `proxy`, and `free_access<"name">` defines the friend function `name`.
- The dispatch types carry no accessor. As with `operator_dispatch`, `basic_facade_builder` gives a convention of `member_dispatch<"name">` the access type `member_access<"name">` and a convention of `free_dispatch<"name">` the access type `free_access<"name">`, and `weak_dispatch` of either shares that access type. A hand-written convention can pair either dispatch type with any access type.
- `PRO_ENABLE_MEMBER(name)` and `PRO_ENABLE_FREE(name)` define the dispatch and access specializations for `name` at global namespace scope. Each name is enabled at most once per translation unit for each macro.
- The primary templates assert that their name is enabled. Using a name that is not enabled, naming an access type whose name is not enabled, or enabling a name after its first use is diagnosed at compile time instead of removing an accessor silently or leaving the program ill-formed with no diagnostic.
- `free_dispatch` performs ordinary lookup from its own scope, then the namespace `pro::inline v5`, the namespace `pro` and its inline namespaces, and finally the global namespace. Argument-dependent lookup happens at instantiation. Overloads that differ between translation units violate the one-definition rule, which the library cannot detect, so the documentation states how to avoid it.

**Changes**
- Added the class templates `member_dispatch`, `member_access`, `free_dispatch` and `free_access`, declared next to `operator_dispatch` so that `proxy_macros.h` stays a macro-only header, and exported them from the `proxy.v5` module.
- Defined the primary templates of the four class templates, `operator_dispatch` and `operator_access` with a `static_assert`. The condition `detail::dependent_false` keeps the assertion dependent for compilers without CWG2518, such as Clang 16, MSVC before 19.40 and NVHPC 24.1.
- Changed `detail::sign<N>` so that `N` is the array length including the terminating null character. This removed its deduction guide and makes GCC and Clang print the whole string in diagnostics.
- Made `member_access` and `free_access` the default access types of `member_dispatch` and `free_dispatch` in `basic_facade_builder`.
- Added `PRO_ENABLE_MEMBER` and `PRO_ENABLE_FREE` with their version-qualified forms and the ambiguity diagnostics of the other version-less macros.
- Added `PRO5D_DEF_FREE_ACCESSOR` for access types that define friend functions, and `PRO5D_GEN_DEBUG_SYMBOL_FOR_FREE_ACCESSOR`, which it, the reflection accessor of `free_access` and the legacy free accessor share.
- Added specification pages with examples for the four class templates and the two macros, covering the accessor of each descriptor, the lookup rules of `free_dispatch`, the one-definition rule across translation units and module usage, and listed the new types in the builder rules, *ProAccess*, the specification index and the README.
- Added guidance to *ProAccess* that an accessor formed from several descriptors is subject to the overloading rules of C++, and that an access type is encouraged to diagnose combinations it does not support.
- Stated in `operator_dispatch` and `operator_access` that instantiating them with an unsupported `Sign` or `Rhs` is ill-formed.
- Replaced the free-as-member test with a facade that pairs `free_dispatch<"to_string">`, found through a global using-declaration, with both `member_access<"ToString">` and `free_access<"ToString">`.
- Moved the weak member dispatch of `ResourceDictionary`, the reflection traits tests and the module test onto the new types, and checked the default access types that the builder gives them.
- Replaced the shared reflection access test with a facade whose member access type combines a direct convention and a reflection and whose free access type exposes the same reflection.
@mingxwa
mingxwa force-pushed the user/mingxwa/named-dispatch branch from 9a4e20e to 69af211 Compare November 14, 2026 14:40
- Restored the dispatch, invocation and reflection tests that had been moved onto the new types. This brings back the coverage of the three-argument `PRO_DEF_MEM_DISPATCH`, the free-as-member test, the reflector accessor and `TestSharedAccess` with its size checks.
- Added named dispatch tests that mirror the per-aspect tests of the existing macros. They cover overload resolution, qualified overloads, `weak_dispatch`, direct conventions, reflections, access types independent of the dispatch type and the size of aggregated accessors.
- Checked the default access types of `weak_dispatch` of `member_dispatch` and `free_dispatch`, and that the builder-provided accessors exist.
- Defined the facades of the traits tests with the builder or by hand instead of shadowing the members of a built facade.
- Removed the unused `PRO_ENABLE_FREE(GetQux)` from the module tests.
- Restored the object-like version-less `PRO_ENABLE_MEMBER` and `PRO_ENABLE_FREE`. The function-like aliases expanded a macro argument before stringizing it, so with `#define Foo Bar`, `PRO_ENABLE_MEMBER(Foo)` defined `member_dispatch<"Bar">` while `PRO5_ENABLE_MEMBER(Foo)` defined `member_dispatch<"Foo">`.
- Counted the six macros in the FAQ, replaced its outdated sentence about modules, and explained in the macro pages why the macros are invoked in an `extern "C++"` block.
@mingxwa
mingxwa merged commit 4dcc0b7 into ngcpp:feature/v5 Nov 15, 2026
20 checks passed
@mingxwa
mingxwa deleted the user/mingxwa/named-dispatch branch November 15, 2026 03:23
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant