Add readme example

hovsep · Nov 10, 2024 · a144c8f · a144c8f
1 parent dc44d92
commit a144c8f
Show file tree

Hide file tree

Showing 2 changed files with 106 additions and 52 deletions.
diff --git a/README.md b/README.md
@@ -6,78 +6,71 @@
 </div>
 
 <h1>What is it?</h1>
-<p>F-Mesh is a simplistic FBP-inspired framework in Go. 
-It allows you to express your program as a mesh of interconnected components (or more formally as computational graph).
-You can think of it as a simple functions orchestrator.
+<p>F-Mesh is a functions orchestrator inspired by FBP. 
+It allows you to express your program as a mesh of interconnected components (or more formally as a computational graph).
 </p>
 <h3>Main concepts:</h3>
 <ul>
 <li>F-Mesh consists of multiple <b>Components</b> - the main building blocks</li>
-<li>Components have unlimited number of input and output <p>Ports</p></li>
-<li>The main job of each component is to read inputs and provide outputs</li>
+<li>Components have unlimited number of input and output <b>Ports</b></li>
 <li>Any output port can be connected to any input port via <b>Pipes</b></li>
-<li>The component behaviour is defined by its <b>Activation function</b></li>
-<li>The framework checks when components are ready to be activated and calls their activation functions concurrently</li>
-<li>One such iteration is called <b>Activation cycle</b></li>
-<li>On each activation cycle the framework does same things: activates all the components ready for activation, flushes the data through pipes and disposes input <b>Signals (the data chunks flowing between components)</b></li>
-<li>Ports and pipes are type agnostic, any data can be transferred or aggregated on any port</li>
-<li>The framework works in discrete time, not it wall time. The quant of time is 1 activation cycle, which gives you "logical parallelism" out of the box</li>
-<li>F-Mesh is suitable for prototyping, simulation, functional-style computations and implementing concurrency patterns without using the concurrency primitives like channels or any sort of locks</li>
+<li>Ports and pipes are type agnostic, any data can be transferred to any port</li>
+<li>The framework works in discrete time, not it wall time. The quant of time is 1 activation cycle, which gives you "logical parallelism" out of the box (activation function is running in "frozen time")</li>
 </ul>
 
 <h1>What it is not?</h1>
-<p>F-mesh is not a classical FBP implementation, and it is not fully async. It does not support long-running components or wall-time events (like timers and tickers)</p>
+<p>F-mesh is not a classical FBP implementation, it does not support long-running components or wall-time events (like timers and tickers)</p>
 
 
 <h2>Example:</h2>
 
 ```go
 fm := fmesh.New("hello world").
-			WithComponents(
-				component.New("concat").
-					WithInputs("i1", "i2").
-					WithOutputs("res").
-					WithActivationFunc(func(inputs *port.Collection, outputs *port.Collection) error {
-						word1 := inputs.ByName("i1").FirstSignalPayloadOrDefault("").(string)
-						word2 := inputs.ByName("i2").FirstSignalPayloadOrDefault("").(string)
+		WithComponents(
+			component.New("concat").
+				WithInputs("i1", "i2").
+				WithOutputs("res").
+				WithActivationFunc(func(inputs *port.Collection, outputs *port.Collection) error {
+					word1 := inputs.ByName("i1").FirstSignalPayloadOrDefault("").(string)
+					word2 := inputs.ByName("i2").FirstSignalPayloadOrDefault("").(string)
 
-						outputs.ByName("res").PutSignals(signal.New(word1 + word2))
-						return nil
-					}),
-				component.New("case").
-					WithInputs("i1").
-					WithOutputs("res").
-					WithActivationFunc(func(inputs *port.Collection, outputs *port.Collection) error {
-						inputString := inputs.ByName("i1").FirstSignalPayloadOrDefault("").(string)
+					outputs.ByName("res").PutSignals(signal.New(word1 + word2))
+					return nil
+				}),
+			component.New("case").
+				WithInputs("i1").
+				WithOutputs("res").
+				WithActivationFunc(func(inputs *port.Collection, outputs *port.Collection) error {
+					inputString := inputs.ByName("i1").FirstSignalPayloadOrDefault("").(string)
 
-						outputs.ByName("res").PutSignals(signal.New(strings.ToTitle(inputString)))
-						return nil
-					})).
-			WithConfig(fmesh.Config{
-				ErrorHandlingStrategy: fmesh.StopOnFirstErrorOrPanic,
-				CyclesLimit:           10,
-			})
+					outputs.ByName("res").PutSignals(signal.New(strings.ToTitle(inputString)))
+					return nil
+				})).
+		WithConfig(fmesh.Config{
+			ErrorHandlingStrategy: fmesh.StopOnFirstErrorOrPanic,
+			CyclesLimit:           10,
+		})
 
-		fm.Components().ByName("concat").Outputs().ByName("res").PipeTo(
-			fm.Components().ByName("case").Inputs().ByName("i1"),
-		)
+	fm.Components().ByName("concat").Outputs().ByName("res").PipeTo(
+		fm.Components().ByName("case").Inputs().ByName("i1"),
+	)
 
-		// Init inputs
-		fm.Components().ByName("concat").Inputs().ByName("i1").PutSignals(signal.New("hello "))
-		fm.Components().ByName("concat").Inputs().ByName("i2").PutSignals(signal.New("world !"))
+	// Init inputs
+	fm.Components().ByName("concat").InputByName("i1").PutSignals(signal.New("hello "))
+	fm.Components().ByName("concat").InputByName("i2").PutSignals(signal.New("world !"))
 
-		// Run the mesh
-		_, err := fm.Run()
+	// Run the mesh
+	_, err := fm.Run()
 
-		// Check for errors
-		if err != nil {
-			fmt.Println("F-Mesh returned an error")
-			os.Exit(1)
-		}
+	// Check for errors
+	if err != nil {
+		fmt.Println("F-Mesh returned an error")
+		os.Exit(1)
+	}
 
-		//Extract results
-		results := fm.Components().ByName("case").Outputs().ByName("res").FirstSignalPayloadOrNil()
-		fmt.Printf("Result is :%v", results)
+	//Extract results
+	results := fm.Components().ByName("case").OutputByName("res").FirstSignalPayloadOrNil()
+	fmt.Printf("Result is : %v", results)
 ```
