Builds a Ref value for data types that are Sync

This builder uses the Partially-Applied Type technique.

Ref[IO].of(10) <-> Ref.of[IO, Int](10)

Creates a Ref starting with the value of the one in source.

Updates of either of the Refs will not have an effect on the other (assuming A is immutable).

Creates an instance focused on a component of another Ref's value. Delegates every get and modification to underlying Ref, so both instances are always in sync.

Example:

case class Foo(bar: String, baz: Int)

val refA: Ref[IO, Foo] = ???
val refB: Ref[IO, String] =
  Ref.lens[IO, Foo, String](refA)(_.bar, (foo: Foo) => (bar: String) => foo.copy(bar = bar))

Creates a thread-safe, concurrent mutable reference initialized to the supplied value.

import cats.effect.IO
import cats.effect.kernel.Ref

for {
  intRef <- Ref.of[IO, Int](10)
  ten <- intRef.get
} yield ten

Like apply but returns the newly allocated Ref directly instead of wrapping it in F.delay. This method is considered unsafe because it is not referentially transparent -- it allocates mutable state.

This method uses the Partially Applied Type Params technique, so only effect type needs to be specified explicitly.

Some care must be taken to preserve referential transparency:

import cats.effect.IO
import cats.effect.kernel.Ref

class Counter private () {
  private val count = Ref.unsafe[IO, Int](0)

  def increment: IO[Unit] = count.update(_ + 1)
  def total: IO[Int] = count.get
}

object Counter {
  def apply(): IO[Counter] = IO(new Counter)
}

Such usage is safe, as long as the class constructor is not accessible and the public one suspends creation in IO.

The recommended alternative is accepting a Ref[F, A] as a parameter:

class Counter (count: Ref[IO, Int]) {
  // same body
}

object Counter {
  def apply(): IO[Counter] = Ref[IO](0).map(new Counter(_))
}