CGraph AI Agent

<p align="left"> <a href="https://github.com/ChunelFeng/CGraph"><img src="https://badgen.net/badge/langs/C++,Python/cyan?list=1" alt="languages"></a> <a href="https://github.com/ChunelFeng/CGraph"><img src="https://badgen.net/badge/os/MacOS,Linux,Windows/cyan?list=1" alt="os"></a> <a href="https://github.com/ChunelFeng/CGraph/stargazers"><img src="https://badgen.net/github/stars/ChunelFeng/CGraph?color=cyan" alt="stars"></a> <a href="https://github.com/ChunelFeng/CGraph/network/members"><img src="https://badgen.net/github/forks/ChunelFeng/CGraph?color=cyan" alt="forks"></a> <a href="https://badge.fury.io/py/pycgraph"><img src="https://badge.fury.io/py/pycgraph.svg" alt="pypi"></a> <a href="https://pepy.tech/projects/pycgraph"><img src="https://static.pepy.tech/personalized-badge/pycgraph?period=total&units=INTERNATIONAL_SYSTEM&left_color=GRAY&right_color=GREEN&left_text=pypi+downloads" alt="PyPI Downloads"></a> <a href="https://www.codefactor.io/repository/github/chunelfeng/cgraph/overview/main"><img src="https://www.codefactor.io/repository/github/chunelfeng/cgraph/badge/main" alt="CodeFactor" /></a> </p>

中文 | English Readme | deepwiki

<h1 align="center"> CGraph 说明文档 </h1> <img align="right" src="https://github.com/ChunelFeng/CGraph/blob/main/doc/image/CGraph%20Author.jpg" width="256px">

<b>CGraph</b> is a cross-platform <b>D</b>irected <b>A</b>cyclic <b>G</b>raph framework based on pure C++ without any 3rd-party dependencies.</br></br> You, with it, can <b>build your own operators simply, and describe any running schedules</b> as you need, such as dependence, parallelling, aggregation, conditional and so on. <b>Python APIs</b> are also supported to build your pipeline.</br></br> Tutorials and contact information are shown as follows. Please <b>get in touch with us for free</b> if you need more about this repository.

一. 简介

CGraph中文名为【色丶图】，是一套无任何第三方依赖的跨平台图流程执行框架。通过GPipeline(流水线)底层调度，提供了包含依赖元素依次执行、非依赖元素并发执行，支持暂停、恢复、超时设定的 eDAG 调度功能。

使用者只需继承GNode(节点)类，实现子类的run()方法，并根据需要设定依赖关系，即可实现任务的图化执行或流水线执行。还可以通过设定各种包含多节点信息的GGroup(组)，自行控制图的条件判断、循环和并发执行逻辑。

<br>

本工程使用纯C++11标准库编写，无任何第三方依赖，兼容MacOS、Linux、Windows和Android系统。支持本地编译和二次开发，并且提供Python版本：pycgraph。编译和安装方法，请参考 CGraph 编译说明 <br>

详细功能介绍和用法，请参考 一面之猿网 中的文章内容。相关视频在B站持续更新中，欢迎观看和交流：<br>

• 【B站视频】CGraph 入门篇 <br>
• 【B站视频】CGraph 功能篇 <br>
  • 全面介绍CGraph项目中，所有的名词术语和功能模块
  • 结合实际coding过程，详细介绍了每个功能的具体的使用场景、用法、以及解决的问题
  • 适合想要全面了解功能和快速上手使用CGraph的童鞋
  • 适合对多线程编程感兴趣的童鞋
• 【B站视频】CGraph 应用篇 <br>
• 【B站视频】CGraph 分享篇 <br>

---

二. 入门Demo

<details open> <summary><b>C++ 版本</b></summary>

#include "CGraph.h"

using namespace CGraph;

class MyNode1 : public GNode {
public:
    CStatus run() override {
        printf("[%s], sleep for 1 second ...\n", this->getName().c_str());
        CGRAPH_SLEEP_SECOND(1)
        return CStatus();
    }
};

class MyNode2 : public GNode {
public:
    CStatus run() override {
        printf("[%s], sleep for 2 second ...\n", this->getName().c_str());
        CGRAPH_SLEEP_SECOND(2)
        return CStatus();
    }
};


