Compare `protocol` with `proxy`

[jbcoe]

There is another proposal in similar design space, https://github.com/ngcpp/proxy.

• https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2025/p3086r5.html
• https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2025/p3401r1.html
• https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2025/p3584r1.html

We should understand and compare similarities and differences.

AI-comparison:

---

Protocol vs. Proxy: A Comparison of Structural Subtyping in C++

This document outlines the fundamental differences between two prominent approaches to type-erased structural subtyping in C++: the protocol pattern (inspired by P3019 std::polymorphic and PEP 544, implemented as xyz::protocol) and the proxy pattern (proposed in P3086, implemented in ngcpp/proxy).

Fundamental Differences

1. Interface Definition (Reflection vs. Library Boilerplate)

• Protocol: Employs an unobtrusive approach. Interfaces are defined as standard C++ structs containing pure declarations. The library relies on (simulated or future C++26) static reflection to introspect the struct and generate a type-erased vtable wrapper.
• Proxy: Employs a library-centric approach. Interfaces (called "Facades") are built using library templates (pro::facade_builder) and macros (PRO_DEF_MEMBER_DISPATCH). The facade explicitly dictates the dispatch mechanism, conventions, and constraints.

2. Interaction Semantics (Value vs. Pointer)

• Protocol: Models true value semantics (Direct Semantics). You interact with a protocol<T> exactly as you would a concrete value, using the dot (.) operator. It behaves like a polymorphic value container.
• Proxy: Models pointer semantics. You interact with a pro::proxy<F> as if it were a smart pointer, using the arrow (->) operator or passing the proxy to dispatch functors. This choice deliberately avoids name collisions between the wrapper's utility methods and the erased type's methods.

3. Configurability and "Meta-Properties"

• Protocol: Operates as a fixed container. Memory layout, copyability, and move behavior are determined by the protocol template implementation and standard C++ mechanisms (e.g., allocators).
• Proxy: The Facade itself describes the "meta-properties" of the container. A facade can specify whether the type is copyable, trivially relocatable (for memmove optimizations), and even restrict the small-buffer optimization (SBO) size or pointer layout.

4. Subtyping and Substitution

• Protocol: Distinct generated types. protocol<A> and protocol<B> are unrelated C++ classes, even if B is a superset of A.
• Proxy: Supports implicit downgrading. If a RichFacade includes a LeanFacade via basic_facade_builder::add_facade, a proxy<RichFacade> can be transparently substituted where a proxy<LeanFacade> is expected.

---

Pattern Comparison Table

Pattern	protocol (cc-protocol / P3019 style)	proxy (ngcpp/proxy / P3086 style)
Defining an Interface	struct Draw {   void draw() const; };	PRO_DEF_MEMBER_DISPATCH(MemDraw, draw); struct DrawFacade : pro::facade_builder   ::add_convention<MemDraw, void() const>   ::build {};
Instantiation (Owning)	xyz::protocol<Draw> p = Circle{};	pro::proxy<DrawFacade> p = pro::make_proxy<DrawFacade>(Circle{});
Method Invocation	p.draw();	p->draw(); (pointer semantics)
Non-Owning View	void render(xyz::protocol_view<Draw> v);	void render(pro::proxy_view<DrawFacade> v);
Reassignment	p = Square{};	p = pro::make_proxy<DrawFacade>(Square{});

---

Patterns Exclusive to One Library

Implementable ONLY in proxy

1. Facade Downgrading / Substitution

• Pattern: Passing a proxy<DrawableAndPrintable> to a function expecting proxy<Drawable>.
• Missing Feature in protocol: protocol generates entirely distinct, isolated classes for each interface. Because it lacks a relational composition mechanism like add_facade, the compiler has no way to map the vtable of a superset protocol to a subset protocol without a heavy, manual re-allocation/re-wrapping process.

2. Interface-Defined Layout and Relocatability

• Pattern: Forcing the polymorphic wrapper to be strictly 16 bytes (pointer + vtable) with no SBO, or declaring that the type can be optimally relocated via memcpy to save cycles during vector reallocations.
• Missing Feature in protocol: protocol uses a "one-size-fits-all" container logic (like std::function or std::any). It cannot bake memory constraints or relocation semantics into the structural interface itself, relying instead on standard C++ move constructors and std::allocator.

3. Weak Handles

• Pattern: Creating a pro::weak_proxy that observes a polymorphic object without extending its lifetime, analogous to std::weak_ptr.
• Missing Feature in protocol: protocol currently only implements strict owning (protocol) and non-owning observation (protocol_view). It does not inherently support shared ownership semantics with weak referencing built-in.

Implementable ONLY in protocol

1. True Value Semantics ("Direct" Semantics)

• Pattern: Treating the polymorphic object literally like a value: obj.do_something().
• Missing Feature in proxy: proxy explicitly separates the container from the object, enforcing pointer semantics (obj->do_something()). It lacks the generative injection necessary to synthesize member functions directly onto the wrapper that perfectly mirror the erased type.

2. Unobtrusive Interface Declarations

• Pattern: Using standard, unmodified C++ structs (or existing 3rd-party structs) as the interface definition.
• Missing Feature in proxy: proxy requires intrusive macro usage (PRO_DEF_MEMBER_DISPATCH) and specific library builder templates to create a Facade. It lacks the reflection capabilities required to automatically introspect a standard C++ struct and infer the dispatch conventions.

