trait Ref[A] extends RefLike[A, InTxn] with Source[A] with Sink[A]

Provides access to a single element of type A. Accesses are performed as part of a memory transaction that comprises all of the operations of an atomic block and any nested blocks. Single-operation memory transactions may be performed without an explicit atomic block using the Ref.View returned from single. The software transactional memory performs concurrency control to make sure that all committed transactions are linearizable. Reads and writes performed by a successful transaction return the same values as if they were executed instantaneously at the transaction's commit (linearization) point.

The static scope of an atomic block is defined by access to an implicit InTxn passed to the block by the STM. Atomic blocks nest, so to participate in an atomic block for which a InTxn is not conveniently available, just create a new atomic block using

atomic { implicit t =>
  // the body
}

In the static scope of an atomic block reads and writes of a Ref are performed by x.get and x.set(v), or more concisely by x() and x() = v. x.single returns a Ref.View that will dynamically resolve the current scope during each method call, automatically creating a single-operation atomic block if no transaction is active.

It is possible for separate Ref instances to refer to the same element; in this case they will compare equal. (As an example, a transactional array class might store elements in an array and create Refs on demand.) Refs may be provided for computed values, such as the emptiness of a queue, to allow conditional retry and waiting on semantic properties.

To perform an access outside a transaction, use the view returned by single. Each access through the returned view will act as if it was performed in its own single-operation transaction, dynamically nesting into an active atomic block as appropriate.

Ref's companion object contains factory methods that create Ref instances paired with a single STM-managed memory location.

Linear Supertypes
Ordering
  1. Alphabetic
  2. By Inheritance
Inherited
  1. Ref
  2. Sink
  3. Source
  4. TxnDebuggable
  5. RefLike
  6. SinkLike
  7. SourceLike
  8. AnyRef
  9. Any
  1. Hide All
  2. Show All
Visibility
  1. Public
  2. All

Abstract Value Members

  1. abstract def get(implicit txn: InTxn): A

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

    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.

    txn

    an active transaction.

    returns

    the value of the Ref as observed by txn.

    Definition Classes
    SourceLike
    Exceptions thrown

    IllegalStateException if txn is not active.

  2. abstract def getWith[Z](f: (A) ⇒ Z)(implicit txn: InTxn): Z

    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.

    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.

    f

    an idempotent function.

    returns

    the result of applying f to the value contained in this Ref.

    Definition Classes
    SourceLike
  3. abstract def relaxedGet(equiv: (A, A) ⇒ Boolean)(implicit txn: InTxn): A

    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.

    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.

    equiv

    an equivalence function that returns true if a transaction that observed the first argument will still complete correctly, where the second argument is the actual value that should have been observed.

    returns

    a value of the Ref, not necessary consistent with the rest of the reads performed by txn.

    Definition Classes
    SourceLike
  4. abstract def set(v: A)(implicit txn: InTxn): Unit

    Performs a transactional write.

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

    v

    a value to store in the Ref.

    Definition Classes
    SinkLike
    Exceptions thrown

    IllegalStateException if txn is not active.

  5. abstract def single: View[A]

    Returns a Ref.View that allows access to the contents of this Ref without requiring that a InTxn be available.

    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) }.

    Definition Classes
    RefSinkSource
  6. abstract def swap(v: A)(implicit txn: InTxn): A

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

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

    returns

    the previous value of this Ref, as observed by txn.

    Definition Classes
    RefLike
    Exceptions thrown

    IllegalStateException if txn is not active.

  7. abstract def transform(f: (A) ⇒ A)(implicit txn: InTxn): Unit

    Transforms the value referenced by this Ref by applying the function f.

    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.

    f

    a function that is safe to call multiple times, and safe to call later during the transaction.

    Definition Classes
    RefLike
    Exceptions thrown

    IllegalStateException if txn is not active.

  8. abstract def transformIfDefined(pf: PartialFunction[A, A])(implicit txn: InTxn): Boolean

    Transforms the value v referenced by this Ref by to pf.apply(v), but only if pf.isDefinedAt(v).

    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.

    pf

    a partial function that is safe to call multiple times, and safe to call later in the transaction.

    returns

    pf.isDefinedAt(v), where v was the value of this Ref before transformation (if any).

    Definition Classes
    RefLike
    Exceptions thrown

    IllegalStateException if txn is not active.

  9. abstract def trySet(v: A)(implicit txn: InTxn): Boolean

    Performs a transactional write and returns true, or returns false.

    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.

    Definition Classes
    SinkLike

