Skip to content

Commit 03b182a

Browse files
committed
docs: add docstrings
1 parent da1786a commit 03b182a

File tree

15 files changed

+267
-38
lines changed

15 files changed

+267
-38
lines changed

src/main/kotlin/dev/silenium/libs/flows/api/Extensions.kt

Lines changed: 14 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,20 @@ package dev.silenium.libs.flows.api
22

33
import kotlinx.coroutines.Job
44

5-
interface FlowGraphBuilder : FlowGraph {
5+
/**
6+
* ConfigScope for creating connections between [Source]s and [Sink]s in a [FlowGraph].
7+
*/
8+
interface FlowGraphConfigScope : FlowGraph {
9+
/**
10+
* Creates a connection job in the [kotlinx.coroutines.CoroutineScope] of the [FlowGraph].
11+
* The job is started immediately.
12+
*/
613
infix fun <T, P> Source<T, P>.connectTo(sink: Sink<T, P>): Result<Job>
714

8-
suspend fun finalize(): Result<Unit>
15+
/**
16+
* Configures the [FlowGraph].
17+
* Currently, it does:
18+
* - wait for all connection jobs to be started
19+
*/
20+
suspend fun configure(): Result<Unit>
921
}

src/main/kotlin/dev/silenium/libs/flows/api/FlowGraph.kt

Lines changed: 79 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,26 +2,102 @@ package dev.silenium.libs.flows.api
22

33
import kotlinx.coroutines.CoroutineScope
44

5+
/**
6+
* A [FlowGraph] is a directed graph of [FlowGraphElement]s.
7+
* It is used to create a flow of data between [Source]s, [Sink]s, and [Transformer]s.
8+
* The [FlowGraph] is a [CoroutineScope] which will contain all connections between the elements.
9+
* It is also an [AutoCloseable] to close all elements and cancel all connection jobs when the [FlowGraph] is closed.
10+
*
11+
* @see FlowGraphElement
12+
* @see Source
13+
* @see Sink
14+
* @see Transformer
15+
* @see CoroutineScope
16+
* @see AutoCloseable
17+
* @see SourceFlowGraphElement
18+
* @see SinkFlowGraphElement
19+
* @see TransformerFlowGraphElement
20+
* @see FlowGraphConfigScope
21+
*/
522
interface FlowGraph : AutoCloseable, CoroutineScope {
23+
/**
24+
* The list of [FlowGraphElement]s in the [FlowGraph].
25+
*/
626
val elements: List<FlowGraphElement<*>>
27+
28+
/**
29+
* The number of [FlowGraphElement]s in the [FlowGraph].
30+
*/
731
val size: Int
832

33+
/**
34+
* Adds a source to the [FlowGraph].
35+
* Don't use this for a [Transformer] which is a combined [Source] and [Sink].
36+
*
37+
* @param source The [Source] to add to the [FlowGraph].
38+
* @param name The name of the [SourceFlowGraphElement].
39+
* @return The [SourceFlowGraphElement] which was added to the [FlowGraph].
40+
* @see SourceFlowGraphElement
41+
* @see Source
42+
*/
943
fun <T, P, E : Source<T, P>> source(
1044
source: E,
1145
name: String = "${source.javaClass.name}-${size}",
1246
): SourceFlowGraphElement<T, P, E>
1347

48+
/**
49+
* Adds a sink to the [FlowGraph].
50+
* Don't use this for a [Transformer] which is a combined [Source] and [Sink].
51+
*
52+
* @param sink The [Sink] to add to the [FlowGraph].
53+
* @param name The name of the [SinkFlowGraphElement].
54+
* @return The [SinkFlowGraphElement] which was added to the [FlowGraph].
55+
* @see SinkFlowGraphElement
56+
* @see Sink
57+
*/
1458
fun <T, P, E : Sink<T, P>> sink(
1559
sink: E,
1660
name: String = "${sink.javaClass.name}-${size}",
1761
): SinkFlowGraphElement<T, P, E>
1862

63+
/**
64+
* Adds a transformer to the [FlowGraph].
65+
*
66+
* @param transform The [Transformer] to add to the [FlowGraph].
67+
* @param name The name of the [TransformerFlowGraphElement].
68+
* @return The [TransformerFlowGraphElement] which was added to the [FlowGraph].
69+
* @see TransformerFlowGraphElement
70+
* @see Transformer
71+
*/
1972
fun <IT, IP, OT, OP, E : Transformer<IT, IP, OT, OP>> transformer(
2073
transform: E,
2174
name: String = "${transform.javaClass.name}-${size}",
2275
): TransformerFlowGraphElement<IT, IP, OT, OP, E>
2376

24-
fun <E : Source<*, *>> source(name: String): FlowGraphElement<E>?
25-
fun <E : Sink<*, *>> sink(name: String): FlowGraphElement<E>?
26-
fun <E : Transformer<*, *, *, *>> transformer(name: String): FlowGraphElement<E>?
77+
/**
78+
* Gets a [SourceFlowGraphElement] by its name.
79+
*
80+
* @param name The name of the [SourceFlowGraphElement].
81+
* @return The [SourceFlowGraphElement] with the given name or `null` if it doesn't exist.
82+
* @see SourceFlowGraphElement
83+
*/
84+
fun <E : Source<*, *>> source(name: String): SourceFlowGraphElement<*, *, E>?
85+
86+
/**
87+
* Gets a [SinkFlowGraphElement] by its name.
88+
*
89+
* @param name The name of the [SinkFlowGraphElement].
90+
* @return The [SinkFlowGraphElement] with the given name or `null` if it doesn't exist.
91+
* @see SinkFlowGraphElement
92+
*/
93+
fun <E : Sink<*, *>> sink(name: String): SinkFlowGraphElement<*, *, E>?
94+
95+
/**
96+
* Gets a [TransformerFlowGraphElement] by its name.
97+
*
98+
* @param name The name of the [TransformerFlowGraphElement].
99+
* @return The [TransformerFlowGraphElement] with the given name or `null` if it doesn't exist.
100+
* @see TransformerFlowGraphElement
101+
*/
102+
fun <E : Transformer<*, *, *, *>> transformer(name: String): TransformerFlowGraphElement<*, *, *, *, E>?
27103
}

src/main/kotlin/dev/silenium/libs/flows/api/FlowGraphElement.kt

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,10 @@ package dev.silenium.libs.flows.api
22

33
import kotlin.reflect.KClass
44

5+
/**
6+
* A [FlowGraphElement] is a single element in a [FlowGraph].
7+
* It wraps the concrete implementation of a [Source], [Sink], or [Transformer].
8+
*/
59
interface FlowGraphElement<T : Any> : AutoCloseable {
610
val name: String
711
val type: KClass<T>
@@ -10,7 +14,18 @@ interface FlowGraphElement<T : Any> : AutoCloseable {
1014
override fun close()
1115
}
1216

17+
/**
18+
* A [FlowGraphElement] which is a [Source].
19+
*/
1320
interface SourceFlowGraphElement<T, P, S : Source<T, P>> : FlowGraphElement<S>, Source<T, P>
21+
22+
/**
23+
* A [FlowGraphElement] which is a [Sink].
24+
*/
1425
interface SinkFlowGraphElement<T, P, S : Sink<T, P>> : FlowGraphElement<S>, Sink<T, P>
26+
27+
/**
28+
* A [FlowGraphElement] which is a [Transformer].
29+
*/
1530
interface TransformerFlowGraphElement<IT, IP, OT, OP, T : Transformer<IT, IP, OT, OP>> :
1631
FlowGraphElement<T>, Transformer<IT, IP, OT, OP>
Lines changed: 31 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,44 @@
11
package dev.silenium.libs.flows.api
22

3-
data class FlowItem<T, P>(val pad: UInt, val metadata: P, val value: T) : ReferenceCounted<FlowItem<T, P>> {
3+
/**
4+
* Wraps the actual data of a flow item and contains its metadata and pad id.
5+
*
6+
* @param T The type of the data.
7+
* @param P The type of the metadata.
8+
* @property pad The pad id of the flow item.
9+
* @property metadata The metadata of the flow item.
10+
* @property value The actual data of the flow item.
11+
* @see Reference
12+
* @see AutoCloseable
13+
*/
14+
data class FlowItem<T, P>(val pad: UInt, val metadata: P, val value: T) : Reference<FlowItem<T, P>> {
15+
/**
16+
* Clones the flow item.
17+
* If value and/or metadata are [Reference], they are cloned as well.
18+
*/
419
@Suppress("UNCHECKED_CAST")
520
override fun clone(): Result<FlowItem<T, P>> {
6-
return when (value) {
7-
is ReferenceCounted<*> -> value.clone().map { FlowItem(pad, metadata, it as T) }
8-
else -> Result.success(this)
21+
val clonedValue = when (value) {
22+
is Reference<*> -> value.clone() as T
23+
else -> value
924
}
25+
val clonedMetadata = when (metadata) {
26+
is Reference<*> -> metadata.clone() as P
27+
else -> metadata
28+
}
29+
return Result.success(FlowItem(pad, clonedMetadata, clonedValue))
1030
}
1131

32+
/**
33+
* Closes the flow item.
34+
* If value and/or metadata are [AutoCloseable], they are closed as well.
35+
*/
1236
override fun close() {
1337
if (value is AutoCloseable) {
1438
(value as AutoCloseable).close()
1539
}
40+
if (metadata is AutoCloseable) {
41+
(metadata as AutoCloseable).close()
42+
}
1643
}
1744
}
Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
package dev.silenium.libs.flows.api
2+
3+
/**
4+
* A reference to a resource.
5+
* The resource is closed when the reference count reaches zero and it implements [AutoCloseable].
6+
*
7+
* @param T The type of the underlying resource.
8+
* @see AutoCloseable
9+
*/
10+
interface Reference<T : Reference<T>> : AutoCloseable {
11+
/**
12+
* Creates a new reference to the underlying resource.
13+
*/
14+
fun clone(): Result<T>
15+
16+
/**
17+
* Destroys the reference to the underlying resource.
18+
* If the reference count reaches zero, the resource is closed.
19+
*/
20+
override fun close()
21+
}

src/main/kotlin/dev/silenium/libs/flows/api/ReferenceCounted.kt

Lines changed: 0 additions & 5 deletions
This file was deleted.

src/main/kotlin/dev/silenium/libs/flows/api/Sink.kt

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,17 @@ package dev.silenium.libs.flows.api
22

33
import kotlinx.coroutines.flow.FlowCollector
44

5+
/**
6+
* A [Sink] is a flow element that consumes flow items.
7+
* It can be configured with metadata for each input pad.
8+
* It can be closed to release resources.
9+
*
10+
* @param T The type of the data.
11+
* @param P The type of the metadata.
12+
* @see FlowCollector
13+
* @see AutoCloseable
14+
* @see FlowItem
15+
*/
516
interface Sink<T, P> : FlowCollector<FlowItem<T, P>>, AutoCloseable {
617
val inputMetadata: Map<UInt, P?>
718

src/main/kotlin/dev/silenium/libs/flows/api/Source.kt

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,17 @@ package dev.silenium.libs.flows.api
22

33
import kotlinx.coroutines.flow.Flow
44

5+
/**
6+
* A [Source] is a flow element that produces flow items.
7+
* It can be queried for metadata for each output pad.
8+
* It can be closed to release resources.
9+
*
10+
* @param T The type of the data.
11+
* @param P The type of the metadata.
12+
* @see AutoCloseable
13+
* @see FlowItem
14+
* @see Flow
15+
*/
516
interface Source<T, P> : AutoCloseable {
617
val outputMetadata: Map<UInt, P>
718
val flow: Flow<FlowItem<T, P>>
Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,14 @@
11
package dev.silenium.libs.flows.api
22

3+
/**
4+
* A [Transformer] is a flow element that transforms flow items.
5+
* It is simply both a [Sink] and a [Source].
6+
*
7+
* @param IT The type of the input data.
8+
* @param IP The type of the input metadata.
9+
* @param OT The type of the output data.
10+
* @param OP The type of the output metadata.
11+
* @see Sink
12+
* @see Source
13+
*/
314
interface Transformer<IT, IP, OT, OP> : Sink<IT, IP>, Source<OT, OP>

src/main/kotlin/dev/silenium/libs/flows/base/SourceBase.kt

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,13 @@ import dev.silenium.libs.flows.api.Source
55
import dev.silenium.libs.flows.impl.CloningFlow
66
import java.util.*
77

8+
/**
9+
* A base class for [Source] implementations.
10+
* It provides a [CloningFlow] to publish flow items.
11+
* It also provides a [metadata] map to store metadata for each output pad.
12+
* It implements the [Source] interface.
13+
* It is an [AutoCloseable] resource.
14+
*/
815
abstract class SourceBase<T, P> : Source<T, P> {
916
override val outputMetadata: Map<UInt, P> get() = metadata.toMap()
1017
override val flow = CloningFlow<FlowItem<T, P>>()

0 commit comments

Comments
 (0)