[jbcoe]

Discussion with AI on how the 'gap' might be closed:

Future Plan: Bridging protocol and proxy

This document details the architectural changes required for xyz::protocol to achieve feature parity with ngcpp/proxy (P3086). It also identifies fundamental design clashes where adopting a proxy feature would compromise the core identity of protocol.

1. Meta-Properties: Layout, Relocatability, and Copyability

The Gap: proxy allows Facades to dictate the container's physical layout, trivially relocatable semantics, and copy constraints. protocol currently relies on a fixed, one-size-fits-all container template.

Required Changes to protocol:
To maintain protocol's "unobtrusive interface" design (using standard C++ structs instead of library builders), meta-properties must be introduced via C++ attributes or type traits applied to the interface struct.

• Implementation Strategy:

  // Example using proposed attributes parsed by the generator
  struct [[xyz::trivially_relocatable]] [[xyz::sbo_size(32)]] [[xyz::move_only]] Draw {
    void draw() const;
  };

  The reflection/generation step (xyz_generate_protocol) would parse these attributes and specialize the internal storage of protocol<Draw> accordingly (e.g., disabling the copy constructor, adjusting the internal std::aligned_storage size, or applying memcpy during vector reallocations).

Feasibility: Highly feasible. It shifts the burden to the code generator rather than template metaprogramming, aligning with protocol's existing architecture.

2. Substitution and Downgrading

The Gap: proxy allows a proxy<RichFacade> to be implicitly converted to a proxy<LeanFacade> if RichFacade is a superset of LeanFacade. protocol classes are strictly isolated.

Required Changes to protocol:
We must introduce a structural subsetting conversion mechanism. Because the underlying type is erased, protocol<Rich> cannot simply instantiate a new protocol<Lean> directly from the underlying object without help from the vtable.

To avoid interface pollution (since protocol uses direct semantics), this API must be exposed as a free function: xyz::downgrade<LeanInterface>(rich_protocol).

• Implementation Strategy:
  1. VTable Augmentation: The generated vtable for every protocol must include a type-erased "re-eraser" function or expose a raw void* and the original type's type_info.
  2. Free Function API: template <typename Lean, typename Rich> protocol<Lean> downgrade(protocol<Rich>&& other);
  3. The Catch: To avoid double-indirection (thunking a vtable through another vtable), the protocol<Rich> vtable must be able to generate a protocol<Lean> vtable on demand. This requires generating an exponential number of conversion paths or relying on heavy RTTI and dynamic registry lookups.

Feasibility / Impossibility: Partially Impossible without overhead. While the API is cleanly solvable via free functions, true zero-overhead downgrading is extremely difficult in protocol because the interfaces are plain structs rather than composed hierarchies (like basic_facade_builder::add_facade). The compiler doesn't know the relationship between Rich and Lean at the time Rich's vtable is instantiated, making zero-overhead protocol downgrading fundamentally at odds with independent structural interface definitions.

3. Shared and Weak Observation

The Gap: proxy supports weak_proxy for observing shared polymorphic objects. protocol only has unique ownership (protocol) and non-owning views (protocol_view).

Required Changes to protocol:
Introduce new container types protocol_shared<T> and protocol_weak<T>, analogous to std::shared_ptr and std::weak_ptr.

• Implementation Strategy:
  Instead of the object buffer living directly inside the protocol wrapper, it would live in a heap-allocated control block containing a reference count, the vtable pointer, and the object itself. protocol_weak<T> would observe this control block.

Feasibility: Highly feasible. It requires implementing a new set of wrapper templates that utilize the same generated vtables but employ standard atomic reference-counting control blocks.

4. Fundamental Design Clashes (The Impossibilities)

While mechanical features can be ported, standardizing protocol to match proxy entirely is impossible due to fundamentally opposed design philosophies:

Impossibility A: Direct Semantics vs. Member Function Utilities

• The Problem: protocol guarantees Direct Semantics (obj.foo()). This makes it a true value type. However, if we add container management utilities like proxy has as member functions (e.g., p.downgrade(), p.has_value()), these names pollute the interface. If the erased type also has a method named has_value(), the wrapper method collides with the interface method.
• The proxy Solution: proxy avoids this by using Pointer Semantics (p->foo()). The wrapper utilities live on the pointer (p.has_value()), and the interface lives on the pointee.
• The protocol Solution (Free Functions): Because protocol uses direct semantics, it cannot adopt wrapper metadata utilities as member functions. Instead, it must rely entirely on free functions, such as xyz::downgrade<Base>(derived) or xyz::has_value(p). While this avoids interface pollution entirely, it diverges from the object-oriented utility style of std::any or proxy.

Impossibility B: Unobtrusive Definitions vs. Explicit Composition

• The Problem: protocol's greatest strength is its ability to use unmodified, plain C++ structs (or structs from 3rd party libraries) as the interface definition.
• The proxy Solution: proxy's downgrading and layout controls work efficiently because the user explicitly composes them using library templates (add_facade, add_convention).
• Conclusion: If protocol adopts explicit compositional hierarchies to solve the downgrading issue, it ceases to be "structural subtyping of plain structs" and becomes a heavily macro/template-bound library like proxy. You cannot have both perfect unobtrusive structural subtyping and zero-overhead, explicitly mapped downgrading hierarchies.