Skip to content

Commit

Permalink
Update README before 0.1.0 release
Browse files Browse the repository at this point in the history
  • Loading branch information
@Avasil
Avasil committed Mar 8, 2020
1 parent 1877f81 commit c28ca34
Show file tree
Hide file tree
Showing 4 changed files with 115 additions and 103 deletions.
126 changes: 25 additions & 101 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,27 +2,18 @@

[![Join the chat at https://gitter.im/monix/monix-bio](https://badges.gitter.im/monix/monix-bio.svg)](https://gitter.im/monix/monix-bio?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)

Experimental alternative to [monix.eval.Task](https://monix.io/api/3.1/monix/eval/Task.html) from [Monix](https://github.com/monix/monix) which uses a second type parameter to represent recoverable errors.

WORK IN PROGRESS.
Alternative to [monix.eval.Task](https://monix.io/api/3.1/monix/eval/Task.html) from [Monix](https://github.com/monix/monix) which uses a second type parameter to represent recoverable errors.

[Documentation Website](https://monix.github.io/monix-bio/)

## Getting Started

There is a SNAPSHOT version (compatible with Monix 3.x and Cats and Cats-Effect 2.x) available:
The latest stable version which is compatible with Monix 3.x, Cats 2.x and Cats-Effect 2.x:

```scala
resolvers += "Sonatype OSS Snapshots" at "https://oss.sonatype.org/content/repositories/snapshots"

libraryDependencies += "io.monix" %% "monix-bio" % "0.0.2-SNAPSHOT"
libraryDependencies += "io.monix" %% "monix-bio" % "0.1.0"
```

I will really appreciate feedback, bugs and complaints about API if you play with it. Just please do not use it in production yet!

If you'd like to join and help then look for issues tagged with [good first issue](https://github.com/monix/monix-bio/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22).
I'm happy to guide anyone interested in contributing. Just let me know on specific issue or write to me on [gitter](https://gitter.im/monix/monix-bio).

## Short introduction

`BIO[E, A]` represents a specification for a possibly lazy or asynchronous computation, which when executed will produce
Expand Down Expand Up @@ -60,112 +51,45 @@ val t: BIO[TypedError, Int] = BIO.race(taskA, taskB).map {
// The error is handled and it is reflected in the signature
val handled: UIO[Int] = t.onErrorHandle { case TypedError(i) => i}

// Nothing happens until it runs, returns Right(-1) after completion
val f: CancelableFuture[Either[Nothing, Int]] = handled.runToFuture
// Nothing happens until it runs, returns -1 after completion
val f: CancelableFuture[Int] = handled.runToFuture

// => taskB has finished
// => taskA has been cancelled
```

I will elaborate much more once the project is ready for general use.
## Current Status

## Stability
The project will maintain binary compatibility in `0.1.x` line.
It is suitable for general usage but I would not recommend building a lot of libraries on it just yet unless you are fine with upgrade in few months.

Currently there are no backwards compatibility guarantees. It will take a bit of time for everything to stabilize so I strongly advise against using it in serious projects at the moment. :) On the other hand, please play with it, give feedback and report bugs! It will be a tremendous help in getting this production-ready faster.
WARNING: Not all scaladocs are updated for `BIO` and currently there is no documentation.
It will be my priority in April.
Until then I consider the project as something for more advanced user who are already familiar with idea of IO Monad and error type exposed in the type parameter.

One of the main goals is to stay as consistent with `monix.eval.Task` as possible so the core functionality will not see much changes but it is likely that some type signatures change, e.g. to return `UIO[A]` where possible.
### Plans for the future
I hope to gather some feedback from production usage and then move towards long term stable version.
Core of the functionality is shared with `monix.eval.Task` (which is stable) and will remain consistent with it.
There might be breaking changes in regards to new error handling combinators, terminology, return types or error reporting.

Error handling operators and error reporting are actively worked on and they will most likely see breaking changes.

Most of the internals didn't see significant changes when compared to `monix.eval.Task` so this implementation can greatly benefit from maturity of its parent but the project has just started and the changes weren't thoroughly tested yet.
## Contributing

## Motivation
I will really appreciate feedback, bugs and complaints about the project.

## Brief comparison to other solutions
If you'd like to contribute code then look for issues tagged with [good first issue](https://github.com/monix/monix-bio/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22)
or just ask me on gitter and I should be able to find something regardless of your level of expertise. :)

## Performance
I'm happy to mentor anyone interested in contributing.

DISCLAIMER: Benchmarks do not necessarily reflect the performance in real conditions so take the results with a grain with salt.
It is possible that in your specific use different effects will perform differently than the benchmark would suggest.
It is best to always measure yourself and for your specific use case if you are concerned about the performance.
## Performance

At the time of writing (10 Dec 2019) the performance is excellent and we did not observe any regressions when compared to `monix.eval.Task`.
Please open an issue or write on gitter (https://gitter.im/monix/monix) in case you measure completely different results or find a benchmark where `monix-bio` does not perform well.
At the time of writing (Q1 2020) performance is as good as `monix.eval.Task` in most benchmarks and `BIO` can outperform it for error handling operators if the error type is not `Throwable`.
It makes it the most performant effect type in today's Scala ecosystem.

The benchmarks are inside [benchmarks module](benchmarks).
Performance is high priority for us and we will greatly appreciate if you open an issue or write on [gitter](https://gitter.im/monix/monix) if you discover use cases where it performs badly.

```
[info] Benchmark (depth) Mode Cnt Score Error Units
[info] IODeepAttemptBenchmark.catsDeepAttempt 1000 thrpt 30 20867.936 ± 113.416 ops/s
[info] IODeepAttemptBenchmark.futureDeepAttempt 1000 thrpt 30 10617.519 ± 266.933 ops/s
[info] IODeepAttemptBenchmark.monixBioDeepAttempt 1000 thrpt 30 21098.927 ± 76.705 ops/s
[info] IODeepAttemptBenchmark.monixBioDeepAttemptTyped 1000 thrpt 30 49799.909 ± 900.961 ops/s
[info] IODeepAttemptBenchmark.monixDeepAttempt 1000 thrpt 30 20858.228 ± 225.967 ops/s
[info] IODeepAttemptBenchmark.zioDeepAttempt 1000 thrpt 30 17182.169 ± 256.507 ops/s
[info] IODeepAttemptBenchmark.zioDeepAttemptTyped 1000 thrpt 30 33391.597 ± 227.462 ops/s
[info] Benchmark (count) (depth) (size) Mode Cnt Score Error Units
[info] IOShallowAttemptBenchmark.catsShallowAttempt N/A 1000 N/A thrpt 30 2082.374 ± 56.612 ops/s
[info] IOShallowAttemptBenchmark.futureShallowAttempt N/A 1000 N/A thrpt 30 13673.549 ± 254.908 ops/s
[info] IOShallowAttemptBenchmark.monixBioShallowAttempt N/A 1000 N/A thrpt 30 2166.767 ± 70.277 ops/s
[info] IOShallowAttemptBenchmark.monixBioShallowAttemptTyped N/A 1000 N/A thrpt 30 45237.518 ± 201.742 ops/s
[info] IOShallowAttemptBenchmark.monixShallowAttempt N/A 1000 N/A thrpt 30 2237.589 ± 66.912 ops/s
[info] IOShallowAttemptBenchmark.zioShallowAttempt N/A 1000 N/A thrpt 30 1655.358 ± 41.271 ops/s
[info] IOShallowAttemptBenchmark.zioShallowAttemptTyped N/A 1000 N/A thrpt 30 15874.855 ± 55.476 ops/s
[info] IODeepFlatMapBenchmark.catsDeepFlatMap N/A 20 N/A thrpt 30 1369.812 ± 13.374 ops/s
[info] IODeepFlatMapBenchmark.futureDeepFlatMap N/A 20 N/A thrpt 30 347.436 ± 6.665 ops/s
[info] IODeepFlatMapBenchmark.monixBioDeepFlatMap N/A 20 N/A thrpt 30 1933.068 ± 13.436 ops/s
[info] IODeepFlatMapBenchmark.monixDeepFlatMap N/A 20 N/A thrpt 30 1937.212 ± 13.173 ops/s
[info] IODeepFlatMapBenchmark.zioDeepFlatMap N/A 20 N/A thrpt 30 1159.547 ± 6.212 ops/s
[info] IODeepLeftBindBenchmark.catsDeepLeftBind N/A 10000 N/A thrpt 30 4340.087 ± 28.919 ops/s
[info] IODeepLeftBindBenchmark.monixBioDeepLeftBind N/A 10000 N/A thrpt 30 7392.089 ± 35.754 ops/s
[info] IODeepLeftBindBenchmark.monixDeepLeftBind N/A 10000 N/A thrpt 30 7382.817 ± 25.495 ops/s
[info] IODeepLeftBindBenchmark.zioDeepLeftBind N/A 10000 N/A thrpt 30 2875.241 ± 47.077 ops/s
[info] IONarrowFlatMapBenchmark.catsNarrowFlatMap N/A N/A 10000 thrpt 30 5878.830 ± 20.724 ops/s
[info] IONarrowFlatMapBenchmark.futureNarrowFlatMap N/A N/A 10000 thrpt 30 847.120 ± 30.852 ops/s
[info] IONarrowFlatMapBenchmark.monixBioNarrowFlatMap N/A N/A 10000 thrpt 30 7502.053 ± 29.003 ops/s
[info] IONarrowFlatMapBenchmark.monixNarrowFlatMap N/A N/A 10000 thrpt 30 7494.606 ± 42.565 ops/s
[info] IONarrowFlatMapBenchmark.zioNarrowFlatMap N/A N/A 10000 thrpt 30 6053.870 ± 25.552 ops/s
[info] IOEmptyRaceBenchmark.catsEmptyRace N/A N/A 1000 thrpt 30 376.517 ± 9.853 ops/s
[info] IOEmptyRaceBenchmark.monixBioEmptyRace N/A N/A 1000 thrpt 30 343.120 ± 1.743 ops/s
[info] IOEmptyRaceBenchmark.monixEmptyRace N/A N/A 1000 thrpt 30 346.287 ± 3.841 ops/s
[info] IOEmptyRaceBenchmark.zioEmptyRace N/A N/A 1000 thrpt 30 65.288 ± 1.717 ops/s
[info] IOSequenceBenchmark.catsParSequence 100 N/A N/A thrpt 30 5931.683 ± 31.683 ops/s
[info] IOSequenceBenchmark.catsParSequence 1000 N/A N/A thrpt 30 555.898 ± 2.747 ops/s
[info] IOSequenceBenchmark.catsParSequenceN 100 N/A N/A thrpt 30 6468.484 ± 70.442 ops/s
[info] IOSequenceBenchmark.catsParSequenceN 1000 N/A N/A thrpt 30 302.005 ± 31.390 ops/s
[info] IOSequenceBenchmark.catsSequence 100 N/A N/A thrpt 30 99080.596 ± 362.897 ops/s
[info] IOSequenceBenchmark.catsSequence 1000 N/A N/A thrpt 30 9688.414 ± 45.275 ops/s
[info] IOSequenceBenchmark.futureSequence 100 N/A N/A thrpt 30 11469.757 ± 48.180 ops/s
[info] IOSequenceBenchmark.futureSequence 1000 N/A N/A thrpt 30 1556.510 ± 106.805 ops/s
[info] IOSequenceBenchmark.monixBioGather 100 N/A N/A thrpt 30 9992.616 ± 68.297 ops/s
[info] IOSequenceBenchmark.monixBioGather 1000 N/A N/A thrpt 30 1825.815 ± 18.950 ops/s
[info] IOSequenceBenchmark.monixBioGatherN 100 N/A N/A thrpt 30 18452.927 ± 67.554 ops/s
[info] IOSequenceBenchmark.monixBioGatherN 1000 N/A N/A thrpt 30 3818.984 ± 17.530 ops/s
[info] IOSequenceBenchmark.monixBioGatherUnordered 100 N/A N/A thrpt 30 12254.025 ± 132.574 ops/s
[info] IOSequenceBenchmark.monixBioGatherUnordered 1000 N/A N/A thrpt 30 1177.839 ± 91.644 ops/s
[info] IOSequenceBenchmark.monixBioSequence 100 N/A N/A thrpt 30 299900.839 ± 1734.770 ops/s
[info] IOSequenceBenchmark.monixBioSequence 1000 N/A N/A thrpt 30 32325.930 ± 127.897 ops/s
[info] IOSequenceBenchmark.monixGather 100 N/A N/A thrpt 30 10318.503 ± 79.700 ops/s
[info] IOSequenceBenchmark.monixGather 1000 N/A N/A thrpt 30 1838.422 ± 41.339 ops/s
[info] IOSequenceBenchmark.monixGatherN 100 N/A N/A thrpt 30 18673.274 ± 30.147 ops/s
[info] IOSequenceBenchmark.monixGatherN 1000 N/A N/A thrpt 30 4044.859 ± 23.332 ops/s
[info] IOSequenceBenchmark.monixGatherUnordered 100 N/A N/A thrpt 30 12635.339 ± 477.038 ops/s
[info] IOSequenceBenchmark.monixGatherUnordered 1000 N/A N/A thrpt 30 1079.405 ± 64.828 ops/s
[info] IOSequenceBenchmark.monixSequence 100 N/A N/A thrpt 30 310564.348 ± 8099.175 ops/s
[info] IOSequenceBenchmark.monixSequence 1000 N/A N/A thrpt 30 32006.174 ± 154.372 ops/s
[info] IOSequenceBenchmark.zioParSequence 100 N/A N/A thrpt 30 583.752 ± 4.781 ops/s
[info] IOSequenceBenchmark.zioParSequence 1000 N/A N/A thrpt 30 19.831 ± 0.118 ops/s
[info] IOSequenceBenchmark.zioParSequenceN 100 N/A N/A thrpt 30 1897.714 ± 17.671 ops/s
[info] IOSequenceBenchmark.zioParSequenceN 1000 N/A N/A thrpt 30 323.613 ± 4.579 ops/s
[info] IOSequenceBenchmark.zioSequence 100 N/A N/A thrpt 30 133190.725 ± 707.170 ops/s
[info] IOSequenceBenchmark.zioSequence 1000 N/A N/A thrpt 30 14209.771 ± 200.079 ops/s
```
You can find benchmarks and their results inside [benchmarks module](benchmarks).

## Credits

Expand Down
11 changes: 10 additions & 1 deletion benchmarks/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,4 +16,13 @@ It might be also useful to redirect results to a file:
benchmarks/jmh:run -i 20 -wi 10 -f 3 -r 10 -t 1 -rff "benchmarksResult.txt"
```

Refer to the full list of available parameters [here](https://github.com/guozheng/jmh-tutorial/blob/master/README.md).
Refer to the full list of available parameters [here](https://github.com/guozheng/jmh-tutorial/blob/master/README.md).

### Results

DISCLAIMER: Benchmarks do not necessarily reflect the performance in real conditions so take the results with a grain with salt.
It is possible that in your specific use different effects will perform differently than the benchmark would suggest.
It is best to always measure yourself and for your specific use case if you are concerned about the performance.


[10-12-2019](results/10-12-2019.md)
Loading

0 comments on commit c28ca34

Please sign in to comment.