GenConcurrent

Implicitly added by genConcurrentForOptionT

Pair the result of function application with A.

Example:
{{{
scala> import cats.Functor
scala> import cats.implicits.catsStdInstancesForOption

scala> Functor[Option] .fproductLeft(Option(42))(_.toString)
res0: Option[(String, Int)] = Some((42,42))
}}}

Inhertied from: Functor

Implicitly added by genConcurrentForOptionT

Pair A with the result of function application.

Example:
{{{
scala> import cats.implicits._
scala> List("12", "34", "56").mproduct(_.toList)
res0: List[(String, Char)] = List((12,1), (12,2), (34,3), (34,4), (56,5), (56,6))
}}}

Inhertied from: FlatMap

@noop

Implicitly added by genConcurrentForOptionT

Execute an action repeatedly as long as the given Boolean expression
returns true. The condition is evaluated before the loop body.
Discards results.

Inhertied from: Monad

Implicitly added by genConcurrentForOptionT

Races the evaluation of two fibers that returns the Outcome of the
winner. The winner of the race is considered to be the first fiber that
completes with an outcome. The loser of the race is canceled before
returning.

Value Params

fa: the effect for the first racing fiber
fb: the effect for the second racing fiber

See also

race for a simpler variant that returns the successful outcome.

Inhertied from

GenSpawn

@inline

Implicitly added by genConcurrentForOptionT

Alias for productR.

Inhertied from: Apply

@noop

Implicitly added by genConcurrentForOptionT

Un-zips an F[(A, B)] consisting of element pairs or Tuple2 into two separate F's tupled.

NOTE: Check for effect duplication, possibly memoize before

{{{
scala> import cats.Functor
scala> import cats.implicits.catsStdInstancesForList

scala> Functor[List] .unzip(List((1,2), (3, 4)))
res0: (List[Int] , List[Int] ) = (List(1, 3),List(2, 4))
}}}

Inhertied from: Functor

Implicitly added by genConcurrentForOptionT

Handle any error, by mapping it to an A value.

See also: handleErrorWith to map to an F[A] value instead of simply an
A value.

recover to only recover from certain errors.
Inhertied from: ApplicativeError

Implicitly added by genConcurrentForOptionT

Replaces the A value in F[A] with the supplied value.

Example:

{{{
scala> import cats.Functor
scala> import cats.implicits.catsStdInstancesForList

scala> Functor[List] .as(List(1,2,3), "hello")
res0: List[String] = List(hello, hello, hello)
}}}

Inhertied from: Functor

Implicitly added by genConcurrentForOptionT

Similar to attempt, but it only handles errors of type EE.

Inhertied from: ApplicativeError

Implicitly added by genConcurrentForOptionT

Convert from scala.Option

Example:
{{{
scala> import cats.implicits._
scala> import cats.ApplicativeError
scala> val F = ApplicativeError[Either[String, *] , String]

scala> F.fromOption(Some(1), "Empty")
res0: scala.Either[String, Int] = Right(1)

scala> F.fromOption(Option.empty[Int] , "Empty")
res1: scala.Either[String, Int] = Left(Empty)
}}}

Inhertied from: ApplicativeError

Implicitly added by genConcurrentForOptionT

Convert from scala.Either

Example:
{{{
scala> import cats.ApplicativeError
scala> import cats.instances.option._

scala> ApplicativeError[Option, Unit] .fromEither(Right(1))
res0: scala.Option[Int] = Some(1)

scala> ApplicativeError[Option, Unit] .fromEither(Left(()))
res1: scala.Option[Nothing] = None
}}}

Inhertied from: ApplicativeError

Implicitly added by genConcurrentForOptionT

Specifies an effect that is always invoked after evaluation of fa
completes, regardless of the outcome.

This function can be thought of as a combination of
flatTap, onError, and
onCancel.

Value Params

fa: The effect that is run after fin is registered.
fin: The effect to run in the event of a cancellation or error.

See also

guaranteeCase for a more powerful variant

Outcome for the various outcomes of evaluation

Inhertied from

MonadCancel

Implicitly added by genConcurrentForOptionT

Inhertied from: FlatMap

Implicitly added by genConcurrentForOptionT

A pattern for safely interacting with effectful lifecycles.

If acquire completes successfully, use is called. If use succeeds,
fails, or is canceled, release is guaranteed to be called exactly once.

acquire is uncancelable.
release is uncancelable.
use is cancelable by default, but can be masked.

Value Params

acquire: the lifecycle acquisition action
release: the lifecycle release action which depends on the outcome of use
use: the effect to which the lifecycle is scoped, whose result
is the return value of this function

See also

bracketFull for a more powerful variant

Resource for a composable datatype encoding of effectful lifecycles

Inhertied from

MonadCancel

@noop

Implicitly added by genConcurrentForOptionT

Execute an action repeatedly as long as the given Boolean expression
returns true. The condition is evaluated before the loop body.
Collects the results into an arbitrary Alternative value, such as a Vector.
This implementation uses append on each evaluation result,
so avoid data structures with non-constant append performance, e.g. List.

Inhertied from: Monad

@noop

Implicitly added by genConcurrentForOptionT

This repeats an F until we get defined values. This can be useful
for polling type operations on State (or RNG) Monads, or in effect
monads.

Inhertied from: FlatMap

Implicitly added by genConcurrentForOptionT

Tuple the values in fa with the result of applying a function
with the value

Example:
{{{
scala> import cats.Functor
scala> import cats.implicits.catsStdInstancesForOption

scala> Functor[Option] .fproduct(Option(42))(_.toString)
res0: Option[(Int, String)] = Some((42,42))
}}}

Inhertied from: Functor

@noop

Implicitly added by genConcurrentForOptionT

Simulates an if/else-if/else in the context of an F. It evaluates conditions until
one evaluates to true, and returns the associated F[A] . If no condition is true,
returns els.

{{{
scala> import cats._
scala> Monad[Eval] .ifElseM(Eval.later(false) -> Eval.later(1), Eval.later(true) -> Eval.later(2))(Eval.later(5)).value
res0: Int = 2
}}}

Based on a gist by Daniel Spiewak with a stack-safe
implementation due to P. Oscar Boykin

See also: See https://gitter.im/typelevel/cats-effect?at=5f297e4314c413356f56d230 for the discussion.
Inhertied from: Monad

Implicitly added by genConcurrentForOptionT

Registers a finalizer that is invoked if cancellation is observed
during the evaluation of fa. If the evaluation of fa completes
without encountering a cancellation, the finalizer is unregistered
before proceeding.

During finalization, all actively registered finalizers are run exactly
once. The order by which finalizers are run is dictated by nesting:
innermost finalizers are run before outermost finalizers. For example,
in the following program, the finalizer f1 is run before the finalizer
f2:

{{{

F.onCancel(F.onCancel(F.canceled, f1), f2)

}}}

If a finalizer throws an error during evaluation, the error is suppressed,
and implementations may choose to report it via a side channel. Finalizers
are always uncancelable, so cannot otherwise be interrupted.

Value Params

fa: The effect that is evaluated after fin is registered.
fin: The finalizer to register before evaluating fa.

Inhertied from

MonadCancel

Implicitly added by genConcurrentForOptionT

point lifts any value into a Monoidal Functor.

Example:
{{{
scala> import cats.implicits._

scala> InvariantMonoidal[Option] .point(10)
res0: Option[Int] = Some(10)
}}}

Inhertied from: InvariantMonoidal

Implicitly added by genConcurrentForOptionT

Similar to map2 but uses Eval to allow for laziness in the F[B]
argument. This can allow for "short-circuiting" of computations.