int main() {
    /* 创建一个流水线，用于设定和执行流图信息 */
    GPipelinePtr pipeline = GPipelineFactory::create();
    GElementPtr a, b, c, d = nullptr;

    /* 注册节点之间的依赖关系 */
    pipeline->registerGElement<MyNode1>(&a, {}, "nodeA");
    pipeline->registerGElement<MyNode2>(&b, {a}, "nodeB");
    pipeline->registerGElement<MyNode1>(&c, {a}, "nodeC");
    pipeline->registerGElement<MyNode2>(&d, {b, c}, "nodeD");

    /* 执行流图框架 */
    pipeline->process();

    /* 清空流水线中所有的资源 */
    GPipelineFactory::remove(pipeline);

    return 0;
}

</details>

<br> 如上图所示，图结构执行的时候，首先执行a节点。a节点执行完毕后，并行执行b和c节点。b和c节点全部执行完毕后，再执行d节点。

<details> <summary><b>Python 版本</b></summary>

# pip install pycgraph

import time
from datetime import datetime

from pycgraph import GNode, GPipeline

class MyNode1(GNode):
    def run(self):
        print("[{0}] {1}, sleep for 1 second ... ".format(datetime.now(), self.getName()))
        time.sleep(1)
        return 0

class MyNode2(GNode):
    def run(self):
        print("[{0}] {1}, sleep for 2 second ... ".format(datetime.now(), self.getName()))
        time.sleep(2)
        return 0


if __name__ == '__main__':
    pipeline = GPipeline()
    a, b, c, d = MyNode1(), MyNode2(), MyNode1(), MyNode2()

    pipeline.registerGElement(a, set(), "nodeA")
    pipeline.registerGElement(b, {a}, "nodeB")
    pipeline.registerGElement(c, {a}, "nodeC")
    pipeline.registerGElement(d, {b, c}, "nodeD")

    pipeline.process()

</details> <details> <summary><b>其他版本</b></summary>

• CsCGraph : A CSharp native, CGraph-API-liked DAG project
• JaCGraph : A Java native, CGraph-API-liked DAG project
• GoCGraph : A Go native, CGraph-API-liked DAG project
• CGraph-lite : A one-header-only, CGraph-API-liked DAG project, lite version by C++

</details>

---

三. 推荐阅读

• 纯序员给你介绍图化框架的简单实现——执行逻辑
• 纯序员给你介绍图化框架的简单实现——循环逻辑
• 纯序员给你介绍图化框架的简单实现——参数传递
• 纯序员给你介绍图化框架的简单实现——条件判断
• 纯序员给你介绍图化框架的简单实现——面向切面
• 纯序员给你介绍图化框架的简单实现——函数注入
• 纯序员给你介绍图化框架的简单实现——消息机制
• 纯序员给你介绍图化框架的简单实现——事件触发
• 纯序员给你介绍图化框架的简单实现——超时机制
• 纯序员给你介绍图化框架的简单实现——线程池优化（一）
• 纯序员给你介绍图化框架的简单实现——线程池优化（二）
• 纯序员给你介绍图化框架的简单实现——线程池优化（三）
• 纯序员给你介绍图化框架的简单实现——线程池优化（四）
• 纯序员给你介绍图化框架的简单实现——线程池优化（五）
• 纯序员给你介绍图化框架的简单实现——线程池优化（六）
• 纯序员给你介绍图化框架的简单实现——性能优化（一）
• 纯序员给你介绍图化框架的简单实现——性能优化（二）
• 纯序员给你介绍图化框架的简单实现——距离计算 <br><br>
• CGraph 主打歌——《听码农的话》
• 聊聊我写CGraph的这一年
• 从零开始主导一款收录于awesome-cpp的项目，是一种怎样的体验?
• 炸裂！CGraph性能全面超越taskflow之后，作者却说他更想...
• 以图优图：CGraph中计算dag最大并发度思路总结
• 一文带你了解练习时长两年半的CGraph
• CGraph作者想知道，您是否需要一款eDAG调度框架
• 降边增效：CGraph中冗余边剪裁思路总结
• 最新码坛爽文：重生之我在国外写CGraph(python版本)
• 做之前不敢想的 CGraph <br>

