abstract class Ref[F[_], A] extends RefSource[F, A] with RefSink[F, A]
A thread-safe, concurrent mutable reference.
Provides safe concurrent access and modification of its content, but no functionality for
synchronisation, which is instead handled by Deferred. For this reason, a Ref is always
initialised to a value.
The default implementation is nonblocking and lightweight, consisting essentially of a purely
functional wrapper over an AtomicReference. Consequently it must not be used to store
mutable data as AtomicReference#compareAndSet and friends are dependent upon object
reference equality.
See also cats.effect.std.AtomicCell class from cats-effect-std for an alternative that
ensures exclusive access and effectual updates.
If your contents are an immutable Map[K, V], and all your operations are per-key, consider
using cats.effect.std.MapRef.
- Source
- Ref.scala
- Alphabetic
- By Inheritance
- Ref
- RefSink
- RefSource
- Serializable
- AnyRef
- Any
- Hide All
- Show All
- Public
- Protected
Instance Constructors
- new Ref()
Abstract Value Members
- abstract def access: F[(A, (A) => F[Boolean])]
Obtains a snapshot of the current value, and a setter for updating it.
Obtains a snapshot of the current value, and a setter for updating it.
The setter attempts to modify the contents from the snapshot to the new value (and return
true). If it cannot do this (because the contents changed since taking the snapshot), the setter is a noop and returnsfalse.Satisfies:
r.access.map(_._1) == r.getandr.access.flatMap { case (v, setter) => setter(f(v)) } == r.tryUpdate(f).map(_.isDefined). - abstract def get: F[A]
Obtains the current value.
Obtains the current value.
Since
Refis always guaranteed to have a value, the returned action completes immediately after being bound.- Definition Classes
- RefSource
- abstract def modify[B](f: (A) => (A, B)): F[B]
Like
tryModifybut retries until the update has been successfully made. - abstract def modifyState[B](state: State[A, B]): F[B]
Like tryModifyState but retries the modification until successful.
- abstract def set(a: A): F[Unit]
Sets the current value to
a.Sets the current value to
a.The returned action completes after the reference has been successfully set.
- Definition Classes
- RefSink
- abstract def tryModify[B](f: (A) => (A, B)): F[Option[B]]
Like
tryUpdatebut allows the update function to return an output value of typeB.Like
tryUpdatebut allows the update function to return an output value of typeB. The returned action completes withNoneif the value is not updated successfully andSome(b)otherwise. - abstract def tryModifyState[B](state: State[A, B]): F[Option[B]]
Update the value of this
Refwith a state computation.Update the value of this
Refwith a state computation.The current value of this
Refis used as the initial state and the computed output state is stored in thisRefafter computation completes. If a concurrent modification occurs,Noneis returned. - abstract def tryUpdate(f: (A) => A): F[Boolean]
Attempts to modify the current value once, returning
falseif another concurrent modification completes between the time the variable is read and the time it is set. - abstract def update(f: (A) => A): F[Unit]
Modifies the current value using the supplied update function.
Modifies the current value using the supplied update function. If another modification occurs between the time the current value is read and subsequently updated, the modification is retried using the new value. Hence,
fmay be invoked multiple times.Satisfies:
r.update(_ => a) == r.set(a)
Concrete Value Members
- final def !=(arg0: Any): Boolean
- Definition Classes
- AnyRef → Any
- final def ##: Int
- Definition Classes
- AnyRef → Any
- final def ==(arg0: Any): Boolean
- Definition Classes
- AnyRef → Any
- final def asInstanceOf[T0]: T0
- Definition Classes
- Any
- def clone(): AnyRef
- Attributes
- protected[lang]
- Definition Classes
- AnyRef
- Annotations
- @throws(classOf[java.lang.CloneNotSupportedException]) @native()
- final def eq(arg0: AnyRef): Boolean
- Definition Classes
- AnyRef
- def equals(arg0: AnyRef): Boolean
- Definition Classes
- AnyRef → Any
- def finalize(): Unit
- Attributes
- protected[lang]
- Definition Classes
- AnyRef
- Annotations
- @throws(classOf[java.lang.Throwable])
- def flatModify[B](f: (A) => (A, F[B]))(implicit F: MonadCancel[F, _]): F[B]
Like modify but schedules resulting effect right after modification.
Like modify but schedules resulting effect right after modification.
Useful for implementing effectful transition of a state machine, in which an effect is performed based on current state and the state must be updated to reflect that this effect will be performed.
Both modification and finalizer are within a single uncancelable region, to prevent canceled finalizers from leaving the Ref's value permanently out of sync with effects actually performed. if you need cancellation mechanic in finalizer please see flatModifyFull.
- See also
- def flatModifyFull[B](f: (Poll[F], A) => (A, F[B]))(implicit F: MonadCancel[F, _]): F[B]
Like modify but schedules resulting effect right after modification.
Like modify but schedules resulting effect right after modification.
Unlike flatModify finalizer cancellation could be unmasked via supplied
Poll. Modification itself is still uncancelable.When used as part of a state machine, cancelable regions should usually have an
onCancelfinalizer to update the state to reflect that the effect will not be performed.- See also
- def flatModifyState[B](state: State[A, F[B]])(implicit F: MonadCancel[F, _]): F[B]
Like modifyState but schedules resulting effect right after state computation & update.
Like modifyState but schedules resulting effect right after state computation & update.
Both modification and finalizer are uncancelable, if you need cancellation mechanic in finalizer please see flatModifyStateFull.
- See also
- def flatModifyStateFull[B](state: (Poll[F]) => State[A, F[B]])(implicit F: MonadCancel[F, _]): F[B]
Like modifyState but schedules resulting effect right after modification.
Like modifyState but schedules resulting effect right after modification.
Unlike flatModifyState finalizer cancellation could be masked via supplied
Poll[F]. Modification itself is still uncancelable.- See also
- def getAndSet(a: A): F[A]
Replaces the current value with
a, returning the previous value. - def getAndUpdate(f: (A) => A): F[A]
Updates the current value using
fand returns the previous value.Updates the current value using
fand returns the previous value.In case of retries caused by concurrent modifications, the returned value will be the last one before a successful update.
- final def getClass(): Class[_ <: AnyRef]
- Definition Classes
- AnyRef → Any
- Annotations
- @native()
- def hashCode(): Int
- Definition Classes
- AnyRef → Any
- Annotations
- @native()
- final def isInstanceOf[T0]: Boolean
- Definition Classes
- Any
- def mapK[G[_]](f: ~>[F, G])(implicit F: Functor[F]): Ref[G, A]
Modify the context
Fusing transformationf. - final def ne(arg0: AnyRef): Boolean
- Definition Classes
- AnyRef
- final def notify(): Unit
- Definition Classes
- AnyRef
- Annotations
- @native()
- final def notifyAll(): Unit
- Definition Classes
- AnyRef
- Annotations
- @native()
- final def synchronized[T0](arg0: => T0): T0
- Definition Classes
- AnyRef
- def toString(): String
- Definition Classes
- AnyRef → Any
- def updateAndGet(f: (A) => A): F[A]
Updates the current value using
f, and returns the updated value. - final def wait(): Unit
- Definition Classes
- AnyRef
- Annotations
- @throws(classOf[java.lang.InterruptedException])
- final def wait(arg0: Long, arg1: Int): Unit
- Definition Classes
- AnyRef
- Annotations
- @throws(classOf[java.lang.InterruptedException])
- final def wait(arg0: Long): Unit
- Definition Classes
- AnyRef
- Annotations
- @throws(classOf[java.lang.InterruptedException]) @native()