evolution-gaming / cats-helper Goto Github PK

View Code? Open in Web Editor NEW

43.0 11.0 18.0 484 KB

Helpers for cats & cats-effect

License: MIT License

Scala 100.00%

scala cats cats-effect tagless-final

cats-helper's Introduction

Cats Helper

ClockHelper

import com.evolutiongaming.catshelper.ClockHelper._

val clock = Clock.const[Id](nanos = 1000, millis = 2)

clock.millis // 2
clock.nanos // 1000
clock.micros // 1
clock.instant // Instant.ofEpochMilli(2)

MeasureDuration

Provides a way to measure duration of a computation in a pure way.

Example:

import com.evolutiongaming.catshelper.MeasureDuration

for {
  duration <- MeasureDuration[IO].start
  _        <- doSomething
  duration <- duration
} yield duration

Syntax extensions are also available, allowing to measure duration of a computation and execute an effect with it:

import com.evolutiongaming.catshelper.syntax.measureDuration._

for {
  int1 <- IO.pure(1).measured(elapsed => IO.println(s"elapsed: $elapsed"))
  int2 <- IO.pure(1).measuredCase(
    successF = elapsed => IO.println(s"Succeeded: $elapsed"),
    failureF = elapsed => IO.println(s"Failed: $elapsed")
  )
} yield int1 + int2

SerialRef

Like Ref but allows A => F[A] rather than A => A
Ensures that updates are run serially

import com.evolutiongaming.catshelper.SerialRef

for {
  ref <- SerialRef.of[IO, Int](0)
  _   <- ref.update(a => (a + 1).pure[IO])
} yield {}

LazyVal

Functional alternative to lazy keyword in Scala

trait LazyVal[F[_], A] {

  def get: F[A]

  def getLoaded: F[Option[A]]
}

ToFuture & FromFuture

trait ToFuture[F[_]] {
  def apply[A](fa: F[A]): Future[A]
}

trait FromFuture[F[_]] {
  def apply[A](future: => Future[A]): F[A]
}

ToTry & FromTry

trait ToTry[F[_]] {

  def apply[A](fa: F[A]): Try[A]
}

trait FromTry[F[_]] {

  def apply[A](fa: Try[A]): F[A]
}

Log

trait Log[F[_]] {

  def debug(msg: => String): F[Unit]

  def info(msg: => String): F[Unit]

  def warn(msg: => String): F[Unit]

  def warn(msg: => String, cause: Throwable): F[Unit]

  def error(msg: => String): F[Unit]

  def error(msg: => String, cause: Throwable): F[Unit]
}

Runtime

trait Runtime[F[_]] {

  def availableCores: F[Int]

  def freeMemory: F[Long]

  def totalMemory: F[Long]

  def maxMemory: F[Long]

  def gc: F[Unit]
}

ThreadLocalRef

trait ThreadLocalRef[F[_], A] {

  def get: F[A]

  def set(a: A): F[Unit]

  def update(f: A => A): F[Unit]

  def modify[B](f: A => (A, B)): F[B]
}

ResourceFenced

This is useful to ensure release called at most once, in cases when "unsafe" api like Resource.allocated being used

val resource: Resource[F, A] = ???
resource.fenced

ReadWriteRef

A mutable reference to A value with read-write lock semantics.

FeatureToggled

Manages a given Resource[F, A] providing access to it only when a feature-toggle is on.

val serviceResource: Resource[F, AService] = ???
val flag: F[Boolean] = ???

val ftService: Resource[F, Resource[F, Option[AService]]] = FeatureToggled
  .polling(
    serviceResource,
    flag,
    pollInterval = 10.seconds,
    gracePeriod = 30.seconds,
  )

ftService.use { access =>
  access.use {
    case Some(service) => service.doStuff(…)
    case None          => F.unit
  }
}

PureTest

This helper lives in a separate cats-helper-testkit module. It is makes testing F[_]-based code easier.

NOTE: cats-helper-testkit is an experimental module and may break SemVer guarantees from time to time. However we will do our best to avoid unnecessary breakages.

"what time is it now?" in PureTest[IO].of { env =>
  import env._
  for {
    _ <- IO.sleep(1.hour)
    _ <- testRuntime.getTimeSinceStart.map(_ shouldBe 1.hour)
  } yield ()
}

Setup

addSbtPlugin("com.evolution" % "sbt-artifactory-plugin" % "0.0.2")

libraryDependencies += "com.evolutiongaming" %% "cats-helper" % "2.2.3"

cats-helper's People

Contributors

Stargazers

Watchers

Forkers

scala-steward eternalerrors saraiva132 gregoryevlash z1kkurat sergluka funfunfine brainhorse devilab yaroslav73 sirmax kpodsiad akilegaspi gjojgov-evolution khanhkhuc longaleonteq

cats-helper's Issues

Accumulative timeout in ToTry

Some cases like skafka #125 required applying ToTry multiple times while accumulating total execution time and firing IO.timeout on its exhaustion.

That can be achieved by implementing factory ToTryOf with API like:

import cats.effect.IO
import cats.effect.unsafe.IORuntime

sealed trait ToTryOf[F[_]] {
  def disposable(timeout: FiniteDuration): F[ToTry[F]]
}

object ToTryOf {
  def ioToTryOf(implicit runtime: IORuntime): ToTryOf[IO] = ???
}

Cancelling ReadWriteRef.read can result in a locked-up state

Initially we observed this issue with FeatureToggled. It went like so:

we have a feature-toggled resource, toggled on and under some use
we toggle it off
later we toggle it on, but it does not go back.
Heap dumps showed that an internal rwLock: ReadWriteRef had a positive number of active tasks despite them being complete long time ago.

We've narrowed down the problem to the incorrect cancellation handling in ReadWriteRef, specifically this bit

val read: Resource[F, A] = {
  Resource.suspend {
    Concurrent.cancelableF[F, Resource[F, A]] { cb =>
      …
      stateRef
        .modify { // acquisition
            …
            val effect = … // emit a Resource that modifies stateRef on release
            val cancel = F.unit
            s1 -> (effect as cancel)
        }
        .flatten
    }
  }

In a nutshell, we have two stateRef updates here: one for "acquisition" and one for "release", but the problem is that they happen on different "layers", and its quite possible that only "acquisition" happens but not "release" when the read.use(…) gets cancelled.

Imports unification and other syntax changes

There is a little inconsistency regarding imports in the library: while any other library (e.g. cats, cats-effect & tofu) import their syntax by import lib.syntax.something._ and import lib.syntax.all._, cats-helper does it in its own unique way by import com.evolutiongaming.SomethingHelper._.

It kind of slows down the adoption by newcomers, because they can easily miss that those syntax objects even exist, so I would like to propose to change this import scheme to be the same as in cats. WDYT?

Another thing I would like to discuss here (I don't think it is worth creating a separate issue for that) is the pollution by apply methods. One can easily find such code in cats-helper (e.g. Blocking, FromFuture):

trait Something[F[_]] {
  def apply(something: Thing): F[OtherThing]
}

object Something {
  def apply[F[_]: Something]: Something[F] = implicitly
}

Not only that it just doesn't work to call it like Something[F](thing) because of double apply and thing being treated as an explicitly passed instance, but IntelliJ IDEA often fails to find usages or asks if I want to go to the instance or to the method. In other words, it is inconvenient. So my proposal is to add alternative methods names with the possible deprecation of apply methods.

I could get this done, but I would like to see some discussion here. Are those proposals any good?