Ref

Returns a Ref.View that allows access to the contents of this Ref without requiring that a InTxn be available. Each operation on the view will act as if it is performed in its own "single-operation" atomic block, nesting into an existing transaction if one is active.

A mental model of this method is that ref.single.foo(args) acts like atomic { implicit t => ref.foo(args) }.

Transforms the value stored in the Ref by multiplying it.

'''Note: Implementations may choose to ignore the provided Numeric[A] instance if A is a primitive type.'''

Transforms the value stored in the Ref by incrementing it.

'''Note: Implementations may choose to ignore the provided Numeric[A] instance if A is a primitive type.'''

Transforms the value stored in the Ref by decrementing it.

'''Note: Implementations may choose to ignore the provided Numeric[A] instance if A is a primitive type.'''

Transforms the value stored the Ref by performing a division on it, throwing away the remainder if division is not exact for instances of type A. The careful reader will note that division is actually provided by Fractional[A] or Integral[A], it is not defined on Numeric[A]. To avoid compile-time ambiguity this method accepts a Numeric[A] and assumes that it can be converted at runtime into either a Fractional[A] or an Integral[A].

'''Note: Implementations may choose to ignore the provided Numeric[A] instance if A is a primitive type.'''

Performs a transactional read and checks that it is consistent with all reads already made by txn. Equivalent to get.

Example:

  val x = Ref(0)
  atomic { implicit t =>
    ...
    val v = x() // perform a read inside a transaction
    ...
  }

Performs a transactional read and checks that it is consistent with all reads already made by txn. Equivalent to apply(), which is more concise in many situations.

Transforms the value referenced by this Ref by applying the function f, and returns the previous value.

Returns f(get), possibly reevaluating f to avoid rollback if a conflicting change is made but the old and new values are equal after application of f. Requires that f(x) == f(y) if x == y.

getWith(f) is equivalent to f(relaxedGet({ f(_) == f(_) })), although perhaps more efficient.

Returns the same value as get, but allows the caller to determine whether txn should be rolled back if another thread changes the value of this Ref before txn is committed. If ref.relaxedGet(equiv) returns v0 in txn, another context changes ref to v1, and equiv(v0, v1) == true, then txn won't be required to roll back (at least not due to this read). If additional changes are made to ref additional calls to the equivalence function will be made, always with v0 as the first parameter.

equiv will always be invoked on the current thread. Extreme care should be taken if the equivalence function accesses any Refs.

As an example, to perform a read that will not be validated during commit you can use the maximally permissive equivalence function:

  val unvalidatedValue = ref.relaxedGet({ (_, _) => true })

To check view serializability rather than conflict serializability for a read:

  val viewSerializableValue = ref.relaxedGet({ _ == _ })

The getWith method provides related functionality.

Performs a transactional write. The new value will not be visible by any other threads until (and unless) txn successfully commits. Equivalent to update(v).

Works like set(v), but returns the old value.

Transforms the value referenced by this Ref by applying the function f. Acts like ref.set(f(ref.get)), but the execution of f may be deferred or repeated by the STM to reduce transaction conflicts.

Transforms the value referenced by this Ref from ''v'' to f(''v'')._1, and returns f(''v'')._2.

Transforms the value referenced by this Ref by applying the function f, and returns the new value.

Transforms the value ''v'' referenced by this Ref by to pf.apply(''v''), but only if pf.isDefinedAt(''v''). Returns true if a transformation was performed, false otherwise. pf.apply and pf.isDefinedAt may be deferred or repeated by the STM to reduce transaction conflicts.

Performs a transactional write and returns true, or returns false. The STM implementation may choose to return false to reduce (not necessarily avoid) blocking. If no other threads are performing any transactional or atomic accesses then this method will succeed.

Performs a transactional write. The new value will not be visible by any other threads until (and unless) txn successfully commits. Equivalent to set(v).

Example:

  val x = Ref(0)
  atomic { implicit t =>
    ...
    x() = 10 // perform a write inside a transaction
    ...
  }