Release 0.0.25

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.0.24"
+"com.softwaremill.ox" %% "core" % "0.0.25"
 ```
 
 Or [scala-cli](https://scala-cli.virtuslab.org):
 
 ```scala
-//> using dep "com.softwaremill.ox::core:0.0.24"
+//> using dep "com.softwaremill.ox::core:0.0.25"
 ```
 
 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/channels/actors.md

@@ -70,7 +70,7 @@ Such a callback can be used to release any resources held by the actor's logic.
 includes closing of the enclosing scope:
 
 ```scala
-import ox.supervised
+import ox.{never, supervised}
 import ox.channels.*
 
 class Stateful:
@@ -82,5 +82,8 @@ supervised {
 
   // fire-and-forget, exception causes the scope to close
   ref.tell(_.work(5)) 
+
+  // preventing the scope from closing
+  never
 }
 ```

generated-doc/out/collections.md

@@ -3,7 +3,7 @@
 ## mapPar
 
 ```scala
-import ox.syntax.mapPar
+import ox.mapPar
 
 val input: List[Int] = List(1, 2, 3, 4, 5, 6, 7, 8, 9, 10)
 
@@ -18,7 +18,7 @@ limits how many concurrent forks are going to process the collection.
 ## foreachPar
 
 ```scala
-import ox.syntax.foreachPar
+import ox.foreachPar
 
 val input: List[Int] = List(1, 2, 3, 4, 5, 6, 7, 8, 9, 10)
 
@@ -31,7 +31,7 @@ Similar to `mapPar` but doesn't return anything.
 ## filterPar
 
 ```scala
-import ox.syntax.filterPar
+import ox.filterPar
 
 val input: List[Int] = List(1, 2, 3, 4, 5, 6, 7, 8, 9, 10)
 
@@ -45,7 +45,7 @@ and other forks calculating predicates are interrupted.
 ## collectPar
 
 ```scala
-import ox.syntax.collectPar
+import ox.collectPar
 
 val input: List[Int] = List(1, 2, 3, 4, 5, 6, 7, 8, 9, 10)
 

generated-doc/out/control-flow.md

@@ -5,7 +5,8 @@ There are some helper methods which might be useful when writing code using ox's
 * `forever { ... }` repeatedly evaluates the given code block forever
 * `repeatWhile { ... }` repeatedly evaluates the given code block, as long as it returns `true`
 * `repeatUntil { ... }` repeatedly evaluates the given code block, until it returns `true`
-* `uninterruptible { ... }` evaluates the given code block making sure it can't be interrupted
 * `never` blocks the current thread indefinitely, until it is interrupted
+* `checkInterrupt()` checks if the current thread is interrupted, and if so, throws an `InterruptedException`. Useful in
+  compute-intensive code, which wants to cooperate in the cancellation protocol
 
-All of these are `inline` methods.
+All of these are `inline` methods, imposing no runtime overhead.

generated-doc/out/error-handling-scopes.md

@@ -8,7 +8,8 @@ The "default" and recommended scope is created using `supervised`. When this sco
 `fork` or `forkUser` that fails with an exception, will cause the enclosing scope to end:
 
 ```scala
