Skip to content

README.md

Latest commit

 

History

History
192 lines (143 loc) · 6.78 KB

README.md

File metadata and controls

192 lines (143 loc) · 6.78 KB

mcpplibs primitives

C++23 modular primitives library - import mcpplibs.primitives;

d2x Online-ebook License

中文 - English - Forum
用户文档 - User Documentation
API文档 - API Documentation

This repository provides configurable primitive infrastructure (underlying traits, policy, and operations/dispatcher) to unify numeric behavior, error handling, and concurrency access semantics.

Warning

The project is still evolving quickly, and APIs may change.

Features

  • C++23 modules — import mcpplibs.primitives;
  • Dual build systems — both xmake and CMake are supported
  • Policy-driven behavior — value/type/error/concurrency policies are composable
  • Mixed operations support — binary operations between primitive and underlying are supported
  • Concurrency access APIs — primitive::load/store/compare_exchange

Operators

The library provides unary, arithmetic, bitwise, and comparison operations for primitive.
Arithmetic paths are dispatched through a unified pipeline and return std::expected<..., policy::error::kind>.

  • Value policies (policy::value::checked / policy::value::saturating / policy::value::unchecked) define overflow behavior.
  • Error policies (policy::error::throwing / policy::error::expected / policy::error::terminate) define how errors are propagated.

Example:

import std;
import mcpplibs.primitives;

using namespace mcpplibs::primitives;
using namespace mcpplibs::primitives::operators;

primitive<int> a{1};
primitive<int> b{2};
auto sum = a + b; // std::expected<primitive<int>, policy::error::kind>

using checked_t =
    primitive<int, policy::value::checked, policy::error::expected>;
auto maybe_overflow =
    checked_t{std::numeric_limits<int>::max()} + checked_t{1};

Policy Protocol Namespaces

When implementing custom policies, protocol entry points are split by responsibility:

  • policy::type::handler / policy::type::handler_available
  • policy::concurrency::handler / policy::concurrency::injection
  • policy::value::handler / policy::value::decision
  • policy::error::handler / policy::error::request / policy::error::kind

Built-in policy tags:

  • policy::value::{checked, unchecked, saturating}
  • policy::type::{strict, compatible, transparent}
  • policy::error::{throwing, expected, terminate}
  • policy::concurrency::{none, fenced, fenced_relaxed, fenced_acq_rel, fenced_seq_cst}

Concurrency notes:

  • fenced* policies provide operation-level concurrency semantics with injected memory-order fences.
  • primitive storage keeps a uniform, zero-extra-storage abstraction.
  • primitive::load/store/compare_exchange are provided by concurrency policy protocols and fail at compile time if unsupported.

Example (concurrent access APIs):

using shared_t = primitive<int, policy::value::checked,
                           policy::concurrency::fenced_acq_rel,
                           policy::error::expected>;

shared_t v{1};
v.store(2);
auto expected = 2;
if (v.compare_exchange(expected, 3)) {
  auto now = v.load();
  (void)now;
}

Default policies are available under policy::defaults:

  • policy::defaults::value
  • policy::defaults::type
  • policy::defaults::error
  • policy::defaults::concurrency

Examples

  • ex01_default_arithmetic: Basic arithmetic under default policies.
  • ex02_type_policy: Type negotiation with strict/compatible, including how type policy affects construction from underlying.
  • ex03_value_policy: checked/unchecked/saturating behavior, including mixed binary operations with underlying.
  • ex04_error_policy: Error-handling behavior across different error policies.
  • ex05_concurrency_policy: Representative mixed read/write concurrency workload (writer store + reader add/sub + CAS).
  • ex06_custom_underlying: Custom underlying traits, rep validation, and common-rep extension.
  • ex07_custom_policy: Custom policy protocol implementation.
  • ex08_custom_operation: Custom operation extension.

Project Layout

mcpplibs-primitives/
├── src/                        # module sources
│   ├── primitives.cppm         # top-level aggregate module
│   ├── primitive/              # primitive definitions and traits
│   ├── policy/                 # policy tags and protocol implementations
│   ├── operations/             # operation tags / dispatcher / operators
│   └── underlying/             # underlying traits and common_rep
├── examples/                   # ex01 ~ ex08 examples
├── tests/                      # test entry and basic test suite
├── xmake.lua                   # xmake build script
├── CMakeLists.txt              # CMake build script
└── .xlings.json                # xlings package descriptor

Quick Start

import std;
import mcpplibs.primitives;

int main() {
  using namespace mcpplibs::primitives;

  using value_t = primitive<int, policy::error::expected>;
  auto const result = operations::add(value_t{40}, value_t{2});
  return (result.has_value() && result->value() == 42) ? 0 : 1;
}

Installation and Setup

xlings install

Build and Run

Using xmake

xmake build mcpplibs-primitives
xmake run basic                    # equivalent to ex01_default_arithmetic
xmake run ex05_concurrency_policy
xmake run primitives_test

Using CMake

cmake -B build -G Ninja
cmake --build build --target mcpplibs-primitives
cmake --build build --target ex01_default_arithmetic
cmake --build build --target basic_tests
ctest --test-dir build --output-on-failure

Build System Integration

xmake

add_repositories("mcpplibs-index https://github.com/mcpplibs/mcpplibs-index.git")

add_requires("primitives")

target("myapp")
    set_kind("binary")
    set_languages("c++23")
    add_files("main.cpp")
    add_packages("primitives")
    set_policy("build.c++.modules", true)

Related Links