# par-dual

[![CI Status](https://github.com/gvolpe/par-dual/workflows/Haskell%20CI/badge.svg)](https://github.com/gvolpe/par-dual/actions)

The [PureScript](https://www.purescript.org/) language defines a [Parallel](https://pursuit.purescript.org/packages/purescript-parallel/4.0.0/docs/Control.Parallel.Class#t:Parallel) typeclass in the `parallel` package. Quoting its documentation:

> The `Parallel` class abstracts over monads which support parallel composition via some related `Applicative`.

The same typeclass is defined in the [Scala](https://www.scala-lang.org/) language, as part of the [Cats](https://typelevel.org/cats/typeclasses/parallel.html) library.

This typeclass has been controversial, in a sense, for not having strong laws. However, it has been proven to be actually useful in real-world applications.

The idea of this package is to bring this power over to the Haskell language while exploring the design space to identify and define stronger laws (if possible).

Originally, this idea has been described in [this blogpost](https://gvolpe.github.io/blog/parallel-typeclass-for-haskell/).

## ParDual

Here's the definition of the same typeclass in Haskell:

```haskell
class (Monad m, Applicative f) => ParDual f m | m -> f, f -> m where
  parallel :: forall a . m a -> f a
  sequential :: forall a . f a -> m a
```

I decided to call it `ParDual` instead of `Parallel`, because this *duality* doesn't always define a `sequential` and `parallel` relationship. Such is the case between `[]` and `ZipList`, as we will soon discover.

It defines two functions, which are natural transformations between a `Monad m` and an `Applicative f`. It could also be seen as a typeclass version of an isomorphism such as `forall a . Iso (f a) (m a)`.

The most common and useful relationships are both `Either` / `Validation` and `IO` / `Concurrently`.

```haskell
instance Semigroup e => ParDual (Validation e) (Either e) where
  parallel   = fromEither
  sequential = toEither

instance ParDual Concurrently IO where
  parallel   = Concurrently
  sequential = runConcurrently
```

`Validation` comes from the [validators](https://hackage.haskell.org/package/validators) package, whereas `Concurrently` comes from the [async](https://hackage.haskell.org/package/async) package.

Additionally, we can define a lot of powerful functions solely in terms of `Applicative`, `Monad`, and `ParDual`. A few other functions might require extra requirements, such as `Traversable`.

### parMapN

The `parMapN` set of functions are analogue to combining `<$>` and `<*>`, for any dual `Applicative`.

```haskell
parMap2
  :: (Applicative f, Monad m, ParDual f m)
  => m a0
  -> m a1
  -> (a0 -> a1 -> a)
  -> m a
```

In this case, `parMap2` takes only two computations and a function, but you can find other versions up to `parMap6`. If there is demand, we can consider abstracting over its arity, in order to compose an arbitrary number of computations.

For example, if we define a `Person` datatype with two fields:

```haskell
type Name = Refined NonEmpty String
type Age = Refined (GreaterThan 17) Int

data Person = Person
  { personAge :: Age
  , personName :: Name
  } deriving Show
```

We can then validate different inputs, while accumulating errors on the left side, even when our type is `Either [String] Person`.

```haskell
mkPerson :: Int -> String -> Either [String] Person
mkPerson a n = parMap2 (ref a) (ref n) Person
```

Where `ref` is a generic function that converts `RefineException`s to `[String]`:

```haskell
ref :: Predicate p x => x -> Either [String] (Refined p x)
ref x = left (\e -> [show e]) (refine x)
```

In case of two invalid inputs, we will get as a result a list of validation errors:

```haskell
mkPerson 10 "" == Left ["error 1", "error 2"]
```

If `parMapN` didn't exist, we could do the same by manually converting between `Either` and `Validation` (which is exactly what `parMapN` does via the `ParDual` class).

```haskell
mkPerson :: Int -> String -> Either [String] Person
mkPerson a n = toEither $ Person <$> fromEither (ref a) <*> fromEither (ref n)
```

Though, we can see how cumbersome and boilerplatey it gets.

### parTraverse

Another great application of the `ParDual` class is the definition of a `traverse` function that takes a `Monad` and a `Traversable t`, but that operates over its dual `Applicative`, and at the end it converts back to this `Monad`.

```haskell
parTraverse
  :: (Traversable t, Applicative f, Monad m, ParDual f m)
  => (a -> m b)
  -> t a
  -> m (t b)
```

The type signature is exactly the same as `traverse`, except the constraints are different.

We can appreciate its usability by looking at some examples. Here's one with `Either`:

```haskell
f :: Int -> Either [String] Int
f n = Left [show n]

traverse f [1..5] == Left ["1"]
parTraverse f [1..5] == Left ["1","2","3","4","5"]
```

Below there is another one with `IO`:

```haskell
randomDelay :: IO ()
randomDelay = do
  r <- randomRIO (1, 10)
  threadDelay (r * 500000)

traverseIO :: IO ()
traverseIO = traverse_ (\n -> randomDelay >> print n) [1 .. 10]

parTraverseIO :: IO ()
parTraverseIO = parTraverse_ (\n -> randomDelay >> print n) [1 .. 10]
```

The `traverse` version prints out numbers from 1 to 10 in sequence, while waiting for every random delay. So the output is pretty much `1 2 3 4 5 6 7 8 9 10`.

The `parTraverse` version has a non-deterministic output, since it goes through `Concurrently` (`IO`'s dual). It is exactly what you would expect while using [mapConcurrently](https://hackage.haskell.org/package/async-2.2.2/docs/Control-Concurrent-Async.html#v:mapConcurrently). One possible output is `5 10 6 1 3 2 9 4 7 8`.

### ZipList

The dual `Applicative` instance of `[]` is the one defined by `ZipList`, which doesn't have anything to do with parallelism.

```haskell
instance ParDual ZipList [] where
  parallel   = ZipList
  sequential = getZipList
```

Let's have a look at the examples shown below.

```haskell
((+) <$> [1..5] <*> [6..10]) == [7,8,9,10,11,8,9,10,11,12,9,10,11,12,13,10,11,12,13,14,11,12,13,14,15]

parMap2 [1..5] [6..10] (+) == [7,9,11,13,15]
```

The standard version iterates over both lists "sequentially". That is, it iterates over the first one, and then over the second one, returning the cartesian product of both lists.

Conversely, `ZipList`s only return the sum of the current elements of both lists such as `1 + 6`, `2 + 7`, and so on. It iterates over both lists in "parallel", effectively traversing both at once.

### parBitraverse

Operates over any `Bitraversable` such as `Either` or `(,,)`.

```haskell
res1 = [("ba",'2','T'),("ba",'2','r'),("ba",'2','u'),("ba",'2','e'),("ba",'4','T'),("ba",'4','r'),("ba",'4','u'),("ba",'4','e')]

(bitraverse show show ("ba", 24, True)) == res1
```

The standard `bitraverse` for `(String, Int, Bool)` traverses over the second value and then over the third value, combining the results on each iteration.

```haskell
(parBitraverse show show ("ba", 24, True)) == [("ba",'2','T'),("ba",'4','r')]
```

The dual variant traverses all the values at the same time, terminating as soon as either value is empty.

## Test suite

The test suite property-checks the functions defined in `ParDual` applied to different types of values.

```
$ nix-shell --run 'cabal new-run par-dual-tests'
━━━ Main ━━━
  ✓ prop_parMap2_on_success passed 100 tests.
  ✓ prop_parMap2_accumulates_errors passed 100 tests.
  ✓ prop_parTraverse_accumulates_errors passed 100 tests.
  ✓ prop_parTraverse_io_is_concurrent passed 10 tests.
  ✓ prop_parMap2_on_lists passed 100 tests.
  ✓ prop_parBitraverse passed 100 tests.
  ✓ 6 succeeded.
```

## Publishing

Generating documentation and tarball file to upload.

```
$ cabal new-haddock --haddock-for-hackage --enable-doc
$ cabal upload -d dist-newstyle/par-dual-0.1.0.0-docs.tar.gz
$ cabal new-sdist