ox

# Ox

[![Ideas, suggestions, problems, questions](https://img.shields.io/badge/Discourse-ask%20question-blue)](https://softwaremill.community/c/ox)
[![CI](https://github.com/softwaremill/ox/workflows/CI/badge.svg)](https://github.com/softwaremill/ox/actions?query=workflow%3A%22CI%22)
[![Maven Central](https://img.shields.io/maven-central/v/com.softwaremill.ox/core_3)](https://central.sonatype.com/artifact/com.softwaremill.ox/core_3)
[![ScalaDoc](https://javadoc.io/badge2/com.softwaremill.ox/core_3/ScalaDoc.svg)](https://javadoc.io/doc/com.softwaremill.ox/core_3)

Safe direct-style streaming, concurrency and resiliency for Scala on the JVM. Requires JDK 21+ & Scala 3. Ox covers
the following areas:

* streaming: push-based backpressured streaming designed for direct-style, with a rich set of stream transformations,
  flexible stream source & sink definitions and reactive streams integration
* error management: retries, timeouts, a safe approach to error propagation, safe resource management  
* concurrency: high-level concurrency operators, developer-friendly structured concurrency, safe low-level primitives, 
  communication between concurrently running computations
* scheduling & timers
* resiliency: circuit breakers, bulkheads, rate limiters, backpressure

Ox enables writing simple, expression-oriented code in functional style. The syntax overhead is kept to a minimum, 
preserving developer-friendly stack traces, and without compromising performance.

To use Ox, add the following dependency, using either [sbt](https://www.scala-sbt.org):

```scala
"com.softwaremill.ox" %% "core" % "1.1.0"
```

Or [scala-cli](https://scala-cli.virtuslab.org):

```scala
//> using dep "com.softwaremill.ox::core:1.1.0"
```

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).

## Tour of ox

Run two computations [in parallel](https://ox.softwaremill.com/latest/high-level-concurrency/par.html):

```scala mdoc:compile-only
def computation1: Int = { sleep(2.seconds); 1 }
def computation2: String = { sleep(1.second); "2" }
val result1: (Int, String) = par(computation1, computation2)
// (1, "2")
```

[Timeout](https://ox.softwaremill.com/latest/high-level-concurrency/timeout.html) a computation:

```scala mdoc:compile-only
def computation3: Int = { sleep(2.seconds); 1 }
val result2: Either[TimeoutException, Int] = timeout(1.second)(computation3).catching[TimeoutException]
// `timeout` only completes once the loosing branch is interrupted & done
```

[Race](https://ox.softwaremill.com/latest/high-level-concurrency/race.html) two computations:

```scala mdoc:compile-only
def computation4: Int = { sleep(2.seconds); 1 }
def computation5: Int = { sleep(1.second); 2 }
val result3: Int = raceSuccess(computation4, computation5)
// as before, the loosing branch is interrupted & awaited before returning a result
```

[Structured concurrency](https