https://github.com/yegor256/together
Executes Java lambda in multiple threads and collects their results (useful for testing for thread-safety)
https://github.com/yegor256/together
concurrency java java-8 java-li testing thread-safety threads
Last synced: about 1 month ago
JSON representation
Executes Java lambda in multiple threads and collects their results (useful for testing for thread-safety)
- Host: GitHub
- URL: https://github.com/yegor256/together
- Owner: yegor256
- License: mit
- Created: 2024-12-17T17:06:37.000Z (10 months ago)
- Default Branch: master
- Last Pushed: 2025-08-31T11:26:07.000Z (about 1 month ago)
- Last Synced: 2025-08-31T13:18:08.950Z (about 1 month ago)
- Topics: concurrency, java, java-8, java-li, testing, thread-safety, threads
- Language: Java
- Homepage:
- Size: 124 KB
- Stars: 16
- Watchers: 2
- Forks: 0
- Open Issues: 11
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# Runs Java Lambda in Many Threads
[](https://www.elegantobjects.org)
[](https://www.rultor.com/p/yegor256/together)
[](https://www.jetbrains.com/idea/)
[](https://github.com/yegor256/together/actions/workflows/mvn.yml)
[](https://www.0pdd.com/p?name=yegor256/together)
[](https://maven-badges.herokuapp.com/maven-central/com.yegor256/together)
[](https://www.javadoc.io/doc/com.yegor256/together)
[](https://codecov.io/gh/yegor256/together)
[](https://hitsofcode.com/view/github/yegor256/together)
[](https://github.com/yegor256/together/blob/master/LICENSE.txt)
With this small Java library you can test your objects
for [thread safety] by doing some manipulations with them
in multiple parallel threads. You may read this blog post,
in order to understand the motivation for this type of
testing better: [How I Test My Java Classes for Thread-Safety][blog].
By the way, there are similar libraries for Java, but they are
either more complex or less tests-oriented, for example
[lincheck],
[ConcurrentUnit](https://github.com/jhalterman/concurrentunit),
[`RunsInThreads`][RunsInThreads] from [cactoos-matchers],
or
[`Threads`][Threads] from [Cactoos](https://github.com/yegor256/cactoos).
First, you add this library to your `pom.xml` in [Maven]:
```xml
com.yegor256
together
0.1.0
```
Then, you use it like this, in your [JUnit5] test
(with [Hamcrest]):
```java
import org.hamcrest.MatcherAssert;
import org.hamcrest.Matchers;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.io.TempDir;
import com.yegor256.Together;
class FooTest {
@Test
void worksAsExpected() {
MatcherAssert.assertThat(
"processes all lambdas successfully",
new Together<>(
thread -> {
// Do the job and use "thread" as a number
// of the thread currently running (they are all unique).
return true;
}
),
Matchers.not(Matchers.hasItem(Matchers.is(false)))
);
}
}
```
Here, the `Together` class will run the "job" in multiple threads
and will make sure that all of them return `true`. If at least
one of them returns `false`, the test will fail. If at least one of the
threads will throw an exception, the test will also fail.
`Together` guarantees that all threads will start exactly simultaneously,
thus simulating [race condition] as much as it's possible. This is exactly
what you need for your tests: making sure your object under test
experiences troubles that are very similar to what it might experience
in real life.
For even better/stronger testing, you can use
[`@RepeatedTest`][RepeatedTest].
## How to Contribute
Fork repository, make changes, send us a
[pull request](https://www.yegor256.com/2014/04/15/github-guidelines.html).
We will review your changes and apply them to the `master` branch shortly,
provided they don't violate our quality standards. To avoid frustration,
before sending us your pull request please run full Maven build:
```bash
mvn clean install -Pqulice
```
You will need [Maven] 3.3+ and Java 11+.
[blog]: https://www.yegor256.com/2018/03/27/how-to-test-thread-safety.html
[JUnit5]: https://junit.org/junit5/
[Hamcrest]: http://hamcrest.org
[Maven]: https://maven.apache.org
[race condition]: https://en.wikipedia.org/wiki/Race_condition
[thread safety]: https://en.wikipedia.org/wiki/Thread_safety
[RunsInThreads]: https://github.com/llorllale/cactoos-matchers/blob/master/src/main/java/org/llorllale/cactoos/matchers/RunsInThreads.java
[cactoos-matchers]: https://github.com/llorllale/cactoos-matchers
[Threads]: https://github.com/yegor256/cactoos/blob/master/src/main/java/org/cactoos/experimental/Threads.java
[lincheck]: https://github.com/JetBrains/lincheck
[RepeatedTest]: https://junit.org/junit5/docs/5.0.1/api/org/junit/jupiter/api/RepeatedTest.html