BIOCatsSpawnImpl

Alias for productR.

Alias for productL.

Alias for ap.

Transform certain errors using pf and rethrow them. Non matching errors and successful values are not affected by this function.

Example:

scala> import cats._, implicits._

scala> def pf: PartialFunction[String, String] = { case "error" => "ERROR" }

scala> ApplicativeError[Either[String, *], String].adaptError("error".asLeft[Int])(pf)
res0: Either[String,Int] = Left(ERROR)

scala> ApplicativeError[Either[String, *], String].adaptError("err".asLeft[Int])(pf)
res1: Either[String,Int] = Left(err)

scala> ApplicativeError[Either[String, *], String].adaptError(1.asRight[String])(pf)
res2: Either[String,Int] = Right(1)

The same function is available in ApplicativeErrorOps as adaptErr - it cannot have the same name because this would result in ambiguous implicits due to adaptError having originally been included in the MonadError API and syntax.

Given a value and a function in the Apply context, applies the function to the value.

Example:

scala> import cats.implicits._

scala> val someF: Option[Int => Long] = Some(_.toLong + 1L)
scala> val noneF: Option[Int => Long] = None
scala> val someInt: Option[Int] = Some(3)
scala> val noneInt: Option[Int] = None

scala> Apply[Option].ap(someF)(someInt)
res0: Option[Long] = Some(4)

scala> Apply[Option].ap(noneF)(someInt)
res1: Option[Long] = None

scala> Apply[Option].ap(someF)(noneInt)
res2: Option[Long] = None

scala> Apply[Option].ap(noneF)(noneInt)
res3: Option[Long] = None

ap2 is a binary version of ap, defined in terms of ap.

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)

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.

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

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

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)

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 canceled. If the child fiber terminates before one of these cases occurs, then cancelation 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)
 }

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

The following rules describe the semantics of both:

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

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.

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.

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.

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.

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

canceled has a return type of F[Unit] instead of F[Nothing] due to execution continuing in a masked region. In the following example, the fiber requests self-cancelation in a masked region, so cancelation is suppressed until the fiber is completely unmasked. fa will run but fb will not. If canceled had a return type of F[Nothing], then it would not be possible to continue execution to fa (there would be no Nothing value to pass to the flatMap).

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

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

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

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

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.

This function is primarily useful when performing long-running computation that is outside of the monadic context. For example:

 fa.map(data => expensiveWork(data))

In the above, we're assuming that expensiveWork is a function which is entirely compute-bound but very long-running. A good rule of thumb is to consider a function "expensive" when its runtime is around three or more orders of magnitude higher than the overhead of the map function itself (which runs in around 5 nanoseconds on modern hardware). Thus, any expensiveWork function which requires around 10 microseconds or longer to execute should be considered "long-running".

The danger is that these types of long-running actions outside of the monadic context can result in degraded fairness properties. The solution is to add an explicit cede both before and after the expensive operation:

 (fa <* F.cede).map(data => expensiveWork(data)).guarantee(F.cede)

Note that extremely long-running expensiveWork functions can still cause fairness issues, even when used with cede. This problem is somewhat fundamental to the nature of scheduling such computation on carrier threads. Whenever possible, it is best to break apart any such functions into multiple pieces invoked independently (e.g. via chained map calls) whenever the execution time exceeds five or six orders of magnitude beyond the overhead of map itself (around 1 millisecond on most hardware).

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.

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)

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)

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)

Compose Invariant F[_] and Contravariant G[_] then produce Invariant[F[G[_]]] using F's imap and G's contramap.

Example:

scala> import cats.implicits._
scala> import scala.concurrent.duration._

scala> type ToInt[T] = T => Int
scala> val durSemigroupToInt: Semigroup[ToInt[FiniteDuration]] =
    | Invariant[Semigroup]
    |   .composeContravariant[ToInt]
    |   .imap(Semigroup[ToInt[Long]])(Duration.fromNanos)(_.toNanos)
// semantically equal to (2.seconds.toSeconds.toInt + 1) + (2.seconds.toSeconds.toInt * 2) = 7
scala> durSemigroupToInt.combine(_.toSeconds.toInt + 1, _.toSeconds.toInt * 2)(2.seconds)
res1: Int = 7

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.by[String, Int](_.length)

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)

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)

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

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

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> List[Int](0).flatTap(nCats)
res2: List[Int] = List()
scala> List[Int](4).flatTap(nCats)
res3: List[Int] = List(4, 4, 4, 4)

"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

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!)

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

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.