microsoft/proxy

Proxy is a modern C++20 header-only library designed to enable polymorphism without the need for traditional inheritance. It provides a way to use different types of objects interchangeably using pointers as a foundation, similar to how traits work in languages like Rust.

Key features include:

• Portable: Implemented in standard C++20 and largely freestanding, making it suitable for embedded systems or kernel design.
• Non-intrusive: Implementation types do not need to inherit from an abstract binding.
• Well-managed: Provides GC-like lifetime management for objects without a full garbage collector.
• Fast: Designed to produce high-quality code that often outperforms traditional inheritance-based approaches.
• Flexible: Supports polymorphism for member functions, free functions, operators, and conversions.

Note: This repository is no longer actively maintained by Microsoft. Active development has moved to the ngcpp/proxy organization.

Since version 4.0.0, Proxy ships with .ixx files. Due to current CMake limitations regarding forward compatibility with C++ modules, you must manually declare the msft_proxy4::proxy_module target if you are consuming the library.

Note: The C++ standard version for the msft_proxy4_module target must be the same or higher than your consumer CMake target. For example, if your project uses C++23, change cxx_std_20 to cxx_std_23 in the script below.

```cmake
find_package(msft_proxy4 REQUIRED)

if(NOT DEFINED msft_proxy4_INCLUDE_DIR) # (1)
  if(NOT DEFINED msft_proxy4_SOURCE_DIR)
    message(FATAL_ERROR "`msft_proxy4_INCLUDE_DIR` or `msft_proxy4_SOURCE_DIR` must be defined to use this script.")
  endif()
  set(msft_proxy4_INCLUDE_DIR ${msft_proxy4_SOURCE_DIR}/include)
endif()

message(STATUS "Declaring `msft_proxy4::proxy_module` target for include path `${msft_proxy4_INCLUDE_DIR}`")

add_library(msft_proxy4_module)
set_target_properties(
  msft_proxy4_module
  PROPERTIES
    SYSTEM TRUE
    EXCLUDE_FROM_ALL TRUE
)

add_library(msft_proxy4::proxy_module ALIAS msft_proxy4_module)
target_sources(msft_proxy4_module PUBLIC
  FILE_SET CXX_MODULES
  BASE_DIRS ${msft_proxy4_INCLUDE_DIR}
  FILES
    ${msft_proxy4_INCLUDE_DIR}/proxy/v4/proxy.ixx
)
target_compile_features(msft_proxy4_module PUBLIC cxx_std_20) # (2)
target_link_libraries(msft_proxy4_module PUBLIC msft_proxy4::proxy)

To consume the module in your application:

target_link_libraries(main PRIVATE msft_proxy4::proxy_module)

Note (1): msft_proxy4_INCLUDE_DIR is automatically declared after find_package(msft_proxy4). If using CPM, msft_proxy4_SOURCE_DIR is declared after CPMAddPackage.

When upgrading Proxy in a monorepo or multi-module product, follow these versioning rules to avoid ODR violations:

Minor or Patch Upgrades (e.g., 3.3.0 → 3.4.0)

All 3.x.y releases preserve API/ABI compatibility. Different parts of your program can safely depend on different 3.x.y versions.

Major Upgrades (e.g., 3.4.0 → 4.0.0)

1. Intermediate Step: If your current version is earlier than 3.4.0, migrate to 3.4.0 first.
2. Versioned Namespaces: Starting from 3.4.0, each major release uses a versioned inline namespace (e.g., pro::v3, pro::v4).
3. Explicit Qualification: If a translation unit includes headers from multiple major versions, qualify the namespace explicitly:

   pro::v3::foo(); // Proxy 3 API
   pro::v4::foo(); // Proxy 4 API

4. Macro Aliases: Use major-qualified macro aliases (e.g., PRO4_DEF_MEM_DISPATCH) when multiple major versions are present in the same translation unit.
5. Incremental Rollout: Upgrade subsystems incrementally (module-by-module or DLL-by-DLL). Once a target is fully migrated, you can use unqualified calls (e.g., pro::foo()) to use the latest version and remove the old version.

To create a custom abstraction, use facade_builder to define a facade. This allows you to specify conventions (member functions) and reflections that the proxy will expose.

1. Define a dispatch macro using PRO_DEF_MEM_DISPATCH.
2. Use pro::facade_builder to add conventions.
3. Pass the resulting facade to pro::proxy<YourFacade>.
4. Use operator-> to access the abstracted members.

#include <iostream>
#include <map>
#include <memory>
#include <string>
#include <vector>
#include <proxy/proxy.h>

// 1. Define the dispatch for a member function
PRO_DEF_MEM_DISPATCH(MemAt, at);

// 2. Build the facade
struct Dictionary : pro::facade_builder                       
                    ::add_convention<MemAt, std::string(int)> 
                    ::build {};

// 3. Use the proxy in a function
void PrintDictionary(pro::proxy<Dictionary> dictionary) {
  std::cout << dictionary->at(1) << "\n";
}

int main() {
  static std::map<int, std::string> container1{{1, "hello"}};
  auto container2 = std::make_shared<std::vector<const char*>>();
  container2->push_back("hello");
  container2->push_back("world");

  // 4. Pass pointers to the proxy
  PrintDictionary(&container1); // Prints "hello"
  PrintDictionary(container2);  // Prints "world"
}