Release 0.5.1

README.md

@@ -23,13 +23,13 @@ the project!
 To test Ox, use the following dependency, using either [sbt](https://www.scala-sbt.org):
 
 ```scala
-"com.softwaremill.ox" %% "core" % "0.5.0"
+"com.softwaremill.ox" %% "core" % "0.5.1"
 ```
 
 Or [scala-cli](https://scala-cli.virtuslab.org):
 
 ```scala
-//> using dep "com.softwaremill.ox::core:0.5.0"
+//> using dep "com.softwaremill.ox::core:0.5.1"
 ```
 
 Documentation is available at [https://ox.softwaremill.com](https://ox.softwaremill.com), ScalaDocs can be browsed at [https://javadoc.io](https://www.javadoc.io/doc/com.softwaremill.ox).

generated-doc/out/basics/start-here.md

@@ -4,10 +4,10 @@
 
 ```scala
 // sbt dependency
-"com.softwaremill.ox" %% "core" % "0.5.0"
+"com.softwaremill.ox" %% "core" % "0.5.1"
 
 // scala-cli dependency
-//> using dep com.softwaremill.ox::core:0.5.0
+//> using dep com.softwaremill.ox::core:0.5.1
 ```
 
 ## Scope of the Ox project

generated-doc/out/kafka.md

@@ -3,7 +3,7 @@
 Dependency:
 
 ```scala
-"com.softwaremill.ox" %% "kafka" % "0.5.0"
+"com.softwaremill.ox" %% "kafka" % "0.5.1"
 ```
 
 `Flow`s which read from a Kafka topic, mapping stages and drains which publish to Kafka topics are available through

generated-doc/out/mdc-logback.md

@@ -3,7 +3,7 @@
 Dependency:
 
 ```scala
-"com.softwaremill.ox" %% "mdc-logback" % "0.5.0"
+"com.softwaremill.ox" %% "mdc-logback" % "0.5.1"
 ```
 
 Ox provides support for setting inheritable MDC (mapped diagnostic context) values, when using the [Logback](https://logback.qos.ch)

generated-doc/out/streaming/flows.md

@@ -19,20 +19,7 @@ Flow.iterate(0)(_ + 1) // natural numbers
 
 Note that creating a flow as above doesn't emit any elements, or execute any of the flow's logic. Only when run, the elements are emitted and any effects that are part of the flow's stages happen.
 
-Flows can be also created by providing arbitrary element-emitting logic:
-
-```scala
-import ox.flow.Flow
-
-def isNoon(): Boolean = ???
-
-Flow.usingEmit: emit =>
-  emit(1)
-  for i <- 4 to 50 do emit(i)
-  if isNoon() then emit(42)
-```
-
-Finally, flows can be created using [channel](channels.md) `Source`s:
+Flows can also be created using [channel](channels.md) `Source`s:
 
 ```scala
 import ox.channels.Channel
@@ -50,6 +37,25 @@ supervised:
   Flow.fromSource(ch) // TODO: transform the flow further & run
 ```
 
+Finally, flows can be created by providing arbitrary element-emitting logic:
+
+```scala
+import ox.flow.Flow
+
+def isNoon(): Boolean = ???
+
+Flow.usingEmit: emit =>
+  emit(1)
+  for i <- 4 to 50 do emit(i)
+  if isNoon() then emit(42)
+```
+
+The `emit: FlowEmit` instances is used to emit elements by the flow, that is process them further, as defined by the downstream pipeline. This method only completes once the element is fully processed, and it might throw exceptions in case there's a processing error.
+
+As part of the callback, you can create [supervision scopes](../structured-concurrency/error-handling-scopes.md), fork background computations or run other flows asynchronously. However, take care **not** to share the `emit: FlowEmit` instance across threads. That is, instances of `FlowEmit` are thread-unsafe and should only be used on the calling thread. The lifetime of `emit` should not extend over the duration of the invocation of `withEmit`.
+
+Any asynchronous communication should be best done with [channels](channels.md). You can then manually any elements received from a channel to `emit`, or use e.g. `FlowEmit.channelToEmit`.
+
 ## Transforming flows: basics
 
 Multiple transformation stages can be added to a flow, each time returning a new `Flow` instance, describing the extended pipeline. As before, no elements are emitted or transformed until the flow is run, as flows are lazy. There's a number of pre-defined transformation stages, many of them similar in function to corresponding methods on Scala's collections: