add some pages

Author: symphony09

content/en/docs/examples/merge_sort.md

@@ -0,0 +1,104 @@
+---
+weight: 999
+title: "Parallel Merge Sort"
+description: ""
+icon: "article"
+date: "2025-05-04T22:58:38+08:00"
+lastmod: "2025-05-04T22:58:38+08:00"
+draft: false
+toc: true
+---
+
+## Example Description
+
+A primary use case for OGraph is accelerating parallel computations. Taking merge sort as an example, conventional merge sort algorithms do not leverage multi-core CPU parallelism.
+
+During the merge sort process, each subsequence needs to be sorted. If these sorts can be performed concurrently, it significantly reduces computation time.
+
+In this scenario, OGraph enables task parallelism without complicating the code structure.
+
+## Example Code
+
+The following code implements a parallelized merge sort. It first defines a merge function to combine two already sorted sequences.
+
+Then, it defines sorting tasks for subsequences, merges them into the final result using the merge function, and defines a validation task to check the final result.
+
+Finally, a pipeline is created, these tasks are registered, and the pipeline is executed.
+
+(For code brevity, standard library sorting is used for subsequences rather than recursively applying the merge function as in conventional merge sort.)
+
+```go
+package main
+
+import (
+	"context"
+	"fmt"
+	"log"
+	"math/rand"
+	"slices"
+	"sync"
+
+	"github.com/symphony09/ograph"
+)
+
+func merge(left, right []int) []int {
+	result := make([]int, 0, len(left)+len(right))
+	for len(left) > 0 || len(right) > 0 {
+		if len(left) == 0 {
+			return append(result, right...)
+		}
+		if len(right) == 0 {
+			return append(result, left...)
+		}
+		if left[0] < right[0] {
+			result = append(result, left[0])
+			left = left[1:]
+		} else {
+			result = append(result, right[0])
+			right = right[1:]
+		}
+	}
+	return result
+}
+
+func main() {
+	size := 1000
+	randomInts := make([]int, 0, size)
+	sortedInts := make([]int, 0, size)
+	mux := &sync.Mutex{}
+
+	for i := 0; i < size; i++ {
+		randomInts = append(randomInts, rand.Intn(10000))
+	}
+
+	sortTasks := make([]*ograph.Element, 0, 10)
+
+	for i := 0; i < 10; i++ {
+		part := randomInts[i*100 : (i+1)*100]
+
+		t := ograph.NewElement(fmt.Sprintf("t%d", i)).UseFn(func() error {
+			slices.Sort(part)
+			mux.Lock()
+			sortedInts = merge(sortedInts, part)
+			mux.Unlock()
+			return nil
+		})
+
+		sortTasks = append(sortTasks, t)
+	}
+
+	checkTask := ograph.NewElement("check").UseFn(func() error {
+		if len(sortedInts) != 1000 || !slices.IsSorted(sortedInts) {
+			return fmt.Errorf("got wrong sort result")
+		}
+		return nil
+	})
+
+	p := ograph.NewPipeline()
+	err := p.Register(checkTask, ograph.Rely(sortTasks...)).Run(context.Background(), nil)
+	if err != nil {
+		log.Fatalf("run merge sort pipeline failed, err: %v\n", err)
+	}
+
+	fmt.Println("result:", sortedInts)
+}

content/en/docs/features/event.md

@@ -0,0 +1,61 @@
+---
+weight: 202
+title: "Events"
+description: "How to send events and listen for events"
+icon: "article"
+date: "2025-04-20T17:38:13+08:00"
+lastmod: "2025-04-20T17:38:13+08:00"
+draft: false
+toc: true
+---
+
+Events are generally used for code decoupling. In OGraph, nodes can send events, and pipelines can listen for events sent by nodes.
+
+For example, a node can send an event representing an error occurrence. After the pipeline captures this event, it can report it via webhook.
+
+This way, nodes only need to focus on their business logic, and the pipeline layer doesn't need to handle errors for specific nodes.
+
+## Example
+
+To enable a node to send events, first make the node inherit (embed) ograph.BaseEventNode. Then the node can call the Emit method to send events.
+
+```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
+}
+```
+
+Then, listen and handle events in the 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 uses the github.com/symphony09/eventd library to implement the event mechanism. eventd.On("test") indicates listening for the "test" event, supporting regular expression matching for event names. For detailed usage, please refer to the eventd library's documentation.
+
+Output result:
+```
+get message from test event: hi, it is a test event.
+```
+
+## Synchronous and Asynchronous
+
+Following Go's philosophy, OGraph sends events synchronously by default. That is, `node.Emit()` will block the node. If you need asynchronous processing, use `go node.Emit()`.

content/en/docs/features/parallelism_limit.md

@@ -0,0 +1,58 @@
+---
+weight: 202
+title: "Parallelism Limit"
+description: "How to limit node parallelism"
+icon: "article"
+date: "2025-04-20T19:25:06+08:00"
+lastmod: "2025-04-20T19:25:06+08:00"
+draft: false
+toc: true
+---
+
+In the real world, resources are always limited. CPU resources are limited, memory capacity is limited, and network bandwidth is limited.
+
+If the pipeline node parallelism is too high, it may lead to:
+
+1. CPU: Severely impact other processes
+2. Memory: Out Of Memory (OOM)
+
+OGraph supports setting parallelism limits to avoid these issues.
+
+## Example
+
+```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)
+	}
+```
+
+Output result:
+
+```
+n1 running
+n1 stop
+n2 running
+n2 stop
+```
+
+From the output, you can see that although there's no dependency between n1 and n2 nodes, after setting the parallelism to 1, only one node can run at a time. Therefore, even if n1 node sleeps for 1 second, n2 cannot start during that period.
+
+{{< alert context="info" text="What's mentioned here as 'parallelism' is more accurately referred to as 'concurrency' in technical terms." />}}

content/en/docs/features/pause_continue_cancel.md

@@ -0,0 +1,78 @@
+---
+weight: 202
+title: "Pause, Continue, and Cancel"
+description: "How to pause, continue, and cancel a pipeline"
+icon: "article"
+date: "2025-04-20T15:22:48+08:00"
+lastmod: "2025-04-20T15:22:48+08:00"
+draft: false
+toc: true
+---
+
+## Example
+
+OGraph Pipeline supports pausing, resuming, and canceling execution. Here's an example:
+
+```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 running node b
+
+	time.Sleep(time.Second)
+
+	continueRun() // b continues running, after 1.5s (0.5+1), not 1s
+
+	time.Sleep(time.Millisecond * 500)
+
+	cancel() // cancel before running node c, so node c will never execute
+
+	err := wait() // wait for pipeline completion
+
+	fmt.Println(err) // should get context canceled error
+```
+
+## Execution Process
+
+The example code execution flow is as follows:
+
+```mermaid
+%%{init: { 'logLevel': 'debug', 'theme': 'default', 'timeline': {'disableMulticolor': true} } }%%
+timeline
+    title Execution process
+    0s~0.5s : Node a running
+    0.5s~1s : Node a finishes
+         : Pipeline pauses
+    1s~1.5s : Pipeline paused
+    1.5s~2s : Pipeline continues : Node b running
+    2s~2.5s : Node b finishes : Pipeline canceled
+```
+
+{{< alert context="info" text="Pausing does not affect nodes already running. If a node does not support cancellation, cancellation will not affect nodes already running." />}}

content/en/docs/features/priority.md

@@ -0,0 +1,51 @@
+---
+weight: 202
+title: "Priority Scheduling"
+description: "How to prioritize node execution when resources are limited"
+icon: "article"
+date: "2025-04-20T18:46:29+08:00"
+lastmod: "2025-04-20T18:46:29+08:00"
+draft: false
+toc: true
+---
+
+In resource-constrained scenarios, OGraph's priority scheduling feature allows important nodes to execute first.
+
+For example, in an image processing application that needs to process a batch of images of varying sizes, smaller images should be prioritized to process as many images as possible in a short time (smaller images take less time to process).
+
+In this scenario, it's necessary to limit concurrency and let smaller image tasks execute first. (In fully concurrent scenarios, large image tasks would consume CPU time from smaller tasks)
+
+## Example
+
+```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)
+	}
+```
+
+In the code above, `pipeline.ParallelismLimit = 1` limits concurrency. Without this limit, node n2 would still execute immediately.
+
+It's recommended to set concurrency limits for compute-intensive tasks to the number of CPU cores, and for tasks requiring significant memory or other resources, set it to total resources divided by average resource consumption per task.
+
+Output:
+
+```
+n1 running
+n2 running
+```