NOTE: the default implementation of map2Eval does not short-circuit
computations. For data structures that can benefit from laziness, Apply
instances should override this method.

In the following example, x.map2(bomb)(_ + _) would result in an error,
but map2Eval "short-circuits" the computation. x is None and thus the
result of bomb doesn't even need to be evaluated in order to determine
that the result of map2Eval should be None.

{{{
scala> import cats.{Eval, Later}
scala> import cats.implicits._
scala> val bomb: Eval[Option[Int] ] = Later(sys.error("boom"))
scala> val x: Option[Int] = None
scala> x.map2Eval(bomb)(_ + _).value
res0: Option[Int] = None
}}}

Inhertied from: Apply

Implicitly added by genConcurrentForOptionT

Convert from cats.data.Validated

Example:
{{{
scala> import cats.implicits._
scala> import cats.ApplicativeError

scala> ApplicativeError[Option, Unit] .fromValidated(1.valid[Unit] )
res0: scala.Option[Int] = Some(1)

scala> ApplicativeError[Option, Unit] .fromValidated(().invalid[Int] )
res1: scala.Option[Int] = None
}}}

Inhertied from: ApplicativeError

Implicitly added by genConcurrentForOptionT

Execute an action repeatedly until its result fails to satisfy the given predicate
and return that result, discarding all others.

Inhertied from: Monad

Implicitly added by genConcurrentForOptionT

Lift an error into the F context.

Example:
{{{
scala> import cats.implicits._

// integer-rounded division
scala> def divide[F[_] ](dividend: Int, divisor: Int)(implicit F: ApplicativeError[F, String] ): F[Int] =
| if (divisor === 0) F.raiseError("division by zero")
| else F.pure(dividend / divisor)

scala> type ErrorOr[A] = Either[String, A]

scala> divide[ErrorOr] (6, 3)
res0: ErrorOr[Int] = Right(2)

scala> divide[ErrorOr] (6, 0)
res1: ErrorOr[Int] = Left(division by zero)
}}}

Inhertied from: ApplicativeError

Implicitly added by genConcurrentForOptionT

If the error type is Throwable, we can convert from a scala.util.Try

Inhertied from: ApplicativeError

Implicitly added by genConcurrentForOptionT

Compose Invariant F[_] and Functor G[_] then produce Invariant[F[G[_]]]
using F's imap and G's map.

Example:
{{{
scala> import cats.implicits._
scala> import scala.concurrent.duration._

scala> val durSemigroupList: Semigroup[List[FiniteDuration] ] =
| Invariant[Semigroup]
| .composeFunctor[List]
| .imap(Semigroup[List[Long] ])(Duration.fromNanos)(_.toNanos)
scala> durSemigroupList.combine(List(2.seconds, 3.seconds), List(4.seconds))
res1: List[FiniteDuration] = List(2 seconds, 3 seconds, 4 seconds)
}}}

Inhertied from: Invariant

Implicitly added by genConcurrentForOptionT

Inhertied from: InvariantSemigroupal

Implicitly added by genConcurrentForOptionT

Recover from certain errors by mapping them to an F[A] value.

See also: handleErrorWith to handle any/all errors.

recover to recover from certain errors by mapping them to A
values.
Inhertied from: ApplicativeError

Implicitly added by genConcurrentForOptionT

"flatten" a nested F of F structure into a single-layer F structure.

This is also commonly called join.

Example:
{{{
scala> import cats.Eval
scala> import cats.implicits._

scala> val nested: Eval[Eval[Int] ] = Eval.now(Eval.now(3))
scala> val flattened: Eval[Int] = nested.flatten
scala> flattened.value
res0: Int = 3
}}}

Inhertied from: FlatMap

Implicitly added by genConcurrentForOptionT

Execute an action repeatedly until the Boolean condition returns true.
The condition is evaluated after the loop body. Collects results into an
arbitrary Alternative value, such as a Vector.
This implementation uses append on each evaluation result,
so avoid data structures with non-constant append performance, e.g. List.

Inhertied from: Monad

Implicitly added by genConcurrentForOptionT

Returns an F[Unit] value, equivalent with pure(()).

A useful shorthand, also allowing implementations to optimize the
returned reference (e.g. it can be a val).

Example:
{{{
scala> import cats.implicits._

scala> Applicative[Option] .unit
res0: Option[Unit] = Some(())
}}}

Inhertied from: Applicative

Implicitly added by genConcurrentForOptionT

Execute an action repeatedly until the Boolean condition returns true.
The condition is evaluated after the loop body. Discards results.

Inhertied from: Monad

Implicitly added by genConcurrentForOptionT

Returns a Resource that manages the concurrent execution of a fiber.
The inner effect can be used to wait on the outcome of the child fiber;
it is effectively a join.

The child fiber is canceled in two cases: either the resource goes out
of scope or the parent fiber is cancelled. If the child fiber terminates
before one of these cases occurs, then cancellation is a no-op. This
avoids fiber leaks because the child fiber is always canceled before
the parent fiber drops the reference to it.

{{{

// Starts a fiber that continously prints "A".
// After 10 seconds, the resource scope exits so the fiber is canceled.
F.background(F.delay(println("A")).foreverM).use { _ =>
F.sleep(10.seconds)
}

}}}

Value Params

fa: the effect for the spawned fiber

Inhertied from

GenSpawn

Implicitly added by genConcurrentForOptionT

Tuples the A value in F[A] with the supplied B value, with the B value on the left.

Example:
{{{
scala> import scala.collection.immutable.Queue
scala> import cats.Functor
scala> import cats.implicits.catsStdInstancesForQueue

scala> Functor[Queue] .tupleLeft(Queue("hello", "world"), 42)
res0: scala.collection.immutable.Queue[(Int, String)] = Queue((42,hello), (42,world))
}}}

Inhertied from: Functor

Implicitly added by genConcurrentForOptionT

Handle any error, potentially recovering from it, by mapping it to an
F[A] value.

See also: handleError to handle any error by simply mapping it to an A
value instead of an F[A].

recoverWith to recover from only certain errors.
Inhertied from: ApplicativeError

Implicitly added by genConcurrentForOptionT

Apply a monadic function and discard the result while keeping the effect.

{{{
scala> import cats., implicits.
scala> Option(1).flatTap(_ => None)
res0: Option[Int] = None
scala> Option(1).flatTap(_ => Some("123"))
res1: Option[Int] = Some(1)
scala> def nCats(n: Int) = List.fill(n)("cat")
nCats: (n: Int)List[String]
scala> ListInt.flatTap(nCats)
res2: List[Int] = List()
scala> ListInt.flatTap(nCats)
res3: List[Int] = List(4, 4, 4, 4)
}}}

Inhertied from: FlatMap

Implicitly added by genConcurrentForOptionT

Masks cancellation on the current fiber. The argument to body of type
Poll[F] is a natural transformation F ~> F that enables polling.
Polling causes a fiber to unmask within a masked region so that
cancellation can be observed again.

In the following example, cancellation can be observed only within fb
and nowhere else:

{{{

F.uncancelable { poll =>
fa *> poll(fb) *> fc
}

}}}

If a fiber is canceled while it is masked, the cancellation is suppressed
for as long as the fiber remains masked. Whenever the fiber is completely
unmasked again, the cancellation will be respected.

Masks can also be stacked or nested within each other. If multiple masks
are active, all masks must be undone so that cancellation can be observed.
In order to completely unmask within a multi-masked region, the poll
corresponding to each mask must be applied, innermost-first.

{{{

F.uncancelable { p1 =>
F.uncancelable { p2 =>
fa *> p2(p1(fb)) *> fc
}
}

}}}

