CGraph 1.0.2-alpha

CGraph.NET

CGraph.NET 是基于C#实现的图计算框架，完全移植自优秀的C++开源项目 CGraph。

CGraph.NET 提供了无第三方依赖的跨平台图流程执行框架，支持 eDAG (扩展有向无环图) 调度，具有依赖执行、并发执行、暂停恢复、超时设定等功能。

20251204，V1.0.2，优化多线程和内存占用，基准测试更新 20251203，V1.0.1，切换日志模块

✨ 特性

🏗️ 核心框架

• 🚀 高性能: 基于现代C#异步编程模型，充分利用多核性能
• 🔧 易用性: 类型安全的API设计，完整的IntelliSense支持
• 🌐 跨平台: 支持Windows、Linux、macOS
• 📦 零依赖: 核心框架无第三方依赖
• 🔄 完整移植: 保持与C++版本的API兼容性

🎯 高级特性 (第四阶段)

• ⚡ 线程池系统: 工作窃取算法，双层线程设计，支持优先级调度
• 🎭 切面编程 (AOP): 内置性能、日志、重试切面，支持自定义切面
• 📨 消息传递: 高性能消息总线，支持发布订阅和频道通信
• 🎪 事件系统: 事件驱动架构，支持异步事件处理和链式触发
• 📊 参数管理: 类型安全的参数系统，支持作用域和配置管理

🧪 质量保证

• ✅ 测试覆盖: 78个单元测试，100%通过率
• 📈 性能基准: 完整的性能测试和优化指南
• 🔍 代码质量: 遵循C#最佳实践和编码规范

可视化介绍

The diagram below illustrates the internal structure of CGraph.NET:

• Architecture: How the Pipeline orchestrates Groups and Nodes.
• Execution: Visualizing the DAG flow where Task B and Task C run in parallel.
• Lifecycle: The strict state management of every node from creation to destruction.

graph TB
    %% --- 样式定义 (让图表看起来更专业) ---
    classDef core fill:#e1f5fe,stroke:#01579b,stroke-width:2px;
    classDef flow fill:#fff9c4,stroke:#fbc02d,stroke-width:2px;
    classDef state fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px;
    classDef container fill:#ffffff,stroke:#999,stroke-dasharray: 5 5;

    %% --- 1. 核心架构模块 (Architecture) ---
    subgraph CoreArch [🏗️ Core Architecture / 核心架构]
        direction TB
        Pipeline[Pipeline<br/>调度器] 
        Group[Group<br/>节点组]
        Node[Node<br/>业务节点]
        Context[(Data Context<br/>数据上下文)]
        
        Pipeline -->|1. Build & Schedule| Group
        Group -->|2. Manage| Node
        Node <-->|3. Read/Write| Context
    end

    %% --- 2. 并行执行逻辑 (Execution Flow) ---
    subgraph Workflow [🚀 Parallel Execution / 并行执行流]
        direction LR
        Start((Start)) --> A[Node A<br/>Pre-process]
        
        %% 模拟并行分支
        subgraph Parallel [Parallel Region]
            direction TB
            B[Node B<br/>Compute Task]
            C[Node C<br/>IO Task]
        end
        
        A --> B & C
        B & C --> D[Node D<br/>Summary]
        D --> Stop((End))
    end

    %% --- 3. 生命周期 (Lifecycle) ---
    subgraph LifeCycle [🔄 Node Lifecycle / 生命周期]
        direction LR
        s1(Created) -->|Init| s2(Initialized)
        s2 -->|Run| s3(Running)
        s3 -->|Success| s4(Finished)
        s3 -->|Exception| s5(Error)
        s4 & s5 -->|Destroy| s6(Destroyed)
    end

    %% --- 模块间的关联 (Relationships) ---
    Pipeline -.->|Drives| Workflow
    Node -.->|Follows| LifeCycle

    %% --- 应用样式 ---
    class Pipeline,Group,Node,Context core
    class Start,A,B,C,D,Stop flow
    class s1,s2,s3,s4,s5,s6 state
    class CoreArch,Workflow,LifeCycle container

🚀 快速开始

安装