---

四. 关联项目

• GraphANNS : Graph-based Approximate Nearest Neighbor Search Working off CGraph
• CThreadPool : 一个简单好用、功能强大、性能优异、跨平台的C++线程池
• PyCGraph-example : A useful list of how cool to use PyCGraph
• awesome-cpp : A curated list of awesome C++ (or C) frameworks, libraries, resources, and shiny things. Inspired by awesome-... stuff.
• awesome-workflow-engines : A curated list of awesome open source workflow engines
• taskflow : A General-purpose Parallel and Heterogeneous Task Programming System
  • 【B站视频】CGraph 和 taskflow 性能对比实测 <br>
• torchpipe : Serving Inside Pytorch
  • 【B站视频】开源项目torchpipe - ai引擎在线高并发经验和实战
• nndeploy : Easy-to-use, high-performance, multi-platform inference deployment framework
  • 【B站视频合集】【nndeploy】AI推理框架最全教程
• KuiperInfer : 带你从零实现一个高性能的深度学习推理库，支持大模型 llama2 、Unet、Yolov5、Resnet等模型的推理。Implement a high-performance deep learning inference library step by step
  • 【B站视频】KuiperInfer推理框架 - 一个面向教学的推理框架
• OGraph : A simple way to build a pipeline with Go.
  • 【B站视频】听阿里云大佬分享：OGraph——基于Go的流图调度二三事
• incubator-hugegraph-ai : The integration of HugeGraph with AI/LLM & GraphRAG
  • Agentic GraphRAG：模块化架构实践
• pybind11 : Seamless operability between C++11 and Python
  • 本项目Python接口绑定功能，使用pybind11实现
  • 【B站视频】pybind11落地实战——PyCGraph是怎样练成的 | 飞书文档链接
• FlowX : MCP server and Python SDK that generates, runs and refines AI agent workflows from natural language (Generative Workflow, A2A, FastAPI).
  • 【B站视频】生成式工作流探索-FlowX实践和技术展望

---

<details> <summary><b>附录-1. 版本信息</b></summary>

[2021.05.04 - v1.0.0 - Chunel]

• 提供图化执行功能，支持非依赖节点并行计算

[2021.05.09 - v1.1.0 - Chunel]

• 优化图执行过程中的并发度

[2021.05.18 - v1.1.1 - Chunel]

• 添加节点name和session信息

[2021.05.23 - v1.2.0 - Chunel]

• 提供单节点循环执行功能

[2021.05.29 - v1.3.0 - Chunel]

• 提供cluster（簇）和region（区域）划分和循环执行功能
• 提供tutorial内容，包含多种使用样例

[2021.06.14 - v1.4.0 - Chunel]

• 提供param（参数）传递机制
• 提供group（组）功能，多节点模块统一继承自group模块
• 添加对Linux系统的的支持

[2021.06.20 - v1.4.1 - Chunel]

• 提供condition（条件）功能
• 添加对Windows系统的支持

[2021.06.24 - v1.5.0 - Chunel]

• 提供pipeline工厂创建方法
• 更新tutorial内容

[2021.07.07 - v1.5.1 - Chunel]

• 优化线程池功能。实现任务盗取机制

[2021.07.11 - v1.5.2 - Chunel]

• 优化线程池功能。实现线程数量自动调节机制

[2021.07.31 - v1.5.3 - Chunel]

• 优化线程池功能。实现任务批量获取功能，优化任务盗取机制

[2021.08.29 - v1.6.0 - Chunel]

• 提供多pipeline功能，优化底层逻辑
• 更新tutorial内容

[2021.09.19 - v1.6.1 - Chunel]

• 提供Lru算子、Trie算子和模板节点功能，优化底层逻辑
• 更新tutorial内容

[2021.09.29 - v1.7.0 - Chunel]

• 提供aspect(切面)功能，用于横向扩展node或group功能
• 更新tutorial内容

[2021.10.07 - v1.7.1 - Chunel]

• 优化aspect(切面)实现逻辑，提供切面参数功能，提供批量添加切面功能
• 更新tutorial内容