The following operations are no-ops:

Polling in the wrong order
Applying the same poll more than once: poll(poll(fa))
Applying a poll bound to one fiber within another fiber

Inhertied from: MonadCancel

Implicitly added by genConcurrentForOptionT

Inhertied from: GenSpawn

Implicitly added by genConcurrentForOptionT

Turns a successful value into an error if it does not satisfy a given predicate.

Inhertied from: MonadError

Implicitly added by genConcurrentForOptionT

Sequentially compose two actions, discarding any value produced by the second. This variant of
productL also lets you define the evaluation strategy of the second action. For instance
you can evaluate it only ''after'' the first action has finished:

{{{
scala> import cats.Eval
scala> import cats.implicits._
scala> var count = 0
scala> val fa: Option[Int] = Some(3)
scala> def fb: Option[Unit] = Some(count += 1)
scala> fa.productLEval(Eval.later(fb))
res0: Option[Int] = Some(3)
scala> assert(count == 1)
scala> none[Int] .productLEval(Eval.later(fb))
res1: Option[Int] = None
scala> assert(count == 1)
}}}

Inhertied from: FlatMap

Implicitly added by genConcurrentForOptionT

Sequentially compose two actions, discarding any value produced by the first. This variant of
productR also lets you define the evaluation strategy of the second action. For instance
you can evaluate it only ''after'' the first action has finished:

{{{
scala> import cats.Eval
scala> import cats.implicits._
scala> val fa: Option[Int] = Some(3)
scala> def fb: Option[String] = Some("foo")
scala> fa.productREval(Eval.later(fb))
res0: Option[String] = Some(foo)
}}}

Inhertied from: FlatMap

Implicitly added by genConcurrentForOptionT

Execute a callback on certain errors, then rethrow them.
Any non matching error is rethrown as well.

In the following example, only one of the errors is logged,
but they are both rethrown, to be possibly handled by another
layer of the program:

{{{
scala> import cats., data., implicits._

scala> case class Err(msg: String)

scala> type F[A] = EitherT[State[String, *] , Err, A]

scala> val action: PartialFunction[Err, F[Unit] ] = {
| case Err("one") => EitherT.liftF(State.set("one"))
| }

scala> val prog1: F[Int] = (Err("one")).raiseError[F, Int]
scala> val prog2: F[Int] = (Err("two")).raiseError[F, Int]

scala> prog1.onError(action).value.run("").value

res0: (String, Either[Err,Int] ) = (one,Left(Err(one)))

scala> prog2.onError(action).value.run("").value
res1: (String, Either[Err,Int] ) = ("",Left(Err(two)))
}}}

Inhertied from: ApplicativeError

Implicitly added by genConcurrentForOptionT

Evaluates the specified block, catching exceptions of the specified type. Uncaught exceptions are propagated.

Inhertied from: ApplicativeError

Implicitly added by genConcurrentForOptionT

Returns a new value that transforms the result of the source,
given the recover or map functions, which get executed depending
on whether the result is successful or if it ends in error.

This is an optimization on usage of attempt and map,
this equivalence being available:

{{{
fa.redeem(fe, fs) <-> fa.attempt.map(_.fold(fe, fs))
}}}

Usage of redeem subsumes handleError because:

{{{
fa.redeem(fe, id) <-> fa.handleError(fe)
}}}

Implementations are free to override it in order to optimize
error recovery.

Value Params

fa: is the source whose result is going to get transformed
recover: is the function that gets called to recover the source
in case of error

See also

MonadError.redeemWith, attempt and handleError

Inhertied from

ApplicativeError

Implicitly added by genConcurrentForOptionT

Lift a function f to operate on Functors

Example:
{{{
scala> import cats.Functor
scala> import cats.implicits.catsStdInstancesForOption

scala> val o = Option(42)
scala> Functor[Option] .lift((x: Int) => x + 10)(o)
res0: Option[Int] = Some(52)
}}}

Inhertied from: Functor

Implicitly added by genConcurrentForOptionT

Turns a successful value into an error specified by the error function if it does not satisfy a given predicate.

Inhertied from: MonadError

Implicitly added by genConcurrentForOptionT

Apply a monadic function iteratively until its result satisfies
the given predicate and return that result.

Inhertied from: Monad

Implicitly added by genConcurrentForOptionT

Returns a new value that transforms the result of the source,
given the recover or bind functions, which get executed depending
on whether the result is successful or if it ends in error.

This is an optimization on usage of attempt and flatMap,
this equivalence being available:

{{{
fa.redeemWith(fe, fs) <-> fa.attempt.flatMap(_.fold(fe, fs))
}}}

Usage of redeemWith subsumes handleErrorWith because:

{{{
fa.redeemWith(fe, F.pure) <-> fa.handleErrorWith(fe)
}}}

Usage of redeemWith also subsumes flatMap because:

{{{
fa.redeemWith(F.raiseError, fs) <-> fa.flatMap(fs)
}}}

Implementations are free to override it in order to optimize
error recovery.

Value Params

bind: is the function that gets to transform the source
in case of success
fa: is the source whose result is going to get transformed
recover: is the function that gets called to recover the source
in case of error

See also

redeem, attempt and handleErrorWith

Inhertied from

MonadError

Implicitly added by genConcurrentForOptionT

Given fa and n, apply fa n times to construct an F[List[A]] value.

Example:
{{{
scala> import cats.data.State

scala> type Counter[A] = State[Int, A]
scala> val getAndIncrement: Counter[Int] = State { i => (i + 1, i) }
scala> val getAndIncrement5: Counter[List[Int] ] =
| Applicative[Counter] .replicateA(5, getAndIncrement)
scala> getAndIncrement5.run(0).value
res0: (Int, List[Int] ) = (5,List(0, 1, 2, 3, 4))
}}}

Inhertied from: Applicative

Implicitly added by genConcurrentForOptionT

A low-level primitive for starting the concurrent evaluation of a fiber.
Returns a Fiber that can be used to wait for a fiber or cancel it.

start is a cancellation-unsafe function; it is recommended to
use the safer variant, background, to spawn fibers.

Value Params

fa: the effect for the fiber

See also

background for the safer, recommended variant

Inhertied from

GenSpawn

Implicitly added by genConcurrentForOptionT

Apply a monadic function iteratively until its result fails
to satisfy the given predicate and return that result.

Inhertied from: Monad

Implicitly added by genConcurrentForOptionT

Compose an Applicative[F] and a ContravariantMonoidal[G] into a
ContravariantMonoidal[λ[α => F[G[α]]]].

Example:
{{{
scala> import cats.kernel.Comparison
scala> import cats.implicits._

// compares strings by alphabetical order
scala> val alpha: Order[String] = Order[String]

// compares strings by their length
scala> val strLength: Order[String] = Order.byString, Int

scala> val stringOrders: List[Order[String] ] = List(alpha, strLength)

// first comparison is with alpha order, second is with string length
scala> stringOrders.map(o => o.comparison("abc", "de"))
res0: List[Comparison] = List(LessThan, GreaterThan)

scala> val le = Applicative[List] .composeContravariantMonoidal[Order]

// create Int orders that convert ints to strings and then use the string orders
scala> val intOrders: List[Order[Int] ] = le.contramap(stringOrders)(_.toString)

// first comparison is with alpha order, second is with string length
scala> intOrders.map(o => o.comparison(12, 3))
res1: List[Comparison] = List(LessThan, GreaterThan)

// create the product of the string order list and the int order list
// p contains a list of the following orders:
// 1. (alpha comparison on strings followed by alpha comparison on ints)
// 2. (alpha comparison on strings followed by length comparison on ints)
// 3. (length comparison on strings followed by alpha comparison on ints)
// 4. (length comparison on strings followed by length comparison on ints)
scala> val p: List[Order[(String, Int)] ] = le.product(stringOrders, intOrders)

scala> p.map(o => o.comparison(("abc", 12), ("def", 3)))
res2: List[Comparison] = List(LessThan, LessThan, LessThan, GreaterThan)
}}}

