JarCastingTinyAsync
A tiny asynchronous library for Java.
Writing multithreaded code is hard, TinyAsync tries to make it easier by providing simple abstractions for executing and manipulating computations through a clean API abstraction.
Why TinyAsync?
Everything is tucked behind a set of API interfaces, and some functionality has been moved into the stage itself to allow for a clean, chained programming style (especially with java 8).
Since all interaction with the framework happens behind plain old java interfaces, the using component rarely needs to maintain a direct dependency to tiny-async-core. The less components that specify a direct dependency to a potentially messy and changing implementation - the better. See API Separation for more details on how this will be maintained long term.
This has the added benefit of making TinyAsync superb for testing. Your components don't even have to know about concurrency, all you need to do is mock the expected framework behavior.
For an overview of the library, check out the API and the Usage section below.
Setup
TinyAsync is available through maven.
<dependency>
<groupId>eu.toolchain.async2</groupId>
<artifactId>tiny-async-api</artifactId>
<version>${tiny-async.version}</version>
</dependency>
If you have an API project, you can add a dependency to tiny-async-api, which only contains the interfaces used by TinyAsync. This provides a basic level of indirection and is all you need to interact with the library.
If you have an application or framework that intends to provide an implementation of TinyAsync, you should depend on tiny-async-core. This contains the implementation of TinyAsync.
See API Separation for why the API is distributed in a separate package.
After that, the first step is to create a new instance of the framework.
final Async async = CoreAsync.builder().build();
The builder has a few options that you can use to customize behavior.
For a more detailed example, see Helpers.java.
API Separation
The separation between the API and core is done to reduce issues with drifts in dependencies.
A specific version of the API is always intended to be signature compatible with future versions. If you build a project against version 1.1.0 of the API, it will be working with all future 1.x.x versions of core.
Deprecated components will be be marked with @Deprecated and removed in the next major version, packages will also be renamed to avoid future classpath conflicts.
Testing with TinyAsync
TinyAsync heavily favor isolated unit tests that mock as much as possible, see some of the core test suite if you want some inspiration.
Usage
You can see how the library is used by looking at the provided examples:
- Building stages from scratch
- Immediate results
- Blocking
- Completing in different thread
- Listen for changes
- Transform the result
- Collection, and stream collections, and eventual collection of results.
- Retry Operations (API)
- Managed Resources (API)