docs: add README and Simple example

Author: silenium-dev

README.md

@@ -0,0 +1,22 @@
+# kotlin-flow-graph
+
+A simple flow graph implementation in Kotlin.
+It allows you to create a graph of processing nodes that can be connected together to form a processing pipeline.
+
+## Usage
+
+Gradle:
+
+```kotlin
+repositories {
+    maven("https://repo.silenium.dev/releases")
+}
+
+dependencies {
+    implementation("dev.silenium.libs.flow-graph:kotlin-flow-graph:0.1.0")
+}
+```
+
+Examples:
+
+- [Simple](./examples/src/main/kotlin/dev/silenium/libs/flows/examples/Simple.kt)

build.gradle.kts

@@ -15,10 +15,10 @@ repositories {
 
 dependencies {
     val coroutines = "1.8.1"
-    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:$coroutines")
-    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-debug:$coroutines")
-    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-jdk8:$coroutines")
-    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-reactive:$coroutines")
+    api("org.jetbrains.kotlinx:kotlinx-coroutines-core:$coroutines")
+    api("org.jetbrains.kotlinx:kotlinx-coroutines-debug:$coroutines")
+    api("org.jetbrains.kotlinx:kotlinx-coroutines-jdk8:$coroutines")
+    api("org.jetbrains.kotlinx:kotlinx-coroutines-reactive:$coroutines")
 
     val kotest = "5.9.1"
     testImplementation("io.kotest:kotest-runner-junit5-jvm:$kotest")

examples/build.gradle.kts

@@ -0,0 +1,11 @@
+plugins {
+    kotlin("jvm")
+}
+
+repositories {
+    mavenCentral()
+}
+
+dependencies {
+    implementation(project(":"))
+}

examples/src/main/kotlin/dev/silenium/libs/flows/examples/Simple.kt

@@ -0,0 +1,81 @@
+package dev.silenium.libs.flows.examples
+
+import dev.silenium.libs.flows.api.FlowItem
+import dev.silenium.libs.flows.api.Sink
+import dev.silenium.libs.flows.api.Transformer
+import dev.silenium.libs.flows.base.SourceBase
+import dev.silenium.libs.flows.impl.FlowGraph
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.runBlocking
+
+data class MyData(val value: Int)
+data class MyMetadata(val negativeNumbers: Boolean)
+
+// A simple source that publishes numbers from 0 to 100 to two different output pads
+class MySource : SourceBase<MyData, MyMetadata>() {
+    init {
+        // Create two output pads, one for positive numbers and one for negative numbers
+        metadata[0u] = MyMetadata(false)
+        metadata[1u] = MyMetadata(true)
+    }
+
+    // Publish numbers from 0 to 100
+    // Publishing can be done from any thread/coroutine, as the flow is thread-safe
+    suspend fun run() {
+        for (i in 0..100) {
+            if (i % 2 == 0) {
+                publish(FlowItem(0u, metadata[0u]!!, MyData(i)))
+            } else {
+                publish(FlowItem(1u, metadata[1u]!!, MyData(i)))
+            }
+        }
+    }
+}
+
+// A simple processor that doubles the value of the input data
+class MyTransformer : Transformer<MyData, MyMetadata, MyData, MyMetadata>, SourceBase<MyData, MyMetadata>() {
+    private val inputMetadata_ = mutableMapOf<UInt, MyMetadata?>()
+    override val inputMetadata: Map<UInt, MyMetadata?> get() = inputMetadata_
+
+    override fun configure(pad: UInt, metadata: MyMetadata): Result<Unit> {
+        inputMetadata_[pad] = metadata
+        this.metadata[pad] = metadata
+        return Result.success(Unit)
+    }
+
+    override suspend fun receive(item: FlowItem<MyData, MyMetadata>): Result<Unit> = runCatching {
+        publish(FlowItem(item.pad, item.metadata, MyData(item.value.value * 2)))
+    }
+}
+
+// A simple sink that prints the received data
+class MySink : Sink<MyData, MyMetadata> {
+    private val inputMetadata_ = mutableMapOf<UInt, MyMetadata?>()
+    override val inputMetadata: Map<UInt, MyMetadata?> get() = inputMetadata_
+
+    override suspend fun receive(item: FlowItem<MyData, MyMetadata>): Result<Unit> = runCatching {
+        println("Received $item")
+    }
+
+    override fun close() {
+        println("Sink closed")
+    }
+
+    override fun configure(pad: UInt, metadata: MyMetadata): Result<Unit> {
+        inputMetadata_[pad] = metadata
+        return Result.success(Unit)
+    }
+}
+
+fun main() = runBlocking {
+    val graph = FlowGraph(Dispatchers.Default) {
+        val source = source(MySource(), "source")
+        val processor = transformer(MyTransformer(), "transformer")
+        val sink = sink(MySink(), "sink")
+
+        source.connectTo(processor).getOrThrow()
+        processor.connectTo(sink).getOrThrow()
+    }
+    graph.source<MySource>("source")!!.impl.run()
+    graph.close()
+}

settings.gradle.kts

@@ -2,3 +2,5 @@ plugins {
     id("org.gradle.toolchains.foojay-resolver-convention") version "0.8.0"
 }
 rootProject.name = "kotlin-flow-graph"
+
+include(":examples")