org.atnos.eff

This trait provides a way to rewrite applicative effects when there is an operation allowing the batching of some effects based on the Batchable typeclass

This cache is used to memoize values for the Memoized effect

The Choose effect models non-determinism So we can get results, either:

• no results (when using ChooseZero)
• the result for action1 or the result for action b (when using ChoosePlus)

When running this effect we can "collect" the results with any F which has an Alternative instance.

For example if F is List then:

• no results is the empty list
• the result for a or b is List(a, b)

If F is Option then:

• no results is the None
• the result for a or b is Some(a) or Some(b

Collection of effects of a given type from a Unions objects

Sequence of monadic functions from A to B: A => Eff[B]

Internally it is represented as a Vector of functions:

A => Eff[R, X1]; X1 => Eff[R, X2]; X2 => Eff[R, X3]; ...; X3 => Eff[R, B]

An alternate unit value can also be set on this function in case the argument A is not available. This value can be set by an effect to do some cleanup if it doesn't even get the chance to add its own effect. See SafeEffect.bracket

Effects of type R, returning a value of type A

It is implemented as a "Free-er" monad with extensible effects:

• the "pure" case is a pure value of type A

• the "impure" case is:

  • a disjoint union of possible effects
  • a continuation of type X => Eff[R, A] indicating what to do if the current effect is of type M[X] this type is represented by the Arrs type

• the "impure applicative" case is:

  • list of disjoint unions of possible effects
  • a function to apply to the values resulting from those effects

The monad implementation for this type is really simple:

• point is Pure
• bind simply appends the binding function to the Arrs continuation

Important:

The list of continuations is NOT implemented as a type sequence but simply as a

  Vector[Any => Eff[R, Any]]

This means that various .asInstanceOf are present in the implementation and could lead to burns and severe harm. Use with caution!

Similarly the list of effects in the applicative case is untyped and interpreters for those effects are supposed to create a list of values to feed the mapping function. If an interpreter doesn't create a list of values of the right size and with the right types, there will be a runtime exception.

The Pure, Impure and ImpureAp cases also incorporate a "last" action returning no value but just used for side-effects (shutting down an execution context for example). This action is meant to be executed at the end of all computations, regardless of the number of flatMaps added on the Eff value.

Since this last action will be executed, its value never collected so if it throws an exception it is possible to print it by defining the eff.debuglast system property (-Deff.debuglast=true)

Union represents one effect T[_] embedded in a tree of possible effects R

The effect tree is represented by four possible cases:

• fx1[T]
• fx2[T1, T2]
• fx3[T1, T2, T3]
• FxAppend[L, R]

The union type has three concrete constructors:

• UnionAppendL(nested: Union[L]): Union[FxAppend[L, R]]
• UnionAppendR(nested: Union[R]): Union[FxAppend[L, R]]
• UnionTagged(valueUnsafe: Any, index: Int): Union[R] (for R in fx1, fx2, fx3...) In that respect UnionTagged behaves similarly to a tagged union in C or C++.

Effect for computation which can fail

Effect for computation which can fail and return a Throwable, or just stop with a failure

This effect is a mix of Eval and Either in the sense that every computation passed to this effect (with the ok method) is considered "impure" or "faulty" by default.

The type F is used to represent the failure type.

Simple instantiation of the ErrorEffect trait with String as a Failure type

Effect for delayed computations

uses cats.Eval as a supporting data structure

Type class to extract members from a list of Member instances

Base type for a tree of effect types

Append a tree of effects to another one

Impure is an effect (encoded as one possibility among other effects, a Union) and a continuation providing the next Eff value.

This essentially models a flatMap operation with the current effect and the monadic function to apply to a value once the effect is interpreted

One effect can always be executed last, just for side-effects

ImpureAp is a list of independent effects and a pure function creating a value with all the resulting values once all effects have been interpreted.

This essentially models a sequence + map operation but it is important to understand that the list of Union objects can represent different effects and be like: Vector[Option[Int], Future[String], Option[Int]].

Interpreting such an Eff value for a given effect (say Option) consists in:

• grouping all the Option values,
• sequencing them
• pass them to a continuation which will apply the 'map' functions when the other effects (Future in the example above) will have been interpreted

VERY IMPORTANT:

• this object is highly unsafe
• the size of the list argument to 'map' must always be equal to the number of unions in the Unions object
• the types of the elements in the list argument to 'map' must be the exact types of each effect in unions.unions

The Interpret trait provides method to interpret (or "handle") effects.

An interpreter generally handles a given effect M and a value Eff[R, A] where M is a member of R.

The most general way of interpreting an effect is to implement the Interpreter trait for that effect and use the runInterpreter method. With the Interpreter trait you need to define:

• what to do with pure values
• what to do with an effect
• what to do with a list of effects (the "applicative" case)
• what to do with a "last" effect, in case of having side-effects to finalize resources (see the SafeEffect)

For each of those methods you get access to a continuation which you may or may not invoke to create the next effect in a sequence of effects. For example with the EitherEffect once you arrive on a Left value you don't trigger the continuation because there is no value to trigger it with.

There are also easier ways to define interpreters. The recurse method and the Recurser trait define:

• onPure(a: A): B: how to map a pure value A to the result B
• onEffect[X](mx: M[X]): X Either Eff[R, B]: either extract a value from the effect or return another effect
• onApplicative[X](tx: T[M[X]]): T[X] Either M[T[X]]: either extract individual values from each effect or "sequence" the effect

Even simpler, the Translate trait does a translation from an effect M[X] to other effects in the stack.

There are also a few intercept methods to use an effect but still leave it in the stack

Interpret eff values

For stack-safety reasons, the continuation must never be called with a value directly, but always with Eff.impure:

Eff.impure(a, continuation)

• Note it is the responsibility of the implementation to call continuation.onNone if the continuation is not used to create the return value.

Typeclass proving that it is possible to send a tree of effects R into another tree of effects U

for example

Encapsulation of one optional last action to execute at the end of the program

Effect for computations possibly returning several values

list of Member instances for a given stack R

Memoization effect

Memoize a computation for a given key

This effect can be interpreted with a cache implemented with many different libraries. See Cache.scala for 2 default implementations:

• one concurrent hashmap (meaning an unbounded cache)
• one concurrent hashmap with weak references (to evict entries based on garbage collection)

You can implement your own version using ScalaCache for example

The "empty" tree of effects

Effect for optional computations

This class can be used as a F in runChoose to generate random alternatives

Effect for computations depending on an environment.

The inside datatype for this effect is cats.data.Reader

Helper trait for computations which might produce several M[X] in a stack of effects.

Either we can produce an X to pass to a continuation or we're done

For the applicative case we expect to be able to traverse a list of effects and return an effect of a list of results OR completely consume the effect and return a pure list of values

support trait for folding values while possibly keeping some internal state

The Safe type is a mix of a ThrowableEither / Eval effect and a writer effect to collect finalizer failures

type class for effects which can be cached in a SequenceCache

Effect for passing state along computations

Internally backed up by cats.data.State

This effect is used in the implementation of the Async effect

trait for translating one effect into other ones in the same stack

transform a Union for a given stack into a Union for another stack

A non-empty list of Unions.

It is only partially typed, we just keep track of the type of the first object

Effect for computation which can fail but will accumulate errors

The runValidate interpreter just collects the messages and returns them at the end

Effect for logging values alongside computations

Compared to traditional Writer monad which accumulates values by default this effect can be interpreted in different ways:

• log values to the console or to a file as soon as they are produced
• accumulate values in a list