Inhertied from: Applicative

Implicitly added by genConcurrentForOptionT

A pattern for safely interacting with effectful lifecycles.

If acquire completes successfully, use is called. If use succeeds,
fails, or is canceled, release is guaranteed to be called exactly once.

If use succeeds the returned value B is returned. If use returns
an exception, the exception is returned.

acquire is uncancelable by default, but can be unmasked.
release is uncancelable.
use is cancelable by default, but can be masked.

Value Params

acquire: the lifecycle acquisition action which can be canceled
release: the lifecycle release action which depends on the outcome of use
use: the effect to which the lifecycle is scoped, whose result
is the return value of this function

Inhertied from

MonadCancel

@noop

Implicitly added by genConcurrentForOptionT

An if-then-else lifted into the F context.
This function combines the effects of the fcond condition and of the two branches,
in the order in which they are given.

The value of the result is, depending on the value of the condition,
the value of the first argument, or the value of the second argument.

Example:
{{{
scala> import cats.implicits._

scala> val b1: Option[Boolean] = Some(true)
scala> val asInt1: Option[Int] = Apply[Option] .ifA(b1)(Some(1), Some(0))
scala> asInt1.get
res0: Int = 1

scala> val b2: Option[Boolean] = Some(false)
scala> val asInt2: Option[Int] = Apply[Option] .ifA(b2)(Some(1), Some(0))
scala> asInt2.get
res1: Int = 0

scala> val b3: Option[Boolean] = Some(true)
scala> val asInt3: Option[Int] = Apply[Option] .ifA(b3)(Some(1), None)
asInt2: Option[Int] = None

}}}

Inhertied from: Apply

Implicitly added by genConcurrentForOptionT

Often E is Throwable. Here we try to call pure or catch
and raise.

Inhertied from: ApplicativeError

@noop

Implicitly added by genConcurrentForOptionT

Lifts if to Functor

Example:
{{{
scala> import cats.Functor
scala> import cats.implicits.catsStdInstancesForList

scala> Functor[List] .ifF(List(true, false, false))(1, 0)
res0: List[Int] = List(1, 0, 0)
}}}

Inhertied from: Functor

Implicitly added by genConcurrentForOptionT

Similar to attempt, but wraps the result in a data.EitherT for
convenience.

Inhertied from: ApplicativeError

Implicitly added by genConcurrentForOptionT

An effect that requests self-cancellation on the current fiber.

In the following example, the fiber requests self-cancellation in a masked
region, so cancellation is suppressed until the fiber is completely
unmasked. fa will run but fb will not.

{{{

F.uncancelable { _ =>
F.canceled *> fa
} *> fb

}}}

Inhertied from: MonadCancel

Implicitly added by genConcurrentForOptionT

Returns the given argument (mapped to Unit) if cond is true, otherwise,
unit lifted into F.

Example:
{{{
scala> import cats.implicits._

scala> Applicative[List] .whenA(true)(List(1, 2, 3))
res0: List[Unit] = List((), (), ())

scala> Applicative[List] .whenA(false)(List(1, 2, 3))
res1: List[Unit] = List(())

scala> Applicative[List] .whenA(true)(List.empty[Int] )
res2: List[Unit] = List()

scala> Applicative[List] .whenA(false)(List.empty[Int] )
res3: List[Unit] = List(())
}}}

Inhertied from: Applicative

@noop

Implicitly added by genConcurrentForOptionT

iterateForeverM is almost exclusively useful for effect types. For instance,
A may be some state, we may take the current state, run some effect to get
a new state and repeat.

Inhertied from: FlatMap

@noop

Implicitly added by genConcurrentForOptionT

Like an infinite loop of >> calls. This is most useful effect loops
that you want to run forever in for instance a server.

This will be an infinite loop, or it will return an F[Nothing] .

Be careful using this.
For instance, a List of length k will produce a list of length k^n at iteration
n. This means if k = 0, we return an empty list, if k = 1, we loop forever
allocating single element lists, but if we have a k > 1, we will allocate
exponentially increasing memory and very quickly OOM.

Inhertied from: FlatMap

Implicitly added by genConcurrentForOptionT

Lifts natural subtyping covariance of covariant Functors.

NOTE: In certain (perhaps contrived) situations that rely on universal
equality this can result in a ClassCastException, because it is
implemented as a type cast. It could be implemented as map(identity), but
according to the functor laws, that should be equal to fa, and a type
cast is often much more performant.
See this example
of widen creating a ClassCastException.

Example:
{{{
scala> import cats.Functor
scala> import cats.implicits.catsStdInstancesForOption

scala> val s = Some(42)
scala> Functor[Option] .widen(s)
res0: Option[Int] = Some(42)
}}}

Inhertied from: Functor

Implicitly added by genConcurrentForOptionT

Inhertied from: ApplyArityFunctions

Implicitly added by genConcurrentForOptionT

Often E is Throwable. Here we try to call pure or catch
and raise

Inhertied from: ApplicativeError

Implicitly added by genConcurrentForOptionT

Handle errors by turning them into scala.util.Either values.

If there is no error, then an scala.util.Right value will be returned instead.

All non-fatal errors should be handled by this method.

Inhertied from: ApplicativeError

Implicitly added by genConcurrentForOptionT

Introduces a fairness boundary that yields control back to the scheduler
of the runtime system. This allows the carrier thread to resume execution
of another waiting fiber.

Note that cede is merely a hint to the runtime system; implementations
have the liberty to interpret this method to their liking as long as it
obeys the respective laws. For example, a lawful, but atypical,
implementation of this function is F.unit, in which case the fairness
boundary is a no-op.

Inhertied from: GenSpawn

Implicitly added by genConcurrentForOptionT

Alias for map, since map can't be injected as syntax if
the implementing type already had a built-in .map method.

Example:
{{{
scala> import cats.implicits._

scala> val m: Map[Int, String] = Map(1 -> "hi", 2 -> "there", 3 -> "you")

scala> m.fmap(_ ++ "!")
res0: Map[Int,String] = Map(1 -> hi!, 2 -> there!, 3 -> you!)
}}}

Inhertied from: Functor

Implicitly added by genConcurrentForOptionT

Tuples the A value in F[A] with the supplied B value, with the B value on the right.

Example:
{{{
scala> import scala.collection.immutable.Queue
scala> import cats.Functor
scala> import cats.implicits.catsStdInstancesForQueue

scala> Functor[Queue] .tupleRight(Queue("hello", "world"), 42)
res0: scala.collection.immutable.Queue[(String, Int)] = Queue((hello,42), (world,42))
}}}

Inhertied from: Functor

Implicitly added by genConcurrentForOptionT

Keeps calling f until a scala.util.Right[B] is returned.

Based on Phil Freeman's
Stack Safety for Free.

Implementations of this method should use constant stack space relative to f.

Inhertied from: FlatMap

Implicitly added by genConcurrentForOptionT

Inverse of attempt