[2021.11.01 - v1.8.0 - Chunel]

• 提供adapter(适配器)功能，提供singleton适配器功能
• 优化pipeline执行逻辑
• 更新tutorial内容

[2021.12.18 - v1.8.1 - Chunel]

• 优化了返回值CStatus信息

[2022.01.02 - v1.8.2 - Chunel]

• 提供节点执行超时自动退出功能，提供task group(任务组)功能
• 提供线程池配置参数设置方法

[2022.01.23 - v1.8.3 - Chunel]

• 提供function适配器，实现函数式编程功能
• 提供线程优先级调度功能，提供线程绑定cpu执行功能
• 更新tutorial内容

[2022.01.31 - v1.8.4 - Chunel]

• 提供node(节点)异步执行的功能

[2022.02.03 - v1.8.5 - Chunel]

• 提供daemon(守护)功能，用于定时执行非流图中任务
• 更新tutorial内容

[2022.04.03 - v1.8.6 - Chunel]

• 提供DistanceCalculator算子，用于实现任意数据类型、任意距离类型的计算
• 更新tutorial内容

[2022.04.05 - v2.0.0 - Chunel]

• 提供domain(领域)功能，提供Ann领域抽象模型，开始支持个别专业方向
• 提供hold执行机制
• 更新tutorial内容

[2022.05.01 - v2.0.1 - Chunel]

• 优化pipeline注册机制，支持init方法自定义顺序执行
• 提供一键编译脚本

[2022.05.29 - v2.1.0 - Chunel]

• 提供element参数写入方法
• 提供针对C++14版本的支持
• 更新tutorial内容

[2022.10.03 - v2.1.1 - Chunel]

• 提供线程池中的任务优先级机制
• 优化group执行逻辑

[2022.11.03 - v2.2.0 - Chunel]

• 提供message(消息)功能，主要用于完成不同pipeline之间的数据传递
• 更新tutorial内容

[2022.12.24 - v2.2.1 - Chunel]

• 提供TemplateNode(模板节点)功能，用于优化参数传参方式
• 更新tutorial内容

[2022.12.25 - v2.2.2 - yeshenyong]

• 优化图执行逻辑

[2022.12.30 - v2.2.3 - Chunel]

• 提供message发布订阅功能
• 提供执行引擎切换功能

[2023.01.21 - v2.3.0 - Chunel]

• 提供event(事件)功能
• 提供CGraph Intro.xmind文件，通过脑图的方式，介绍了CGraph的整体逻辑

[2023.01.25 - v2.3.1 - Chunel]

• 提供针对C++11版本的支持。感谢 MirrorYuChen 提供相关解决方案

[2023.02.10 - v2.3.2 - Chunel]

• 优化调度策略，提供调度参数配置接口
• 提供英文版本readme.md

[2023.02.12 - v2.3.3 - yeshenyong, Chunel]

• 提供graphviz可视化图展示功能
• 提供参数链路追踪功能

[2023.02.22 - v2.3.4 - Chunel]

• 优化Windows系统下调度机制
• 优化param机制和event(事件)机制

[2023.03.25 - v2.4.0 - woodx, Chunel]

• 提供可运行的docker环境，和构建docker环境的dockerfile文件
• 提供pipeline调度资源管控机制
• 优化调度性能

[2023.05.05 - v2.4.1 - Chunel]

• 提供线程绑定执行功能
• 提供pipeline最大并发度获取方法。感谢 Hanano-Yuuki 提供相关解决方案
• 提供pipeline异步执行功能和执行时退出功能

[2023.06.17 - v2.4.2 - Chunel]

• 提供MultiCondition(多条件)功能
• 提供pipeline暂停执行和恢复执行功能

[2023.07.12 - v2.4.3 - Chunel]

• 优化CStatus功能，添加了异常定位信息

[2023.09.05 - v2.5.0 - Chunel]

• 提供perf功能，用于做pipeline的性能分析
• 提供element的超时机制
• 提供some(部分)功能，优化pipeline的异步执行方式

[2023.09.15 - v2.5.1 - Chunel]

• 提供fence(栅栏)功能
• 提供coordinator(协调)功能