dotnet add package CGraph

Hello World

using CGraph;

// 定义节点
public class HelloNode : GraphNode
{
    public override async Task<GraphResult> RunAsync()
    {
        Console.WriteLine("Hello, CGraph.NET!");
        return GraphResult.Ok;
    }
}

// 使用
using var pipeline = GraphPipelineFactory.Create();
await pipeline.RegisterElementAsync<HelloNode>();
await pipeline.ProcessAsync();

复杂依赖关系

// 创建流水线
using var pipeline = GraphPipelineFactory.Create();

// 注册节点及依赖关系
await pipeline.RegisterElementAsync<MyNode1>("nodeA");
await pipeline.RegisterElementAsync<MyNode2>("nodeB", "nodeA");      // nodeB依赖nodeA
await pipeline.RegisterElementAsync<MyNode1>("nodeC", "nodeA");      // nodeC依赖nodeA  
await pipeline.RegisterElementAsync<MyNode2>("nodeD", "nodeB", "nodeC"); // nodeD依赖nodeB和nodeC

// 执行流水线
await pipeline.ProcessAsync();

执行顺序：首先执行nodeA，然后并行执行nodeB和nodeC，最后执行nodeD。

📚 教程示例

项目包含完整的教程示例，涵盖从基础到高级的所有功能特性：

🎓 基础教程 (第一、二阶段)

• T00-HelloCGraph: 基础入门，第一个CGraph应用
• T01-Simple: 简单流水线，依赖关系和拓扑排序
• T02-Cluster: 并行组合，多节点并行执行
• T03-Region: 串行区域，顺序执行控制

🚀 高级教程 (第三、四阶段)

• T04-Parameters: 参数系统，类型安全的配置管理
• T05-ThreadPool: 线程池系统，高性能并发执行
• T06-Aspects: 切面编程，AOP和横切关注点
• T07-Messaging: 消息传递，异步消息通信
• T08-Events: 事件系统，事件驱动架构
• T09-Advanced: 高级特性综合，多系统集成
• T10-Performance: 性能测试，基准测试和优化

🎮 交互式运行

cd samples/CGraph.Tutorials
dotnet run

# 选择要运行的示例：
# 0 - 运行所有示例
# 1 - Hello CGraph (基础入门)
# 2 - 简单流水线 (第一阶段)
# ...
# 11 - 性能测试和优化

📖 学习路径建议

• 初学者: T00 → T01 → T02 → T04
• 进阶开发者: T03 → T05 → T06 → T07
• 高级架构师: T08 → T09 → T10

🏗️ 架构设计

核心组件

graph TB
    %% --- 全局样式定义 ---
    classDef scheduler fill:#e3f2fd,stroke:#1565c0,stroke-width:2px;
    classDef model fill:#f1f8e9,stroke:#33691e,stroke-width:2px;
    classDef feature fill:#fff3e0,stroke:#e65100,stroke-width:2px;
    classDef kernel fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px,stroke-dasharray: 5 5;
    classDef user fill:#212121,stroke:#000,stroke-width:0px,color:#fff;

    %% --- 0. 用户入口 ---
    User([👤 User Application]):::user

    subgraph CGraphNet [🚀 CGraph.NET Framework]
        direction TB

        %% --- 1. 调度与执行层 (Scheduling & Execution) ---
        subgraph Layer_Scheduling [调度与执行层 / Scheduling Layer]
            direction TB
            Pipeline["Pipeline<br/>流水线管理器"]:::scheduler
            Factory["Pipeline Factory<br/>工厂模式"]:::scheduler
            ThreadPool["Graph ThreadPool<br/>工作窃取线程池"]:::scheduler
            Context["Execution Context<br/>执行上下文"]:::scheduler
            
            Pipeline <--> ThreadPool
        end

        %% --- 2. 核心功能支撑层 (Advanced Features) ---
        subgraph Layer_Features [功能支撑层 / Cross-Cutting Concerns]
            direction LR
            Aspects["🛡️ Aspects<br/>AOP切面管理"]:::feature
            Params["📦 Parameters<br/>参数传递"]:::feature
            Events["🔔 Events<br/>事件总线"]:::feature
            Message["📨 Messaging<br/>消息频道"]:::feature
        end

        %% --- 3. 图模型构建层 (Modeling Layer) ---
        subgraph Layer_Modeling [图构建层 / Modeling Layer]
            direction TB
            Group["Graph Group<br/>(Cluster/Region)"]:::model
            Node["Graph Node<br/>(Business Logic)"]:::model
            Element["Graph Element<br/>(Abstract Base)"]:::model
            
            Group -- contains --> Node
            Node -- inherits --> Element
        end

        %% --- 4. 内核基础层 (Kernel Layer) ---
        subgraph Layer_Kernel [内核基础层 / Kernel Infrastructure]
            direction LR
            ObjBase[GraphObjectBase]:::kernel
            Result[GraphResult]:::kernel
            Interfaces["IGraphObject / IGraphElement"]:::kernel
        end
    end

    %% --- 关系连接 ---
    User --> Factory
    Factory --> Pipeline
    Pipeline -->|Schedule| Group
    Pipeline -->|Manage| Context
    
    %% 功能层注入
    Aspects -.->|Intercept| Node
    Params <-->|Read/Write| Node
    Message -.->|Notify| Node
    Events -.->|Trigger| Pipeline

    %% 继承与依赖
    Layer_Modeling --> Layer_Kernel
    Layer_Scheduling --> Layer_Kernel
    Layer_Features --> Layer_Kernel