Example:
{{{
scala> import cats.implicits._
scala> import scala.util.{Try, Success}

scala> val a: Try[Either[Throwable, Int] ] = Success(Left(new java.lang.Exception))
scala> a.rethrow
res0: scala.util.Try[Int] = Failure(java.lang.Exception)

scala> val b: Try[Either[Throwable, Int] ] = Success(Right(1))
scala> b.rethrow
res1: scala.util.Try[Int] = Success(1)
}}}

Inhertied from: MonadError

Implicitly added by genConcurrentForOptionT

Returns the given argument (mapped to Unit) if cond is false,
otherwise, unit lifted into F.

Example:
{{{
scala> import cats.implicits._

scala> Applicative[List] .unlessA(true)(List(1, 2, 3))
res0: List[Unit] = List(())

scala> Applicative[List] .unlessA(false)(List(1, 2, 3))
res1: List[Unit] = List((), (), ())

scala> Applicative[List] .unlessA(true)(List.empty[Int] )
res2: List[Unit] = List(())

scala> Applicative[List] .unlessA(false)(List.empty[Int] )
res3: List[Unit] = List()
}}}

Inhertied from: Applicative

Implicitly added by genConcurrentForOptionT

Reifies the value or error of the source and performs an effect on the result,
then recovers the original value or error back into F.

Note that if the effect returned by f fails, the resulting effect will fail too.

Alias for fa.attempt.flatTap(f).rethrow for convenience.

Example:
{{{
scala> import cats.implicits._
scala> import scala.util.{Try, Success, Failure}

scala> def checkError(result: Either[Throwable, Int] ): Try[String] = result.fold(_ => Failure(new java.lang.Exception), _ => Success("success"))

scala> val a: Try[Int] = Failure(new Throwable("failed"))
scala> a.attemptTap(checkError)
res0: scala.util.Try[Int] = Failure(java.lang.Exception)

scala> val b: Try[Int] = Success(1)
scala> b.attemptTap(checkError)
res1: scala.util.Try[Int] = Success(1)
}}}

Inhertied from: MonadError

Implicitly added by genConcurrentForOptionT

Empty the fa of the values, preserving the structure

Example:
{{{
scala> import cats.Functor
scala> import cats.implicits.catsStdInstancesForList

scala> Functor[List] .void(List(1,2,3))
res0: List[Unit] = List((), (), ())
}}}

Inhertied from: Functor

@inline

Implicitly added by genConcurrentForOptionT

Alias for productL.

Inhertied from: Apply

@noop

Implicitly added by genConcurrentForOptionT

if lifted into monad.

Inhertied from: FlatMap

Implicitly added by genConcurrentForOptionT

Specifies an effect that is always invoked after evaluation of fa
completes, but depends on the outcome.

This function can be thought of as a combination of
flatTap, onError, and
onCancel.

Value Params

fa: The effect that is run after fin is registered.
fin: A function that returns the effect to run based on the
outcome.

See also

bracketCase for a more powerful variant

Outcome for the various outcomes of evaluation

Inhertied from

MonadCancel

Implicitly added by genConcurrentForOptionT

Compose an Applicative[F] and an Applicative[G] into an
Applicative[λ[α => F[G[α]]]].

Example:
{{{
scala> import cats.implicits._

scala> val alo = Applicative[List] .compose[Option]

scala> alo.pure(3)
res0: List[Option[Int] ] = List(Some(3))

scala> alo.product(List(None, Some(true), Some(false)), List(Some(2), None))
res1: List[Option[(Boolean, Int)] ] = List(None, None, Some((true,2)), None, Some((false,2)), None)
}}}

Inhertied from: Applicative

Implicitly added by genConcurrentForOptionT

Compose Invariant F[_] and G[_] then produce Invariant[F[G[_]]] using their imap.

Example:
{{{
scala> import cats.implicits._
scala> import scala.concurrent.duration._

scala> val durSemigroupList: Semigroup[List[FiniteDuration] ] =
| Invariant[Semigroup] .compose[List] .imap(Semigroup[List[Long] ])(Duration.fromNanos)(_.toNanos)
scala> durSemigroupList.combine(List(2.seconds, 3.seconds), List(4.seconds))
res1: List[FiniteDuration] = List(2 seconds, 3 seconds, 4 seconds)
}}}

Inhertied from: Invariant

Implicitly added by genConcurrentForOptionT

Compose an Apply[F] and an Apply[G] into an Apply[λ[α => F[G[α]]]].

Example:
{{{
scala> import cats.implicits._

scala> val alo = Apply[List] .compose[Option]

scala> alo.product(List(None, Some(true), Some(false)), List(Some(2), None))
res1: List[Option[(Boolean, Int)] ] = List(None, None, Some((true,2)), None, Some((false,2)), None)
}}}

Inhertied from: Apply

Implicitly added by genConcurrentForOptionT

Inhertied from: Functor

Implicitly added by genConcurrentForOptionT

Execute an action repeatedly until its result satisfies the given predicate
and return that result, discarding all others.

Inhertied from: Monad

Implicitly added by genConcurrentForOptionT

Races the evaluation of two fibers and returns the Outcome of both. If
the race is canceled before one or both participants complete, then
then whichever ones are incomplete are canceled.

Value Params

fa: the effect for the first racing fiber
fb: the effect for the second racing fiber

See also

both for a simpler variant that returns the results of both
fibers.

Inhertied from

GenSpawn

Implicitly added by genConcurrentForOptionT

Races the evaluation of two fibers that returns the result of the winner,
except in the case of cancellation.

The semantics of race are described by the following rules:

If the winner completes with Succeeded, the race returns the
successful value. The loser is canceled before returning.
If the winner completes with Errored, the race raises the error.
The loser is canceled before returning.
If the winner completes with Canceled, the race returns the
result of the loser, consistent with the first two rules.
If both the winner and loser complete with Canceled, the race
is canceled.
If the race is masked and is canceled because both participants
canceled, the fiber will block indefinitely.

Value Params

fa: the effect for the first racing fiber
fb: the effect for the second racing fiber

See also

raceOutcome for a variant that returns the outcome of the winner.

Inhertied from

GenSpawn

Implicitly added by genConcurrentForOptionT

A non-terminating effect that never completes, which causes a fiber to
semantically block indefinitely. This is the purely functional,
asynchronous equivalent of an infinite while loop in Java, but no
native threads are blocked.

A fiber that is suspended in never can be canceled if it is
completely unmasked before it suspends:

{{{

// ignoring race conditions between start and cancel
F.never.start.flatMap(_.cancel) <-> F.unit

}}}

However, if the fiber is masked, cancellers will be semantically blocked
forever:

{{{

// ignoring race conditions between start and cancel
F.uncancelable(_ => F.never).start.flatMap(_.cancel) <-> F.never

}}}

Inhertied from: GenSpawn

Implicitly added by genConcurrentForOptionT

Races the evaluation of two fibers and returns the result of both.

The following rules describe the semantics of both:

If the winner completes with Succeeded, the race waits for the
loser to complete.
If the winner completes with Errored, the race raises the error.
The loser is canceled.
If the winner completes with Canceled, the loser and the race
are canceled as well.
If the loser completes with Succeeded, the race returns the
successful value of both fibers.
If the loser completes with Errored, the race returns the error.
If the loser completes with Canceled, the race is canceled.
If the race is canceled before one or both participants complete,
then whichever ones are incomplete are canceled.
If the race is masked and is canceled because one or both
participants canceled, the fiber will block indefinitely.

Value Params

fa: the effect for the first racing fiber
fb: the effect for the second racing fiber

See also

bothOutcome for a variant that returns the Outcome of both
fibers.

Inhertied from

GenSpawn

Implicitly added by genConcurrentForOptionT

Recover from certain errors by mapping them to an A value.

See also: handleError to handle any/all errors.