[2023.11.06 - v2.5.2 - Chunel]

• 优化message(消息)功能，可以设定写入阻塞时的处理方式，减少内存copy次数
• 添加example相关内容，针对不同行业，提供一些简单实现
• 优化调度性能

[2023.11.15 - v2.5.3 - Chunel]

• 提供proto定义文件
• 添加mutable(异变)功能，提供依赖关系注册语法糖

[2024.01.05 - v2.5.4 - Chunel]

• 提供test内容，包含性能和功能方面的测试用例
• 优化event(事件)机制，支持异步等待功能

[2024.07.18 - v2.6.0 - PaPaPig-Melody, Chunel]

• 提供pipeline的拓扑执行的方式
• 提供判定element之间是否有依赖关系的方法
• 提供bazel编译方式
• 优化perf功能

[2024.09.17 - v2.6.1 - Chunel]

• 提供pipeline的静态执行的方式，提供基于静态执行的微任务机制
• 提供pipeline剪裁功能，用于删除element之间重复的依赖
• 提供element删除依赖的方法
• 优化event(事件)机制，异步事件可以等待结束
• 发布 CGraph-lite 项目，提供简单DAG构图和参数传递功能。接口完全兼容，可无缝切换至本项目

[2024.11.16 - v2.6.2 - Chunel]

• 优化参数互斥机制和获取性能
• 修复辅助线程异常等待问题
• 更新tutorial内容

[2025.03.16 - v3.0.0 - Chunel]

• 提供 Python 版本
• 提供stage(阶段)功能，用于element之间同步运行
• 更新tutorial内容

[2025.05.04 - v3.1.0 - Chunel]

• 提供 全量功能 Python 版本
• 提供 Python 和 C++ 混合编程功能
• 提供 Python 打包功能，支持 pip3 install PyCGraph 安装

[2025.06.15 - v3.1.1 - Chunel]

• 提供 C# 和 Java 版本
• 提供 CODE_OF_CONDUCT.md 文档

[2025.09.06 - v3.1.2 - Chunel]

• 提供 Go 版本
• 优化 message 功能
• 优化 aspect 功能

[2025.11.08 - v3.2.2 - Chunel]

• 提供 本地保存和加载 功能
• 修改 PyCGraph 为 pycgraph，支持 pip3 install pycgraph 安装

[2026.03.24 - v3.2.3 - Chunel]

• 优化 message 功能
• 优化 稳定性

[2026.05.10 - v3.2.4 - Chunel]

• 优化 pycgraph 功能

[2026.08.15 - v3.2.5 - Chunel]

• 优化调度性能
• 优化 pycgraph 功能
• 提供 lite 运行模式
• 修改 GSome 使用方式

[2026.10.24 - v3.3.0 - Chunel]

• 优化 GParam 的 trace 功能
• 优化 CStatus 的返回值功能
• 优化 pycgraph 功能，提供 message 功能，提供装饰器功能

</details>

---

<details> <summary><b>附录-2. 感谢</b></summary>

• 感谢 Doocs 微信公众号 刊登相关介绍文档，欢迎加入 Doocs 开源社区
• 感谢《HelloGithub》期刊介绍和推荐：HelloGithub 第70期

<p align="center"><img src="https://github.com/ChunelFeng/CGraph/blob/main/doc/image/HelloGithub%20Logo.gif"/></p>

• Thanks to the recommendation from awesome-cpp, we all know, it is the most authoritative recommendation list for cpp project in the world
• Thanks to the recommendation from Taskflow Group: awesome-parallel-computing, and we always treat taskflow as a role model
• Thanks to the recommendation from awesome-workflow-engines
• 感谢各位开发者 CONTRIBUTORS 为项目做出的贡献
• 感谢所有为CGraph项目提出的意见和建议的朋友，在此不一一提及。随时欢迎大家加入，一起共建

</details>

---

<details> <summary><b>附录-3. 联系方式</b></summary>

• 微信： ChunelFeng (欢迎扫描上方二维码，添加作者为好友。请简单备注个人信息^_^)
• 邮箱： chunel@foxmail.com
• 源码： https://github.com/ChunelFeng/CGraph
• 论坛： www.chunel.cn

</details>

---