KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #developer-tools #ai-agent #claude-code #codex #typescript #ai-agents #deepseek-harness #mcp #cli #rust

jox

★ 419 Open GitHub ↗

Virtual-thread based safe concurrency & streaming

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Jox

[![Ideas, suggestions, problems, questions](https://img.shields.io/badge/Discourse-ask%20question-blue)](https://softwaremill.community/c/open-source/11)
[![CI](https://github.com/softwaremill/jox/workflows/CI/badge.svg)](https://github.com/softwaremill/jox/actions?query=workflow%3A%22CI%22)
[![javadoc (channels)](https://javadoc.io/badge2/com.softwaremill.jox/channels/javadoc%20channels.svg)](https://javadoc.io/doc/com.softwaremill.jox/channels)
[![javadoc (flows)](https://javadoc.io/badge2/com.softwaremill.jox/flows/javadoc%20flows.svg)](https://javadoc.io/doc/com.softwaremill.jox/flows)

[Virtual-thread](https://docs.oracle.com/en/java/javase/21/core/virtual-threads.html) based safe concurrency & streaming
for Java.

Includes:

* Fast & scalable, completable channels, with Go-like `select`s (Java 21+)
* Programmer-friendly structured concurrency (Java 25 only)
* Finite & infinite streaming using flows, with reactive streams compatibility, (blocking) I/O integration and a
  high-level, “functional” API (Java 25 only)

Find out more in the documentation available at [jox.softwaremill.com](https://jox.softwaremill.com/).

## A tour of Jox

Selectable [channels](https://jox.softwaremill.com/latest/channels.html):

```
var ch1 = Channel.<Integer>newBufferedDefaultChannel();
var ch2 = Channel.<Integer>newBufferedDefaultChannel();
var ch3 = Channel.<Integer>newBufferedDefaultChannel();

// send a value to two channels
ch2.send(29);
ch3.send(32);

var received = select(ch1.receiveClause(), ch2.receiveClause(), ch3.receiveClause());
```

A push-based, backpressured [flow](https://jox.softwaremill.com/latest/flows.html) with time-based & parallel
processing:

```
var nats =
  Flows.unfold(0, i -> Optional.of(Map.entry(i+1, i+1)));
 
Flows.range(1, 100, 1)
  .throttle(1, Duration.ofSeconds(1))
  .mapPar(4, i -> {
    Thread.sleep(5000);
    var j = i*3;
    return j+1;
  })
  .filter(i -> i % 2 == 0)
  .zip(nats)
  .runForeach(IO::println);
```

[Structured concurrency](https://jox.softwaremill.com/latest/structured.html) scope:

```
var result = supervised(scope -> {
    var f1 = scope.fork(() -> {
        Thread.sleep(500);
        return 5;
    });
    var f2 = scope.fork(() -> {
        Thread.sleep(1000);
        return 6;
    });
    return f1.join() + f2.join();
});
IO.println("result = " + result);
```

## Feedback

Is what we are looking for!

Let us know in the issues, or our [community forum](https://softwaremill.community/c/open-source/11).

## Project sponsor

We offer commercial development services. [Contact us](https://softwaremill.com) to learn more!

## Building & working on Jox

Jox uses the spotless maven plugin to format code. The formatting is automatically applied during compilation.
Formatting can be checked using `mvn spotless:check` and applied with `mvn spotless:apply`.

When using VS Code, format-on-save should be disabled (see the pom.xml).
For IntelliJ, it might be necessary to install the spotless plugin to properly reformat the sources.

## Channel concurrency tests using Fray

Apart from unit & stress tests, which live in the `channels/src/test/java` directory, Jox includes additional
concurrency tests using the [Fray](https://github.com/cmu-pasta/fray) library. The library runs a number of randomized,
but deterministic tests using orchestrated code & JVM. That way, even though the tests are not exhaustive, so we are
not able to prove that the code is 100% race & deadlock-free, we gain a new approach to verifying thread interleavings
which would otherwise be hard to obtain.

The concurrency tests are only run when the `integration-tests` profile is enabled. That is, when in the
`channels-fray-tests` module:

- `mvn test` - Tests are skipped
- `mvn verify` - Tests are skipped
- `mvn integration-test -Pintegration-tests` - Tests run during the integration-test phase
- `mvn verify -Pintegration-tests` - Tests run during the integration-test phase

The test runs can be parametrized using the `CHANNEL_SIZE` and `JOX_SEGMENT_SIZE` environment variables. By default,
these have the values 16 and 32. Note that the segment size affects not only the tests, but all channels, so be careful
to change it only for scoped test runs.

jox

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README