11# mcpplibs primitives
22
3- > C++23 模块化原语库 - ` import mcpplibs.primitives; `
3+ > C++23 modular primitives library - ` import mcpplibs.primitives; `
44
55[ ![ d2x] ( https://img.shields.io/badge/d2x-ok-green.svg )] ( https://github.com/d2learn/d2x )
66[ ![ Online-ebook] ( https://img.shields.io/badge/online-ebook-orange.svg )] ( https://github.com/d2learn/d2x )
1010| --- |
1111| [ d2x Tool] ( https://github.com/d2learn/d2x ) - [ Docs] ( https://mcpp-community.github.io/d2mystl ) - [ Forum] ( https://mcpp.d2learn.org/forum ) |
1212
13- 本仓库提供可配置的 ` primitive ` 基础设施( ` underlying traits ` 、 ` policy ` 、 ` operations/dispatcher ` ),用于统一约束数值计算、错误处理与并发访问语义。
13+ This repository provides configurable ` primitive ` infrastructure ( ` underlying traits ` , ` policy ` , and ` operations/dispatcher ` ) to unify numeric behavior, error handling, and concurrency access semantics.
1414
1515> [ !WARNING]
16- > 当前项目仍在快速演进中,API 可能发生变更。
16+ > The project is still evolving quickly, and APIs may change.
1717
18- ## 特性
18+ ## Features
1919
20- - ** C++23 模块 ** — ` import mcpplibs.primitives; `
21- - ** 双构建系统 ** — 同时支持 xmake 和 CMake
22- - ** 策略驱动行为 ** — 值/类型/错误/并发策略可组合配置
23- - ** 混合运算支持 ** — 支持 ` primitive ` 与 ` underlying ` 的混合二元运算
24- - ** 并发访问接口 ** — ` primitive::load/store/compare_exchange `
20+ - ** C++23 modules ** — ` import mcpplibs.primitives; `
21+ - ** Dual build systems ** — both xmake and CMake are supported
22+ - ** Policy-driven behavior ** — value/type/error/concurrency policies are composable
23+ - ** Mixed operations support ** — binary operations between ` primitive ` and ` underlying ` are supported
24+ - ** Concurrency access APIs ** — ` primitive::load/store/compare_exchange `
2525
2626## Operators
2727
28- 该库为 ` primitive ` 提供了常见的一元、算术、位运算与比较操作。
29- 算术结果通过统一分发链路返回 ` std::expected<..., policy::error::kind> ` 。
28+ The library provides unary, arithmetic, bitwise, and comparison operations for ` primitive ` .
29+ Arithmetic paths are dispatched through a unified pipeline and return ` std::expected<..., policy::error::kind> ` .
3030
31- - 值策略( ` policy::value::checked ` / ` policy::value::saturating ` / ` policy::value::unchecked ` )决定溢出行为;
32- - 错误策略( ` policy::error::throwing ` / ` policy::error::expected ` / ` policy::error::terminate ` )决定错误传播方式。
31+ - Value policies ( ` policy::value::checked ` / ` policy::value::saturating ` / ` policy::value::unchecked ` ) define overflow behavior.
32+ - Error policies ( ` policy::error::throwing ` / ` policy::error::expected ` / ` policy::error::terminate ` ) define how errors are propagated.
3333
34- 示例:
34+ Example:
3535
3636``` cpp
3737import std;
@@ -50,29 +50,29 @@ auto maybe_overflow =
5050 checked_t{std::numeric_limits<int >::max()} + checked_t{1};
5151```
5252
53- ## Policy 协议命名空间
53+ ## Policy Protocol Namespaces
5454
55- 自定义 policy 时,协议入口按职责拆分到子命名空间:
55+ When implementing custom policies, protocol entry points are split by responsibility:
5656
5757- `policy::type::handler` / `policy::type::handler_available`
5858- `policy::concurrency::handler` / `policy::concurrency::injection`
5959- `policy::value::handler` / `policy::value::decision`
6060- `policy::error::handler` / `policy::error::request` / `policy::error::kind`
6161
62- 预设 policy 标签:
62+ Built-in policy tags:
6363
6464- `policy::value::{checked, unchecked, saturating}`
6565- `policy::type::{strict, compatible, transparent}`
6666- `policy::error::{throwing, expected, terminate}`
6767- `policy::concurrency::{none, fenced, fenced_relaxed, fenced_acq_rel, fenced_seq_cst}`
6868
69- 并发策略说明:
69+ Concurrency notes:
7070
71- - `fenced*` 系列是操作级并发语义,通过策略注入内存序 fence;
72- - `primitive` 存储仍保持统一、零额外存储抽象;
73- - `primitive::load/store/compare_exchange` 由并发策略协议提供,若策略未实现会在编译期报错。
71+ - `fenced*` policies provide operation-level concurrency semantics with injected memory-order fences.
72+ - `primitive` storage keeps a uniform, zero-extra-storage abstraction.
73+ - `primitive::load/store/compare_exchange` are provided by concurrency policy protocols and fail at compile time if unsupported.
7474
75- 示例(并发访问 API):
75+ Example (concurrent access APIs):
7676
7777```cpp
7878using shared_t = primitive<int, policy::value::checked,
@@ -88,42 +88,42 @@ if (v.compare_exchange(expected, 3)) {
8888}
8989```
9090
91- 默认策略位于 ` policy::defaults ` :
91+ Default policies are available under ` policy::defaults ` :
9292
9393- ` policy::defaults::value `
9494- ` policy::defaults::type `
9595- ` policy::defaults::error `
9696- ` policy::defaults::concurrency `
9797
98- ## 示例程序
98+ ## Examples
9999
100- - ` ex01_default_arithmetic ` : 默认策略下的基础算术运算示例。
101- - ` ex02_type_policy ` : 展示 ` strict/compatible ` 的类型协商差异,并包含 ` underlying ` 构造路径对 type 策略的影响。
102- - ` ex03_value_policy ` : 展示 ` checked/unchecked/saturating ` ,并包含与 ` underlying ` 的混合二元运算行为。
103- - ` ex04_error_policy ` : 展示不同 error 策略的处理方式。
104- - ` ex05_concurrency_policy ` : 读写组合并发场景( writer ` store ` + reader ` add/sub ` + ` CAS ` )示例。
105- - ` ex06_custom_underlying ` : 自定义 underlying traits、 rep 校验与 common rep 扩展。
106- - ` ex07_custom_policy ` : 自定义策略协议实现示例。
107- - ` ex08_custom_operation ` : 自定义 operation 扩展示例。
100+ - ` ex01_default_arithmetic ` : Basic arithmetic under default policies.
101+ - ` ex02_type_policy ` : Type negotiation with ` strict/compatible ` , including how type policy affects construction from ` underlying ` .
102+ - ` ex03_value_policy ` : ` checked/unchecked/saturating ` behavior, including mixed binary operations with ` underlying ` .
103+ - ` ex04_error_policy ` : Error-handling behavior across different error policies.
104+ - ` ex05_concurrency_policy ` : Representative mixed read/write concurrency workload ( writer ` store ` + reader ` add/sub ` + ` CAS ` ).
105+ - ` ex06_custom_underlying ` : Custom underlying traits, rep validation, and common- rep extension.
106+ - ` ex07_custom_policy ` : Custom policy protocol implementation.
107+ - ` ex08_custom_operation ` : Custom operation extension.
108108
109- ## 项目结构
109+ ## Project Layout
110110
111111```
112112mcpplibs-primitives/
113- ├── src/ # 模块源码
114- │ ├── primitives.cppm # 顶层聚合模块
115- │ ├── primitive/ # primitive 定义与 traits
116- │ ├── policy/ # policy 标签与协议实现
113+ ├── src/ # module sources
114+ │ ├── primitives.cppm # top-level aggregate module
115+ │ ├── primitive/ # primitive definitions and traits
116+ │ ├── policy/ # policy tags and protocol implementations
117117│ ├── operations/ # operation tags / dispatcher / operators
118- │ └── underlying/ # underlying traits 与 common_rep
119- ├── examples/ # ex01 ~ ex08 示例
120- ├── tests/ # 测试入口与 basic 测试集
121- ├── xmake.lua # xmake 构建脚本
122- ├── CMakeLists.txt # CMake 构建脚本
123- └── .xlings.json # xlings 包描述文件
118+ │ └── underlying/ # underlying traits and common_rep
119+ ├── examples/ # ex01 ~ ex08 examples
120+ ├── tests/ # test entry and basic test suite
121+ ├── xmake.lua # xmake build script
122+ ├── CMakeLists.txt # CMake build script
123+ └── .xlings.json # xlings package descriptor
124124```
125125
126- ## 快速开始
126+ ## Quick Start
127127
128128``` cpp
129129import std;
@@ -138,24 +138,24 @@ int main() {
138138}
139139```
140140
141- ## 安装与配置
141+ ## Installation and Setup
142142
143143``` bash
144144xlings install
145145```
146146
147- ## 构建与运行
147+ ## Build and Run
148148
149- ** 使用 xmake**
149+ ** Using xmake**
150150
151151``` bash
152152xmake build mcpplibs-primitives
153- xmake run basic # 等价于 ex01_default_arithmetic
153+ xmake run basic # equivalent to ex01_default_arithmetic
154154xmake run ex05_concurrency_policy
155155xmake run primitives_test
156156```
157157
158- ** 使用 CMake**
158+ ** Using CMake**
159159
160160``` bash
161161cmake -B build -G Ninja
@@ -165,7 +165,7 @@ cmake --build build --target basic_tests
165165ctest --test-dir build --output-on-failure
166166```
167167
168- ## 集成到构建工具
168+ ## Build System Integration
169169
170170### xmake
171171
@@ -182,10 +182,10 @@ target("myapp")
182182 set_policy (" build.c++.modules" , true )
183183```
184184
185- ## 相关链接
185+ ## Related Links
186186
187- - [ mcpp-style-ref | 现代 C++ 编码/项目风格参考 ] ( https://github.com/mcpp-community/mcpp-style-ref )
188- - [ d2mystl | 从零实现一个迷你STL库 ] ( https://github.com/mcpp-community/d2mystl )
189- - [ mcpp 社区官网 ] ( https://mcpp.d2learn.org )
190- - [ mcpp | 现代 C++ 爱好者论坛 ] ( https://mcpp.d2learn.org/forum )
191- - [ 入门教程: 动手学现代 C++] ( https://github.com/Sunrisepeak/mcpp-standard )
187+ - [ mcpp-style-ref | Modern C++ coding and project style reference ] ( https://github.com/mcpp-community/mcpp-style-ref )
188+ - [ d2mystl | Build a mini STL from scratch ] ( https://github.com/mcpp-community/d2mystl )
189+ - [ mcpp community website ] ( https://mcpp.d2learn.org )
190+ - [ mcpp forum ] ( https://mcpp.d2learn.org/forum )
191+ - [ Getting Started: Learn Modern C++ by Building ] ( https://github.com/Sunrisepeak/mcpp-standard )
0 commit comments