From da777d17435d7584dbe1bcb2ccfc10953da0b4b5 Mon Sep 17 00:00:00 2001 From: Kacper Korban Date: Thu, 8 Aug 2024 14:22:30 +0200 Subject: [PATCH] Change README to a symlink --- README.md | 104 +------------------------------------------- docs/_docs/index.md | 4 +- 2 files changed, 4 insertions(+), 104 deletions(-) mode change 100644 => 120000 README.md diff --git a/README.md b/README.md deleted file mode 100644 index c6c96f9..0000000 --- a/README.md +++ /dev/null @@ -1,103 +0,0 @@ -[![avocado Scala version support](https://index.scala-lang.org/virtuslab/avocado/avocado/latest-by-scala-version.svg?platform=jvm)](https://index.scala-lang.org/virtuslab/avocado/avocado) - -# avocADO - Safe compile-time parallelization of `for` comprehensions - -## Example - -```scala -import cats.effect.IO - -import avocado.* -import avocado.instances.cats.given - -val run: IO[Int] = - parallelize { - for { - a <- doStuff1 - b <- doStuff2(a) - c <- doStuff3 - d <- doStuff4(a) - } yield combine(a, b, c, d) - } -``` - -`avocADO` will transform the above for-comprehension to code equivalent to: -```scala -for { - a <- doStuff1 - (b, c, d) <- doStuff2(a).zip(doStuff3).zip(doStuff4(a)) -} yield combine(a, b, c, d) -``` - -## Description - -`avocADO` is a small library that allows for automatic rewriting of `for` comprehensions to their parallel versions. - -The name `avocADO` is a pun on the function that is the inspiration for this library - `ado` from Haskell's language extension `ApplicativeDo`. - -## Usage (with build tools) - -### sbt - -```scala -libraryDependencies ++= Seq( - "org.virtuslab" %% "avocado" % "version from the badge", - "org.virtuslab" %% "avocado-cats" % "version from the badge", // for Cats - "org.virtuslab" %% "avocado-zio-2" % "version from the badge", // for ZIO 2.x - "org.virtuslab" %% "avocado-zio-1" % "version from the badge", // for ZIO 1.x, - "org.virtuslab" %% "avocado-zio-query" % "version from the badge", // for ZIO Query -) -``` - -### scala-cli - -```scala -//> using lib "org.virtuslab::avocado:version from the badge" -//> using lib "org.virtuslab::avocado-cats:version from the badge" // for Cats -//> using lib "org.virtuslab::avocado-zio-2:version from the badge" // for ZIO 2.x -//> using lib "org.virtuslab::avocado-zio-1:version from the badge" // for ZIO 1.x -//> using lib "org.virtuslab::avocado-zio-query:version from the badge" // for ZIO Query -``` - -## Usage (in code) - -All you need to do in order to use `avocADO` is to import the `parallelize` function and an `AvocADO` instance for your effect system. i.e. -```scala -import avocado.* // This line exposes the `parallelize` function - entrypoint of the library -// You should choose one of the following imports depending on your effect system of choice -import avocado.instances.cats.given -import avocado.instances.zio2.given -import avocado.instances.zio1.given -import avocado.instances.zioquery.given -``` - -And that's it! All that's left is to wrap the `for`-comprehensions that you want to parallelize with a call to `parallelize` an watch your program run in parallel! Like so: -```scala -parallelize { - for { - ... - } yield ... -} -``` - -## Usage (custom monads) - -On the off chance that `avocADO` doesn't provide an instance for your favourite effect monad, you might have to write an instance of our `AvocADO` typeclass yourself. Don't worry, it's relatively straightforward. - -`AvocADO` is just a `Monad` with a changed name, so that it can be easily associated with `avocADO`. So if you want to write an instance for a class called `Effect` it might look like so: -```scala -given AvocADO[Effect] = new AvocADO[Effect] { - def pure[A](a: A): Effect[A] = Effect.pure(a) - def map[A, B](fa: Effect[A], f: A => B): Effect[B] = fa.map(f) - def zip[A, B](fa: Effect[A], fb: Effect[B]): Effect[(A, B)] = fa.zipPar(fb) // This is the most important method - def flatMap[A, B](fa: Effect[A], f: A => Effect[B]): Effect[B] = fa.flatMap(f) -} -``` - -Every parallel part of the computation will be rewritten to a call to `zip`, so in order to achieve any speedup, you have to provide a parallel implementation for `zip`. - -## References - -Inspired by [Haskell's Applicative do-notation](https://gitlab.haskell.org/ghc/ghc/-/wikis/applicative-do) - -Similar project: [`kitlangton/parallel-for`](https://github.com/kitlangton/parallel-for) (only for Scala 2) diff --git a/README.md b/README.md new file mode 120000 index 0000000..50a090f --- /dev/null +++ b/README.md @@ -0,0 +1 @@ +./docs/_docs/index.md \ No newline at end of file diff --git a/docs/_docs/index.md b/docs/_docs/index.md index 6346b35..c6c96f9 100644 --- a/docs/_docs/index.md +++ b/docs/_docs/index.md @@ -1,3 +1,5 @@ +[![avocado Scala version support](https://index.scala-lang.org/virtuslab/avocado/avocado/latest-by-scala-version.svg?platform=jvm)](https://index.scala-lang.org/virtuslab/avocado/avocado) + # avocADO - Safe compile-time parallelization of `for` comprehensions ## Example @@ -42,7 +44,7 @@ libraryDependencies ++= Seq( "org.virtuslab" %% "avocado" % "version from the badge", "org.virtuslab" %% "avocado-cats" % "version from the badge", // for Cats "org.virtuslab" %% "avocado-zio-2" % "version from the badge", // for ZIO 2.x - "org.virtuslab" %% "avocado-zio-1" % "version from the badge", // for ZIO 1.x + "org.virtuslab" %% "avocado-zio-1" % "version from the badge", // for ZIO 1.x, "org.virtuslab" %% "avocado-zio-query" % "version from the badge", // for ZIO Query ) ```