CGraph.NET/
├── src/
│   └── CGraph/                    # 统一核心项目
│       ├── Core/                  # 核心基础设施
│       │   ├── IGraphObject       # 基础对象接口
│       │   ├── GraphResult        # 结果类型
│       │   └── GraphObjectBase    # 基础实现
│       ├── Elements/              # 图元素系统
│       │   ├── IGraphElement      # 元素接口
│       │   ├── GraphElement       # 元素基类
│       │   ├── GraphNode          # 节点基类
│       │   └── GraphGroup         # 组合元素 (Cluster/Region)
│       ├── Pipeline/              # 流水线系统
│       │   ├── IGraphPipeline     # 流水线接口
│       │   ├── GraphPipeline      # 流水线实现
│       │   └── GraphPipelineFactory # 工厂类
│       ├── Threading/             # 🆕 线程池系统
│       │   ├── IGraphThreadPool   # 线程池接口
│       │   ├── GraphThreadPool    # 线程池实现
│       │   └── WorkStealingQueue  # 工作窃取队列
│       ├── Aspects/               # 🆕 切面编程
│       │   ├── IGraphAspect       # 切面接口
│       │   ├── GraphAspectManager # 切面管理器
│       │   └── BuiltinAspects     # 内置切面
│       ├── Messaging/             # 🆕 消息传递
│       │   ├── IGraphMessage      # 消息接口
│       │   ├── GraphMessageBus    # 消息总线
│       │   └── GraphMessageChannel # 消息频道
│       ├── Events/                # 🆕 事件系统
│       │   ├── IGraphEvent        # 事件接口
│       │   ├── GraphEventBus      # 事件总线
│       │   └── GraphEventFactory  # 事件工厂
│       ├── Parameters/            # 🆕 参数管理
│       │   ├── IGraphParam        # 参数接口
│       │   ├── GraphParamManager  # 参数管理器
│       │   └── GraphParam<T>      # 泛型参数
│       ├── Context/               # 🆕 执行上下文
│       │   └── GraphExecutionContext # 执行上下文
│       └── CGraphExtensions.cs    # 扩展方法
├── tests/
│   └── CGraph.Tests/              # 单元测试 (78个测试)
│       ├── Core/                  # 核心功能测试
│       ├── Elements/              # 元素系统测试
│       ├── Pipeline/              # 流水线测试
│       ├── AdvancedFeatures/      # 🆕 高级特性测试
│       └── Integration/           # 🆕 集成测试
└── samples/
    └── CGraph.Tutorials/          # 教程示例 (11个教程)

C++到C#映射

🆕 C#独有增强

🧪 测试

测试覆盖