-
+See more in ```examples``` directory.
 <h2>Version 0.1.0 coming soon</h2>
diff --git a/examples/strings_processing/main.go b/examples/strings_processing/main.go
@@ -0,0 +1,61 @@
+package main
+
+import (
+	"fmt"
+	"github.com/hovsep/fmesh"
+	"github.com/hovsep/fmesh/component"
+	"github.com/hovsep/fmesh/port"
+	"github.com/hovsep/fmesh/signal"
+	"os"
+	"strings"
+)
+
+// This example is used in readme.md
+func main() {
+	fm := fmesh.New("hello world").
+		WithComponents(
+			component.New("concat").
+				WithInputs("i1", "i2").
+				WithOutputs("res").
+				WithActivationFunc(func(inputs *port.Collection, outputs *port.Collection) error {
+					word1 := inputs.ByName("i1").FirstSignalPayloadOrDefault("").(string)
+					word2 := inputs.ByName("i2").FirstSignalPayloadOrDefault("").(string)
+
+					outputs.ByName("res").PutSignals(signal.New(word1 + word2))
+					return nil
+				}),
+			component.New("case").
+				WithInputs("i1").
+				WithOutputs("res").
+				WithActivationFunc(func(inputs *port.Collection, outputs *port.Collection) error {
+					inputString := inputs.ByName("i1").FirstSignalPayloadOrDefault("").(string)
+
+					outputs.ByName("res").PutSignals(signal.New(strings.ToTitle(inputString)))
+					return nil
+				})).
+		WithConfig(fmesh.Config{
+			ErrorHandlingStrategy: fmesh.StopOnFirstErrorOrPanic,
+			CyclesLimit:           10,
+		})
+
+	fm.Components().ByName("concat").Outputs().ByName("res").PipeTo(
+		fm.Components().ByName("case").Inputs().ByName("i1"),
+	)
+
+	// Init inputs
+	fm.Components().ByName("concat").InputByName("i1").PutSignals(signal.New("hello "))
+	fm.Components().ByName("concat").InputByName("i2").PutSignals(signal.New("world !"))
+
+	// Run the mesh
+	_, err := fm.Run()
+
+	// Check for errors
+	if err != nil {
+		fmt.Println("F-Mesh returned an error")
+		os.Exit(1)
+	}
+
+	//Extract results
+	results := fm.Components().ByName("case").OutputByName("res").FirstSignalPayloadOrNil()
+	fmt.Printf("Result is : %v", results)
+}