-import ox.{forkUser, supervised}
+import ox.{forkUser, sleep, supervised}
+import scala.concurrent.duration.*
 
 supervised {
   forkUser {

generated-doc/out/fork-join.md

@@ -16,7 +16,8 @@ exception, or due to an interrupt.
 For example, the code below is equivalent to `par`:
 
 ```scala
-import ox.{fork, supervised}
+import ox.{fork, sleep, supervised}
+import scala.concurrent.duration.*
 
 supervised {
   val f1 = fork {
@@ -37,10 +38,11 @@ It is a compile-time error to use `fork`/`forkUser` outside of a `supervised` or
 require to be run within a scope by requiring the `Ox` capability:
 
 ```scala
-import ox.{fork, Fork, Ox, supervised}
+import ox.{fork, Fork, Ox, sleep, supervised}
+import scala.concurrent.duration.*
 
 def forkComputation(p: Int)(using Ox): Fork[Int] = fork {
-  Thread.sleep(p * 1000)
+  sleep(p.seconds)
   p + 1
 }
 
@@ -68,7 +70,8 @@ are cancelled (using interruption). Once all forks complete, the exception is pr
 the `supervised` method invocation:
 
 ```scala
-import ox.{fork, forkUser, Ox, supervised}
+import ox.{fork, forkUser, Ox, sleep, supervised}
+import scala.concurrent.duration.*
 
 supervised {
   forkUser {

generated-doc/out/index.md

@@ -11,10 +11,10 @@ In addition to this documentation, ScalaDocs can be browsed at [https://javadoc.
 
 ```scala
 // sbt dependency
-"com.softwaremill.ox" %% "core" % "0.0.24"
+"com.softwaremill.ox" %% "core" % "0.0.25"
 
 // scala-cli dependency
-//> using dep "com.softwaremill.ox::core:0.0.24"
+//> using dep "com.softwaremill.ox::core:0.0.25"
 ```
 
 ## Scope of the project
@@ -86,6 +86,7 @@ We offer commercial support for ox and related technologies, as well as developm
    interruptions
    resources
    control-flow
+   utility
    extension
    dictionary
    performance

generated-doc/out/kafka.md

@@ -3,7 +3,7 @@
 Dependency:
 
 ```scala
-"com.softwaremill.ox" %% "kafka" % "0.0.24"
+"com.softwaremill.ox" %% "kafka" % "0.0.25"
 ```
 
 `Source`s which read from a Kafka topic, mapping stages and drains which publish to Kafka topics are available through
@@ -33,15 +33,15 @@ To publish data to a Kafka topic:
 ```scala
 import ox.channels.Source
 import ox.kafka.{ProducerSettings, KafkaDrain}
-import ox.supervised
+import ox.{pipe, supervised}
 import org.apache.kafka.clients.producer.ProducerRecord
 
 supervised {
   val settings = ProducerSettings.default.bootstrapServers("localhost:9092")
   Source
     .fromIterable(List("a", "b", "c"))
     .mapAsView(msg => ProducerRecord[String, String]("my_topic", msg))
-    .applied(KafkaDrain.publish(settings))
+    .pipe(KafkaDrain.publish(settings))
 }
 ```
 
@@ -66,7 +66,7 @@ computed. For example:
 ```scala
 import ox.kafka.{ConsumerSettings, KafkaDrain, KafkaSource, ProducerSettings, SendPacket}
 import ox.kafka.ConsumerSettings.AutoOffsetReset
-import ox.supervised
+import ox.{pipe, supervised}
 import org.apache.kafka.clients.producer.ProducerRecord
 
 supervised {
@@ -79,7 +79,7 @@ supervised {
     .subscribe(consumerSettings, sourceTopic)
     .map(in => (in.value.toLong * 2, in))
     .map((value, original) => SendPacket(ProducerRecord[String, String](destTopic, value.toString), original))
-    .applied(KafkaDrain.publishAndCommit(producerSettings))
+    .pipe(KafkaDrain.publishAndCommit(producerSettings))
 }
 ```
 

generated-doc/out/par.md

@@ -3,7 +3,8 @@
 A number of computations can be ran in parallel using the `par` method, for example:
 
 ```scala
-import ox.par
+import ox.{par, sleep}
+import scala.concurrent.duration.*
 
 def computation1: Int =
   sleep(2.seconds)
@@ -24,7 +25,8 @@ It's also possible to run a sequence of computations given as a `Seq[() => T]` i
 parallelism using `parLimit`:
 
 ```scala
-import ox.parLimit
+import ox.{parLimit, sleep}
+import scala.concurrent.duration.*
 
 def computation(n: Int): Int =
   sleep(1.second)
@@ -45,7 +47,8 @@ It's possible to use an arbitrary [error mode](error-handling.md) by providing i
 Alternatively, a built-in version using `Either` is available as `parEither`:
 
 ```scala
-import ox.parEither
+import ox.{parEither, sleep}
+import scala.concurrent.duration.*
 
 val result = parEither(
   {

generated-doc/out/race.md

@@ -3,7 +3,8 @@
 A number of computations can be raced against each other using the `race` method, for example:
 
 ```scala
-import ox.race
+import ox.{race, sleep}
+import scala.concurrent.duration.*
 
 def computation1: Int =
   sleep(2.seconds)
@@ -38,7 +39,8 @@ It's possible to use an arbitrary [error mode](error-handling.md) by providing i
 Alternatively, a built-in version using `Either` is available as `raceEither`:
 
 ```scala
-import ox.raceEither
+import ox.{raceEither, sleep}
+import scala.concurrent.duration.*
 
 raceEither({
   sleep(200.millis)

generated-doc/out/resources.md

@@ -1,6 +1,22 @@
 # Resources
 
-## Allocate & release
+## Individual resource
+
+Ox provides convenience methods to allocate, use and (uninterruptibly) release resources with a try-finally block: `use`
+and `useCloseable`. For example:
+
+```scala
+import ox.useCloseable
+
+useCloseable(new java.io.PrintWriter("test.txt")) { writer =>
+  writer.println("Hello, world!")
+}
+```
+
+If a concurrency scope is available (e.g. `supervised`), or there are multiple resources to allocate, consider using the
+approach described below, to avoid creating an additional syntactical scope.
+
+## Within a concurrency scope
 
 Resources can be allocated within a concurrency scope. They will be released in reverse acquisition order, after all 
 forks started within the scope finish (but before the scope completes). E.g.:
@@ -25,7 +41,7 @@ supervised {
 }
 ```
 
-## Release-only
+### Release-only
 
 You can also register resources to be released (without acquisition logic), before the scope completes:
 

generated-doc/out/retries.md

@@ -13,12 +13,12 @@ import ox.retry.retry
 retry(operation)(policy)
 ```
 
-or, using syntax sugar:
+or, using [`pipe`](utility.md) sugar:
 
 ```scala
-import ox.syntax.*
+import ox.pipe
 
-operation.retry(policy)
+operation.pipe(retry(policy))
 ```
 
 ## Operation definition
@@ -148,27 +148,27 @@ def eitherOperation: Either[String, Int] = ???
 def unionOperation: String | Int = ???
 
 // various operation definitions - same syntax
-retry(directOperation)(RetryPolicy.immediate(3))
-retryEither(eitherOperation)(RetryPolicy.immediate(3))
+retry(RetryPolicy.immediate(3))(directOperation)
+retryEither(RetryPolicy.immediate(3))(eitherOperation)
 
 // various policies with custom schedules and default ResultPolicy
-retry(directOperation)(RetryPolicy.delay(3, 100.millis))
-retry(directOperation)(RetryPolicy.backoff(3, 100.millis)) // defaults: maxDelay = 1.minute, jitter = Jitter.None
-retry(directOperation)(RetryPolicy.backoff(3, 100.millis, 5.minutes, Jitter.Equal))
+retry(RetryPolicy.delay(3, 100.millis))(directOperation)
+retry(RetryPolicy.backoff(3, 100.millis))(directOperation) // defaults: maxDelay = 1.minute, jitter = Jitter.None
+retry(RetryPolicy.backoff(3, 100.millis, 5.minutes, Jitter.Equal))(directOperation)
 
 // infinite retries with a default ResultPolicy
-retry(directOperation)(RetryPolicy.delayForever(100.millis))
-retry(directOperation)(RetryPolicy.backoffForever(100.millis, 5.minutes, Jitter.Full))
+retry(RetryPolicy.delayForever(100.millis))(directOperation)
+retry(RetryPolicy.backoffForever(100.millis, 5.minutes, Jitter.Full))(directOperation)
 
 // result policies
 // custom success
-retry(directOperation)(RetryPolicy(Schedule.Immediate(3), ResultPolicy.successfulWhen(_ > 0)))
+retry[Int](RetryPolicy(Schedule.Immediate(3), ResultPolicy.successfulWhen(_ > 0)))(directOperation)
 // fail fast on certain errors
-retry(directOperation)(RetryPolicy(Schedule.Immediate(3), ResultPolicy.retryWhen(_.getMessage != "fatal error")))
-retryEither(eitherOperation)(RetryPolicy(Schedule.Immediate(3), ResultPolicy.retryWhen(_ != "fatal error")))
+retry(RetryPolicy(Schedule.Immediate(3), ResultPolicy.retryWhen(_.getMessage != "fatal error")))(directOperation)
+retryEither(RetryPolicy(Schedule.Immediate(3), ResultPolicy.retryWhen(_ != "fatal error")))(eitherOperation)
 
 // custom error mode
-retryWithErrorMode(UnionMode[String])(unionOperation)(RetryPolicy(Schedule.Immediate(3), ResultPolicy.retryWhen(_ != "fatal error")))
+retryWithErrorMode(UnionMode[String])(RetryPolicy(Schedule.Immediate(3), ResultPolicy.retryWhen(_ != "fatal error")))(unionOperation)
 ```
 
 See the tests in `ox.retry.*` for more.