recoverWith to recover from certain errors by mapping them to
F[A] values.
Inhertied from: ApplicativeError

Implicitly added by genConcurrentForOptionT

Analogous to productR, but suppresses short-circuiting behavior
except for cancellation.

Inhertied from: MonadCancel

@inline

Implicitly added by genConcurrentForOptionT

Alias for ap.

Inhertied from: Apply

Implicitly added by genConcurrentForOptionT

A pattern for safely interacting with effectful lifecycles.

If acquire completes successfully, use is called. If use succeeds,
fails, or is canceled, release is guaranteed to be called exactly once.

acquire is uncancelable.
release is uncancelable.
use is cancelable by default, but can be masked.

Value Params

acquire: the lifecycle acquisition action
release: the lifecycle release action
use: the effect to which the lifecycle is scoped, whose result
is the return value of this function

See also

bracketCase for a more powerful variant

Resource for a composable datatype encoding of effectful lifecycles

Inhertied from

MonadCancel

Implicitly added by genConcurrentForOptionT

pure lifts any value into the Applicative Functor.

Example:
{{{
scala> import cats.implicits._

scala> Applicative[Option] .pure(10)
res0: Option[Int] = Some(10)
}}}

Inhertied from: Applicative

Implicitly added by genConcurrentForEitherT

Pair the result of function application with A.

Example:
{{{
scala> import cats.Functor
scala> import cats.implicits.catsStdInstancesForOption

scala> Functor[Option] .fproductLeft(Option(42))(_.toString)
res0: Option[(String, Int)] = Some((42,42))
}}}

Inhertied from: Functor

Implicitly added by genConcurrentForEitherT

Pair A with the result of function application.

Example:
{{{
scala> import cats.implicits._
scala> List("12", "34", "56").mproduct(_.toList)
res0: List[(String, Char)] = List((12,1), (12,2), (34,3), (34,4), (56,5), (56,6))
}}}

Inhertied from: FlatMap

@noop

Implicitly added by genConcurrentForEitherT

Execute an action repeatedly as long as the given Boolean expression
returns true. The condition is evaluated before the loop body.
Discards results.

Inhertied from: Monad

Implicitly added by genConcurrentForEitherT

Races the evaluation of two fibers that returns the Outcome of the
winner. The winner of the race is considered to be the first fiber that
completes with an outcome. The loser of the race is canceled before
returning.

Value Params

fa: the effect for the first racing fiber
fb: the effect for the second racing fiber

See also

race for a simpler variant that returns the successful outcome.

Inhertied from

GenSpawn

@inline

Implicitly added by genConcurrentForEitherT

Alias for productR.

Inhertied from: Apply

@noop

Implicitly added by genConcurrentForEitherT

Un-zips an F[(A, B)] consisting of element pairs or Tuple2 into two separate F's tupled.

NOTE: Check for effect duplication, possibly memoize before

{{{
scala> import cats.Functor
scala> import cats.implicits.catsStdInstancesForList

scala> Functor[List] .unzip(List((1,2), (3, 4)))
res0: (List[Int] , List[Int] ) = (List(1, 3),List(2, 4))
}}}

Inhertied from: Functor

Implicitly added by genConcurrentForEitherT

Handle any error, by mapping it to an A value.

See also: handleErrorWith to map to an F[A] value instead of simply an
A value.

recover to only recover from certain errors.
Inhertied from: ApplicativeError

Implicitly added by genConcurrentForEitherT

Replaces the A value in F[A] with the supplied value.

Example:

{{{
scala> import cats.Functor
scala> import cats.implicits.catsStdInstancesForList

scala> Functor[List] .as(List(1,2,3), "hello")
res0: List[String] = List(hello, hello, hello)
}}}

Inhertied from: Functor

Implicitly added by genConcurrentForEitherT

Similar to attempt, but it only handles errors of type EE.

Inhertied from: ApplicativeError

Implicitly added by genConcurrentForEitherT

Convert from scala.Option

Example:
{{{
scala> import cats.implicits._
scala> import cats.ApplicativeError
scala> val F = ApplicativeError[Either[String, *] , String]

scala> F.fromOption(Some(1), "Empty")
res0: scala.Either[String, Int] = Right(1)

scala> F.fromOption(Option.empty[Int] , "Empty")
res1: scala.Either[String, Int] = Left(Empty)
}}}

Inhertied from: ApplicativeError

Implicitly added by genConcurrentForEitherT

Convert from scala.Either

Example:
{{{
scala> import cats.ApplicativeError
scala> import cats.instances.option._

scala> ApplicativeError[Option, Unit] .fromEither(Right(1))
res0: scala.Option[Int] = Some(1)

scala> ApplicativeError[Option, Unit] .fromEither(Left(()))
res1: scala.Option[Nothing] = None
}}}

Inhertied from: ApplicativeError

Implicitly added by genConcurrentForEitherT

Specifies an effect that is always invoked after evaluation of fa
completes, regardless of the outcome.

This function can be thought of as a combination of
flatTap, onError, and
onCancel.

Value Params

fa: The effect that is run after fin is registered.
fin: The effect to run in the event of a cancellation or error.

See also

guaranteeCase for a more powerful variant

Outcome for the various outcomes of evaluation

Inhertied from

MonadCancel

Implicitly added by genConcurrentForEitherT

Inhertied from: FlatMap

Implicitly added by genConcurrentForEitherT

A pattern for safely interacting with effectful lifecycles.

If acquire completes successfully, use is called. If use succeeds,
fails, or is canceled, release is guaranteed to be called exactly once.

acquire is uncancelable.
release is uncancelable.
use is cancelable by default, but can be masked.

Value Params

acquire: the lifecycle acquisition action
release: the lifecycle release action which depends on the outcome of use
use: the effect to which the lifecycle is scoped, whose result
is the return value of this function

See also

bracketFull for a more powerful variant

Resource for a composable datatype encoding of effectful lifecycles

Inhertied from

MonadCancel

@noop

Implicitly added by genConcurrentForEitherT

Execute an action repeatedly as long as the given Boolean expression
returns true. The condition is evaluated before the loop body.
Collects the results into an arbitrary Alternative value, such as a Vector.
This implementation uses append on each evaluation result,
so avoid data structures with non-constant append performance, e.g. List.

Inhertied from: Monad

@noop

Implicitly added by genConcurrentForEitherT

This repeats an F until we get defined values. This can be useful
for polling type operations on State (or RNG) Monads, or in effect
monads.

Inhertied from: FlatMap

Implicitly added by genConcurrentForEitherT

Tuple the values in fa with the result of applying a function
with the value

Example:
{{{
scala> import cats.Functor
scala> import cats.implicits.catsStdInstancesForOption

scala> Functor[Option] .fproduct(Option(42))(_.toString)
res0: Option[(Int, String)] = Some((42,42))
}}}

Inhertied from: Functor

@noop

Implicitly added by genConcurrentForEitherT

Simulates an if/else-if/else in the context of an F. It evaluates conditions until
one evaluates to true, and returns the associated F[A] . If no condition is true,
returns els.

{{{
scala> import cats._
scala> Monad[Eval] .ifElseM(Eval.later(false) -> Eval.later(1), Eval.later(true) -> Eval.later(2))(Eval.later(5)).value
res0: Int = 2
}}}

Based on a gist by Daniel Spiewak with a stack-safe
implementation due to P. Oscar Boykin

See also: See https://gitter.im/typelevel/cats-effect?at=5f297e4314c413356f56d230 for the discussion.
Inhertied from: Monad

Implicitly added by genConcurrentForEitherT