Concrete Value Members

  1. final def !=(arg0: Any): Boolean
    Definition Classes
    AnyRef → Any
  2. final def ##(): Int
    Definition Classes
    AnyRef → Any
  3. def *=(rhs: A)(implicit txn: InTxn, num: Numeric[A]): Unit

    Transforms the value stored in the Ref by multiplying it.

    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.

    rhs

    the quantity by which to multiply the value of this Ref.

    Definition Classes
    RefLike
    Exceptions thrown

    IllegalStateException if txn is not active.

  4. def +=(rhs: A)(implicit txn: InTxn, num: Numeric[A]): Unit

    Transforms the value stored in the Ref by incrementing it.

    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.

    rhs

    the quantity by which to increment the value of this Ref.

    Definition Classes
    RefLike
    Exceptions thrown

    IllegalStateException if txn is not active.

  5. def -=(rhs: A)(implicit txn: InTxn, num: Numeric[A]): Unit

    Transforms the value stored in the Ref by decrementing it.

    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.

    rhs

    the quantity by which to decrement the value of this Ref.

    Definition Classes
    RefLike
    Exceptions thrown

    IllegalStateException if txn is not active.

  6. def /=(rhs: A)(implicit txn: InTxn, num: Numeric[A]): Unit

    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.

    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.

    rhs

    the quantity by which to divide the value of this Ref.

    Definition Classes
    RefLike
    Exceptions thrown

    IllegalStateException if txn is not active.

  7. final def ==(arg0: Any): Boolean
    Definition Classes
    AnyRef → Any
  8. def apply()(implicit txn: InTxn): A

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

    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
      ...
    }
    txn

    an active transaction.

    returns

    the value of the Ref as observed by txn.

    Definition Classes
    SourceLike
    Exceptions thrown

    IllegalStateException if txn is not active.

  9. final def asInstanceOf[T0]: T0
    Definition Classes
    Any
  10. def clone(): AnyRef
    Attributes
    protected[java.lang]
    Definition Classes
    AnyRef
    Annotations
    @throws( ... )
  11. def dbgStr: String

    Returns a string representation of the transactional value in this instance for debugging convenience.

    Returns a string representation of the transactional value in this instance for debugging convenience. The Ref reads (and writes) performed while constructing the result will be discarded before returning. This method works fine outside a transaction.

    If this method is called from within a transaction that is already doomed (status Txn.Rolledback), a string describing the reason for the outer transaction's rollback will be returned.

    Definition Classes
    SourceTxnDebuggable
  12. def dbgValue: Any

    Returns some value that is suitable for examination in a debugger, or returns a Txn.RollbackCause if called from inside a doomed atomic block.

    Returns some value that is suitable for examination in a debugger, or returns a Txn.RollbackCause if called from inside a doomed atomic block.

    Definition Classes
    SourceTxnDebuggable
  13. final def eq(arg0: AnyRef): Boolean
    Definition Classes
    AnyRef
  14. def equals(arg0: Any): Boolean
    Definition Classes
    AnyRef → Any
  15. def finalize(): Unit
    Attributes
    protected[java.lang]
    Definition Classes
    AnyRef
    Annotations
    @throws( classOf[java.lang.Throwable] )
  16. def getAndTransform(f: (A) ⇒ A)(implicit txn: InTxn): A

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

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

    f

    a function that is safe to call multiple times.

    returns

    the previous value of this Ref (the value passed to f).

    Definition Classes
    RefLike
    Exceptions thrown

    IllegalStateException if txn is not active.

  17. final def getClass(): Class[_]
    Definition Classes
    AnyRef → Any
  18. def hashCode(): Int
    Definition Classes
    AnyRef → Any
  19. final def isInstanceOf[T0]: Boolean
    Definition Classes
    Any
  20. final def ne(arg0: AnyRef): Boolean
    Definition Classes
    AnyRef
  21. final def notify(): Unit
    Definition Classes
    AnyRef
  22. final def notifyAll(): Unit
    Definition Classes
    AnyRef
  23. final def synchronized[T0](arg0: ⇒ T0): T0
    Definition Classes
    AnyRef
  24. def toString(): String
    Definition Classes
    AnyRef → Any
  25. def transformAndExtract[B](f: (A) ⇒ (A, B))(implicit txn: InTxn): B

    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 from v to f(v)._1, and returns f(v)._2.

    f

    a function that is safe to call multiple times.

    returns

    the second element of the pair returned by f.

    Definition Classes
    RefLike
    Exceptions thrown

    IllegalStateException if txn is not active.

  26. def transformAndGet(f: (A) ⇒ A)(implicit txn: InTxn): A

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

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

    f

    a function that is safe to call multiple times.

    returns

    the new value of this Ref (the value returned from f).

    Definition Classes
    RefLike
    Exceptions thrown

    IllegalStateException if txn is not active.

  27. def update(v: A)(implicit txn: InTxn): Unit

    Performs a transactional write.

    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
      ...
    }
    v

    a value to store in the Ref.

    Definition Classes
    SinkLike
    Exceptions thrown

    IllegalStateException if txn is not active.

  28. final def wait(): Unit
    Definition Classes
    AnyRef
    Annotations
    @throws( ... )
  29. final def wait(arg0: Long, arg1: Int): Unit
    Definition Classes
    AnyRef
    Annotations
    @throws( ... )
  30. final def wait(arg0: Long): Unit
    Definition Classes
    AnyRef
    Annotations
    @throws( ... )

Inherited from Sink[A]

Inherited from Source[A]

Inherited from TxnDebuggable

Inherited from RefLike[A, InTxn]

Inherited from SinkLike[A, InTxn]

Inherited from SourceLike[A, InTxn]

Inherited from AnyRef

Inherited from Any

Ungrouped