• 78个单元测试 - 100%通过率 ✅
• 核心功能测试 - 基础框架和元素系统
• 高级特性测试 - 线程池、切面、消息、事件、参数
• 集成测试 - 多系统协作验证
• 性能测试 - 基准测试和优化验证

运行测试

运行所有测试：

dotnet test

运行特定模块测试：

# 核心功能测试
dotnet test --filter "FullyQualifiedName~Core"

# 高级特性测试  
dotnet test --filter "FullyQualifiedName~AdvancedFeatures"

# 集成测试
dotnet test --filter "FullyQualifiedName~Integration"

测试报告

# 生成测试覆盖率报告
dotnet test --collect:"XPlat Code Coverage"

# 详细测试输出
dotnet test --logger "console;verbosity=detailed"

📈 性能

CGraph.NET 在保持功能完整性的同时，充分利用了C#的性能优势：

🚀 核心优化

• 异步优先: 全面使用 async/await 模式，避免线程阻塞
• 零拷贝: 基于引用类型和 Span<T>，减少内存分配
• 内存优化: 利用C# GC优化，减少内存碎片
• 并发优化: 使用 System.Threading.Channels 高性能队列

⚡ 高级特性性能

• 工作窃取线程池: 双层线程设计，支持优先级调度
• 无锁消息传递: 基于Channel的高性能消息队列
• 事件系统: 异步事件处理，支持批量操作
• 切面优化: 最小化性能开销的AOP实现

📊 性能基准

运行性能测试：

cd samples/CGraph.Tutorials
echo 11 | dotnet run  # 运行性能测试示例

典型性能指标：

• 节点执行: 平均 0.1ms/节点
• 消息吞吐: 100,000+ 消息/秒
• 事件处理: 50,000+ 事件/秒 (标准模式), 500,000+ 事件/秒 (基准测试模式)
• 切面开销: < 0.01ms/切面 (优化后), 原来 7秒 → 现在 100ms
• 并发任务: 支持数千并发任务

📊 性能优化成果

🎯 项目状态

✅ 已完成功能 (v1.0)

🚧 开发路线图

v1.1 计划

• 🔄 守护进程系统 - 后台任务和定时任务
• 📊 监控和诊断 - 性能监控和健康检查
• 🔧 配置系统 - 外部配置文件支持

v1.2 计划

• 🌐 分布式支持 - 跨进程和跨机器执行
• 💾 持久化 - 流水线状态保存和恢复
• 🔌 插件系统 - 动态加载和扩展

v2.0 愿景

• 🎨 可视化设计器 - 图形化流水线设计
• ☁️ 云原生支持 - Kubernetes和容器化
• 🤖 AI集成 - 智能调度和优化

🤝 贡献

我们欢迎所有形式的贡献！

贡献方式

1. 代码贡献 - 新功能、Bug修复、性能优化
2. 文档贡献 - 教程、示例、API文档
3. 测试贡献 - 单元测试、集成测试、性能测试
4. 反馈贡献 - Bug报告、功能建议、使用体验

贡献流程

1. Fork 项目
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 开启 Pull Request

开发环境

• .NET 8.0 SDK
• Visual Studio 2022 或 JetBrains Rider
• Git 版本控制

📄 许可证

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。

🙏 致谢

• 感谢 CGraph 原作者 ChunelFeng 的优秀设计
• 感谢所有为CGraph项目做出贡献的开发者

📞 联系方式

• 项目地址: https://github.com/AMEZING77/CGraph.NET
• 原项目: https://github.com/ChunelFeng/CGraph
• 问题反馈: Issues
• 讨论交流: Discussions
• 文档网站: https://cgraph-net.readthedocs.io

📊 项目统计

• 代码行数: 15,000+ 行
• 测试覆盖: 78个测试，100%通过
• 示例教程: 11个完整教程
• 文档页面: 50+ 页详细文档
• 支持平台: Windows, Linux, macOS

<div align="center">

CGraph.NET - 让图计算在.NET生态中绽放光彩 ✨

高性能 • 易使用 • 功能完整 • 企业级

快速开始 • 教程示例 • API文档 • 贡献指南

</div>