Registers a finalizer that is invoked if cancellation is observed
during the evaluation of fa. If the evaluation of fa completes
without encountering a cancellation, the finalizer is unregistered
before proceeding.

During finalization, all actively registered finalizers are run exactly
once. The order by which finalizers are run is dictated by nesting:
innermost finalizers are run before outermost finalizers. For example,
in the following program, the finalizer f1 is run before the finalizer
f2:

{{{

F.onCancel(F.onCancel(F.canceled, f1), f2)

}}}

If a finalizer throws an error during evaluation, the error is suppressed,
and implementations may choose to report it via a side channel. Finalizers
are always uncancelable, so cannot otherwise be interrupted.

Value Params

fa: The effect that is evaluated after fin is registered.
fin: The finalizer to register before evaluating fa.

Inhertied from

MonadCancel

Implicitly added by genConcurrentForEitherT

point lifts any value into a Monoidal Functor.

Example:
{{{
scala> import cats.implicits._

scala> InvariantMonoidal[Option] .point(10)
res0: Option[Int] = Some(10)
}}}

Inhertied from: InvariantMonoidal

Implicitly added by genConcurrentForEitherT

Similar to map2 but uses Eval to allow for laziness in the F[B]
argument. This can allow for "short-circuiting" of computations.

NOTE: the default implementation of map2Eval does not short-circuit
computations. For data structures that can benefit from laziness, Apply
instances should override this method.

In the following example, x.map2(bomb)(_ + _) would result in an error,
but map2Eval "short-circuits" the computation. x is None and thus the
result of bomb doesn't even need to be evaluated in order to determine
that the result of map2Eval should be None.

{{{
scala> import cats.{Eval, Later}
scala> import cats.implicits._
scala> val bomb: Eval[Option[Int] ] = Later(sys.error("boom"))
scala> val x: Option[Int] = None
scala> x.map2Eval(bomb)(_ + _).value
res0: Option[Int] = None
}}}

Inhertied from: Apply

Implicitly added by genConcurrentForEitherT

Convert from cats.data.Validated

Example:
{{{
scala> import cats.implicits._
scala> import cats.ApplicativeError

scala> ApplicativeError[Option, Unit] .fromValidated(1.valid[Unit] )
res0: scala.Option[Int] = Some(1)

scala> ApplicativeError[Option, Unit] .fromValidated(().invalid[Int] )
res1: scala.Option[Int] = None
}}}

Inhertied from: ApplicativeError

Implicitly added by genConcurrentForEitherT

Execute an action repeatedly until its result fails to satisfy the given predicate
and return that result, discarding all others.

Inhertied from: Monad

Implicitly added by genConcurrentForEitherT

Lift an error into the F context.

Example:
{{{
scala> import cats.implicits._

// integer-rounded division
scala> def divide[F[_] ](dividend: Int, divisor: Int)(implicit F: ApplicativeError[F, String] ): F[Int] =
| if (divisor === 0) F.raiseError("division by zero")
| else F.pure(dividend / divisor)

scala> type ErrorOr[A] = Either[String, A]

scala> divide[ErrorOr] (6, 3)
res0: ErrorOr[Int] = Right(2)

scala> divide[ErrorOr] (6, 0)
res1: ErrorOr[Int] = Left(division by zero)
}}}

Inhertied from: ApplicativeError

Implicitly added by genConcurrentForEitherT

If the error type is Throwable, we can convert from a scala.util.Try

Inhertied from: ApplicativeError

Implicitly added by genConcurrentForEitherT

Compose Invariant F[_] and Functor G[_] then produce Invariant[F[G[_]]]
using F's imap and G's map.

Example:
{{{
scala> import cats.implicits._
scala> import scala.concurrent.duration._

scala> val durSemigroupList: Semigroup[List[FiniteDuration] ] =
| Invariant[Semigroup]
| .composeFunctor[List]
| .imap(Semigroup[List[Long] ])(Duration.fromNanos)(_.toNanos)
scala> durSemigroupList.combine(List(2.seconds, 3.seconds), List(4.seconds))
res1: List[FiniteDuration] = List(2 seconds, 3 seconds, 4 seconds)
}}}

Inhertied from: Invariant

Implicitly added by genConcurrentForEitherT

Inhertied from: InvariantSemigroupal

Implicitly added by genConcurrentForEitherT

Recover from certain errors by mapping them to an F[A] value.

See also: handleErrorWith to handle any/all errors.

recover to recover from certain errors by mapping them to A
values.
Inhertied from: ApplicativeError

Implicitly added by genConcurrentForEitherT

"flatten" a nested F of F structure into a single-layer F structure.

This is also commonly called join.

Example:
{{{
scala> import cats.Eval
scala> import cats.implicits._

scala> val nested: Eval[Eval[Int] ] = Eval.now(Eval.now(3))
scala> val flattened: Eval[Int] = nested.flatten
scala> flattened.value
res0: Int = 3
}}}

Inhertied from: FlatMap

Implicitly added by genConcurrentForEitherT

Execute an action repeatedly until the Boolean condition returns true.
The condition is evaluated after the loop body. Collects results into an
arbitrary Alternative value, such as a Vector.
This implementation uses append on each evaluation result,
so avoid data structures with non-constant append performance, e.g. List.

Inhertied from: Monad

Implicitly added by genConcurrentForEitherT

Returns an F[Unit] value, equivalent with pure(()).

A useful shorthand, also allowing implementations to optimize the
returned reference (e.g. it can be a val).

Example:
{{{
scala> import cats.implicits._

scala> Applicative[Option] .unit
res0: Option[Unit] = Some(())
}}}

Inhertied from: Applicative

Implicitly added by genConcurrentForEitherT

Execute an action repeatedly until the Boolean condition returns true.
The condition is evaluated after the loop body. Discards results.

Inhertied from: Monad

Implicitly added by genConcurrentForEitherT

Returns a Resource that manages the concurrent execution of a fiber.
The inner effect can be used to wait on the outcome of the child fiber;
it is effectively a join.

The child fiber is canceled in two cases: either the resource goes out
of scope or the parent fiber is cancelled. If the child fiber terminates
before one of these cases occurs, then cancellation is a no-op. This
avoids fiber leaks because the child fiber is always canceled before
the parent fiber drops the reference to it.

{{{

// Starts a fiber that continously prints "A".
// After 10 seconds, the resource scope exits so the fiber is canceled.
F.background(F.delay(println("A")).foreverM).use { _ =>
F.sleep(10.seconds)
}

}}}

Value Params

fa: the effect for the spawned fiber

Inhertied from

GenSpawn

Implicitly added by genConcurrentForEitherT

Tuples the A value in F[A] with the supplied B value, with the B value on the left.

Example:
{{{
scala> import scala.collection.immutable.Queue
scala> import cats.Functor
scala> import cats.implicits.catsStdInstancesForQueue

scala> Functor[Queue] .tupleLeft(Queue("hello", "world"), 42)
res0: scala.collection.immutable.Queue[(Int, String)] = Queue((42,hello), (42,world))
}}}

Inhertied from: Functor

Implicitly added by genConcurrentForEitherT

Handle any error, potentially recovering from it, by mapping it to an
F[A] value.

See also: handleError to handle any error by simply mapping it to an A
value instead of an F[A].

recoverWith to recover from only certain errors.
Inhertied from: ApplicativeError

Implicitly added by genConcurrentForEitherT

Apply a monadic function and discard the result while keeping the effect.

