add some pages

Author: symphony09

content/zh/docs/features/event.md

@@ -0,0 +1,62 @@
+---
+weight: 202
+title: "事件"
+description: "关于如何发送事件和监听事件"
+icon: "article"
+date: "2025-04-20T17:38:13+08:00"
+lastmod: "2025-04-20T17:38:13+08:00"
+draft: false
+toc: true
+---
+
+事件一般用于代码解耦。在 OGraph 中，可以让节点发送事件，然后在 pipeline 上监听节点所发送的事件。
+
+例如，节点可以发送一个代表发生了错误的事件，pipeline 捕获到这个事件后可以通过 webhook 上报。
+
+这样节点只要专注于自己的业务逻辑，在 pipeline 层面也不用针对某个节点做错误处理。
+
+## 示例
+
+要让节点支持发送事件，那么首先需要让节点继承（内嵌）ograph.BaseEventNode，然后节点就可以调用 Emit 方法发送事件了。
+
+```go
+type TEventNode struct {
+	ograph.BaseEventNode
+}
+
+func (node *TEventNode) Run(ctx context.Context, state ogcore.State) error {
+	state.Set("msg", "hi, it is a test event.")
+	node.Emit("test", state) // pass event info by state
+	return nil
+}
+```
+
+然后就是在 pipeline 中监听和处理事件了。
+
+```go
+	pipeline := ograph.NewPipeline()
+
+	pipeline.Subscribe(func(event string, obj ogcore.State) bool {
+		msg, _ := obj.Get("msg")
+		fmt.Printf("get message from %s event: %v\n", event, msg)
+		return true
+	}, eventd.On("test"))
+
+	pipeline.Register(ograph.NewElement("n").UseNode(&TEventNode{}))
+
+	if err := pipeline.Run(context.Background(), nil); err != nil {
+		fmt.Println(err)
+	}
+```
+
+OGraph 使用了 github.com/symphony09/eventd 库来实现事件机制，eventd.On("test") 表示监听 test 事件，支持正则匹配事件名，详细用法可以参考 eventd 库的文档。
+
+输出结果如下：
+
+```
+get message from test event: hi, it is a test event.
+```
+
+## 同步和异步
+
+遵循 go 的哲学， OGraph 发送事件默认是同步的。也就是说 `node.Emit()` 会阻塞节点，如果你需要异步，那么就用 `go node.Emit()`。

content/zh/docs/features/parallelism_limit.md

@@ -0,0 +1,58 @@
+---
+weight: 202
+title: "并发度限制"
+description: "关于如何限制节点并发度"
+icon: "article"
+date: "2025-04-20T19:25:06+08:00"
+lastmod: "2025-04-20T19:25:06+08:00"
+draft: false
+toc: true
+---
+
+在现实世界中，资源总是受限的。CPU 资源是受限的，内存容量是受限的，网络带宽是受限的。
+
+所以如果 pipeline 节点并发度过高可能出现：
+
+1. CPU：严重影响其他进程运行
+2. 内存：OOM
+
+OGraph 支持设置并发度限制来避免这些问题。
+
+## 示例
+
+```go
+	pipeline := ograph.NewPipeline()
+
+	n1 := ograph.NewElement("n1").UseFn(func() error {
+		fmt.Println("n1 running")
+		time.Sleep(time.Second)
+		fmt.Println("n1 stop")
+		return nil
+	})
+
+	n2 := ograph.NewElement("n2").UseFn(func() error {
+		fmt.Println("n2 running")
+		fmt.Println("n2 stop")
+		return nil
+	})
+	pipeline.Register(n1).Register(n2)
+
+	pipeline.ParallelismLimit = 1
+
+	if err := pipeline.Run(context.Background(), nil); err != nil {
+		fmt.Println(err)
+	}
+```
+
+输出结果：
+
+```
+n1 running
+n1 stop
+n2 running
+n2 stop
+```
+
+从输出结果可以看到，虽然 n1 节点和 n2 节点之间没有依赖关系，但在设置并发度为一后，同一时间只能有一个节点在运行。因此即使 n1 节点陷入睡眠了 1 秒，期间 n2 也不能开始运行。
+
+{{< alert context="info" text="这里说的并发度，更准确的说，应该是指并行度。" />}}

content/zh/docs/features/pause_continue_cancel.md