{{{
scala> import cats., implicits.
scala> Option(1).flatTap(_ => None)
res0: Option[Int] = None
scala> Option(1).flatTap(_ => Some("123"))
res1: Option[Int] = Some(1)
scala> def nCats(n: Int) = List.fill(n)("cat")
nCats: (n: Int)List[String]
scala> ListInt.flatTap(nCats)
res2: List[Int] = List()
scala> ListInt.flatTap(nCats)
res3: List[Int] = List(4, 4, 4, 4)
}}}

Inhertied from: FlatMap

Implicitly added by genConcurrentForEitherT

Masks cancellation on the current fiber. The argument to body of type
Poll[F] is a natural transformation F ~> F that enables polling.
Polling causes a fiber to unmask within a masked region so that
cancellation can be observed again.

In the following example, cancellation can be observed only within fb
and nowhere else:

{{{

F.uncancelable { poll =>
fa *> poll(fb) *> fc
}

}}}

If a fiber is canceled while it is masked, the cancellation is suppressed
for as long as the fiber remains masked. Whenever the fiber is completely
unmasked again, the cancellation will be respected.

Masks can also be stacked or nested within each other. If multiple masks
are active, all masks must be undone so that cancellation can be observed.
In order to completely unmask within a multi-masked region, the poll
corresponding to each mask must be applied, innermost-first.

{{{

F.uncancelable { p1 =>
F.uncancelable { p2 =>
fa *> p2(p1(fb)) *> fc
}
}

}}}

The following operations are no-ops:

Polling in the wrong order
Applying the same poll more than once: poll(poll(fa))
Applying a poll bound to one fiber within another fiber

Inhertied from: MonadCancel

Implicitly added by genConcurrentForEitherT

Inhertied from: GenSpawn

Implicitly added by genConcurrentForEitherT

Turns a successful value into an error if it does not satisfy a given predicate.

Inhertied from: MonadError

Implicitly added by genConcurrentForEitherT

Sequentially compose two actions, discarding any value produced by the second. This variant of
productL also lets you define the evaluation strategy of the second action. For instance
you can evaluate it only ''after'' the first action has finished:

{{{
scala> import cats.Eval
scala> import cats.implicits._
scala> var count = 0
scala> val fa: Option[Int] = Some(3)
scala> def fb: Option[Unit] = Some(count += 1)
scala> fa.productLEval(Eval.later(fb))
res0: Option[Int] = Some(3)
scala> assert(count == 1)
scala> none[Int] .productLEval(Eval.later(fb))
res1: Option[Int] = None
scala> assert(count == 1)
}}}

Inhertied from: FlatMap

Implicitly added by genConcurrentForEitherT

Sequentially compose two actions, discarding any value produced by the first. This variant of
productR also lets you define the evaluation strategy of the second action. For instance
you can evaluate it only ''after'' the first action has finished:

{{{
scala> import cats.Eval
scala> import cats.implicits._
scala> val fa: Option[Int] = Some(3)
scala> def fb: Option[String] = Some("foo")
scala> fa.productREval(Eval.later(fb))
res0: Option[String] = Some(foo)
}}}

Inhertied from: FlatMap

Implicitly added by genConcurrentForEitherT

Execute a callback on certain errors, then rethrow them.
Any non matching error is rethrown as well.

In the following example, only one of the errors is logged,
but they are both rethrown, to be possibly handled by another
layer of the program:

{{{
scala> import cats., data., implicits._

scala> case class Err(msg: String)

scala> type F[A] = EitherT[State[String, *] , Err, A]

scala> val action: PartialFunction[Err, F[Unit] ] = {
| case Err("one") => EitherT.liftF(State.set("one"))
| }

scala> val prog1: F[Int] = (Err("one")).raiseError[F, Int]
scala> val prog2: F[Int] = (Err("two")).raiseError[F, Int]

scala> prog1.onError(action).value.run("").value

res0: (String, Either[Err,Int] ) = (one,Left(Err(one)))

scala> prog2.onError(action).value.run("").value
res1: (String, Either[Err,Int] ) = ("",Left(Err(two)))
}}}

Inhertied from: ApplicativeError

Implicitly added by genConcurrentForEitherT

Evaluates the specified block, catching exceptions of the specified type. Uncaught exceptions are propagated.

Inhertied from: ApplicativeError

Implicitly added by genConcurrentForEitherT

Returns a new value that transforms the result of the source,
given the recover or map functions, which get executed depending
on whether the result is successful or if it ends in error.

This is an optimization on usage of attempt and map,
this equivalence being available:

{{{
fa.redeem(fe, fs) <-> fa.attempt.map(_.fold(fe, fs))
}}}

Usage of redeem subsumes handleError because:

{{{
fa.redeem(fe, id) <-> fa.handleError(fe)
}}}

Implementations are free to override it in order to optimize
error recovery.

Value Params

fa: is the source whose result is going to get transformed
recover: is the function that gets called to recover the source
in case of error

See also

MonadError.redeemWith, attempt and handleError

Inhertied from

ApplicativeError

Implicitly added by genConcurrentForEitherT

Lift a function f to operate on Functors

Example:
{{{
scala> import cats.Functor
scala> import cats.implicits.catsStdInstancesForOption

scala> val o = Option(42)
scala> Functor[Option] .lift((x: Int) => x + 10)(o)
res0: Option[Int] = Some(52)
}}}

Inhertied from: Functor

Implicitly added by genConcurrentForEitherT

Turns a successful value into an error specified by the error function if it does not satisfy a given predicate.

Inhertied from: MonadError

Implicitly added by genConcurrentForEitherT

Apply a monadic function iteratively until its result satisfies
the given predicate and return that result.

Inhertied from: Monad

Implicitly added by genConcurrentForEitherT

Returns a new value that transforms the result of the source,
given the recover or bind functions, which get executed depending
on whether the result is successful or if it ends in error.

This is an optimization on usage of attempt and flatMap,
this equivalence being available:

{{{
fa.redeemWith(fe, fs) <-> fa.attempt.flatMap(_.fold(fe, fs))
}}}

Usage of redeemWith subsumes handleErrorWith because:

{{{
fa.redeemWith(fe, F.pure) <-> fa.handleErrorWith(fe)
}}}

Usage of redeemWith also subsumes flatMap because:

{{{
fa.redeemWith(F.raiseError, fs) <-> fa.flatMap(fs)
}}}

Implementations are free to override it in order to optimize
error recovery.

Value Params

bind: is the function that gets to transform the source
in case of success
fa: is the source whose result is going to get transformed
recover: is the function that gets called to recover the source
in case of error

See also

redeem, attempt and handleErrorWith

Inhertied from

MonadError

Implicitly added by genConcurrentForEitherT

Given fa and n, apply fa n times to construct an F[List[A]] value.

Example:
{{{
scala> import cats.data.State

scala> type Counter[A] = State[Int, A]
scala> val getAndIncrement: Counter[Int] = State { i => (i + 1, i) }
scala> val getAndIncrement5: Counter[List[Int] ] =
| Applicative[Counter] .replicateA(5, getAndIncrement)
scala> getAndIncrement5.run(0).value
res0: (Int, List[Int] ) = (5,List(0, 1, 2, 3, 4))
}}}

Inhertied from: Applicative

Implicitly added by genConcurrentForEitherT

A low-level primitive for starting the concurrent evaluation of a fiber.
Returns a Fiber that can be used to wait for a fiber or cancel it.

start is a cancellation-unsafe function; it is recommended to
use the safer variant, background, to spawn fibers.

Value Params

fa: the effect for the fiber

See also

background for the safer, recommended variant

Inhertied from

GenSpawn

Implicitly added by genConcurrentForEitherT

Apply a monadic function iteratively until its result fails
to satisfy the given predicate and return that result.

Inhertied from: Monad