@@ -0,0 +1,79 @@
+---
+weight: 202
+title: "暂停、继续和取消"
+description: "关于如何暂停、继续和取消 pipeline"
+icon: "article"
+date: "2025-04-20T15:22:48+08:00"
+lastmod: "2025-04-20T15:22:48+08:00"
+draft: false
+toc: true
+---
+
+## 示例
+
+OGraph Pipeline 支持暂停运行、继续运行和取消运行，示例代码如下：
+
+```go
+	pipeline := ograph.NewPipeline()
+
+	var startTime time.Time
+
+	a := ograph.NewElement("a").UseFn(func() error {
+		fmt.Println("a running")
+		startTime = time.Now()
+		time.Sleep(time.Second)
+		return nil
+	})
+
+	b := ograph.NewElement("b").UseFn(func() error {
+		fmt.Println("b running, after", time.Since(startTime))
+		time.Sleep(time.Second)
+		return nil
+	})
+
+	c := ograph.NewElement("c").UseFn(func() error {
+		fmt.Println("c running, after", time.Since(startTime))
+		return nil
+	})
+
+	pipeline.Register(a).Register(b, ograph.Rely(a)).Register(c, ograph.Rely(b))
+
+	ctx, cancel := context.WithCancel(context.Background())
+
+	pause, continueRun, wait := pipeline.AsyncRun(ctx, nil)
+
+	time.Sleep(time.Millisecond * 500)
+
+	pause() // pause before run node b
+
+	time.Sleep(time.Second)
+
+	continueRun() // b continue run, after 1.5s (0.5+1), not 1s
+
+	time.Sleep(time.Millisecond * 500)
+
+	cancel() // cancel before run node c, so node c will never be ran
+
+	err := wait() // wait pipeline finish
+
+	fmt.Println(err) // should get context canceled err
+```
+
+## 流程图
+
+示例代码运行过程如下：
+
+```mermaid
+%%{init: { 'logLevel': 'debug', 'theme': 'default', 'timeline': {'disableMulticolor': true} } }%%
+timeline
+    title Execution process
+    0s~0.5s : Node a running
+    0.5s~1s : Node a finish
+         : Pipeline pause
+    1s~1.5s : Pipeline pause
+    1.5s~2s : Pipeline continue : Node b running
+    2s~2.5s : Node b finish : Pipeline cancel
+
+```
+
+{{< alert context="info" text="暂停不会影响正在运行中的节点。如果节点本身不支持取消，那么取消也不会影响运行中的节点。" />}}

content/zh/docs/features/priority.md

@@ -0,0 +1,51 @@
+---
+weight: 202
+title: "优先级调度"
+description: "关于如何在资源有限的情况下使节点分优先级调度"
+icon: "article"
+date: "2025-04-20T18:46:29+08:00"
+lastmod: "2025-04-20T18:46:29+08:00"
+draft: false
+toc: true
+---
+
+在某些资源受限的情况下，可以使用 OGraph 提供的优先级调度功能，使得重要节点优先执行。
+
+例如在图片处理程序中，需要对一批图片进行计算处理。这些图片大小不一，希望优先处理小图片，这样在短时间内可以处理尽可能多的图片（图片越小，处理越快）。
+
+这种情况下就需要限制并发度，并且让小图片任务先执行。（在完全并发情况下，大图片任务会挤占小图片任务的CPU时间）
+
+## 示例
+
+```go
+	pipeline := ograph.NewPipeline()
+
+	n1 := ograph.NewElement("n1").UseFn(func() error {
+		fmt.Println("n1 running")
+		return nil
+	}).SetPriority(99)
+
+	n2 := ograph.NewElement("n2").UseFn(func() error {
+		fmt.Println("n2 running")
+		return nil
+	}).SetPriority(1)
+
+	pipeline.Register(n1).Register(n2)
+
+	pipeline.ParallelismLimit = 1
+
+	if err := pipeline.Run(context.Background(), nil); err != nil {
+		fmt.Println(err)
+	}
+```
+
+上面代码中用 `pipeline.ParallelismLimit = 1` 限制了并发度，如果不限制并发度，节点 n2 还是会马上执行。
+
+建议对计算密集任务限制并发度为 CPU 核数，对于需要占用大量内存或者其他资源的任务，设置为总的资源量除于任务平均消耗量。
+
+输出结果：
+
+```
+n1 running
+n2 running
+```

content/zh/docs/features/sub_pipeline.md

@@ -0,0 +1,59 @@
+---
+weight: 201
+title: "子 Pipeline"
+description: "关于如何嵌套子 pipeline"
+icon: "article"
+date: "2025-04-20T18:19:09+08:00"
+lastmod: "2025-04-20T18:19:09+08:00"
+draft: false
+toc: true
+---
+
+OGraph 支持嵌套子 Pipeline 来分治复杂的工作流，并且对嵌套深度没有限制。
+
+## 示例
+
+实现嵌套 pipeline 是非常简单的，只要声明一个 pipeline，然后像普通节点一样在另一个 pipeline 中注册它就可以了。
+
+```go
+	study := newSubPipeline("LearnProgramming", "LearnEnglish")
+	relax := newSubPipeline("PlayGame", "Sleep")
+
+	studyThings := ograph.NewElement("StudyThings").UseNode(study)
+	relaxThings := ograph.NewElement("RelaxThings").UseNode(relax)
+
+	day := ograph.NewPipeline()
+	day.Register(studyThings).Register(relaxThings, ograph.Rely(studyThings))
+
+	if err := day.Run(context.TODO(), nil); err != nil {
+		fmt.Println(err)
+	}
+```
+
+上面代码中，创建了两个子 pipeline，模拟两类事情，然后再在主 pipeline 中注册为两个节点，并指定依赖关系。
+
+为了代码简洁，构建子pipeline的逻辑放到了一个函数中，实际上和一般的创建过程没有任何区别
+
+```go
+func newSubPipeline(things ...string) *ograph.Pipeline {
+	pipeline := ograph.NewPipeline()
+
+	for _, thing := range things {
+		thing := thing
+		pipeline.Register(ograph.NewElement(thing).UseFn(func() error {
+			fmt.Printf("->%s", thing)
+			return nil
+		}))
+	}
+
+	return pipeline
+}
+```
+
+输出结果：
+
+```
+->LearnEnglish->LearnProgramming->Sleep->PlayGame
+```
+
+子pipeline内部节点没有指定依赖关系，随机顺序打印，主 pipeline 指定了子 pipeline 的依赖关系，以固定顺序打印。