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.
an active transaction.
the value of the Ref as observed by txn.
if txn is not active.
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.
an idempotent function.
the result of applying f to the value contained in this Ref.
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.
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.
a value of the Ref, not necessary consistent with the rest of
the reads performed by txn.
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).
a value to store in the Ref.
if txn is not active.
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) }.
Works like set(v), but returns the old value.
Works like set(v), but returns the old value.
the previous value of this Ref, as observed by txn.
if txn is not active.
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.
a function that is safe to call multiple times, and safe to call later during the transaction.
if txn is not active.
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.
a partial function that is safe to call multiple times, and safe to call later in the transaction.
pf.isDefinedAt(v), where v was the value of this Ref
before transformation (if any).
if txn is not active.
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.
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.
the quantity by which to multiply the value of this Ref.
if txn is not active.
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.
the quantity by which to increment the value of this Ref.
if txn is not active.
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.
the quantity by which to decrement the value of this Ref.
if txn is not active.
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.
the quantity by which to divide the value of this Ref.
if txn is not active.
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 ... }
an active transaction.
the value of the Ref as observed by txn.
if txn is not active.
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.
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.
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.
a function that is safe to call multiple times.
the previous value of this Ref (the value passed to f).
if txn is not active.
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.
a function that is safe to call multiple times.
the second element of the pair returned by f.
if txn is not active.
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.
a function that is safe to call multiple times.
the new value of this Ref (the value returned from f).
if txn is not active.
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 ... }
a value to store in the Ref.
if txn is not active.
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.Viewreturned fromsingle. 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
InTxnpassed to the block by the STM. Atomic blocks nest, so to participate in an atomic block for which aInTxnis not conveniently available, just create a new atomic block usingatomic { implicit t => // the body }In the static scope of an atomic block reads and writes of a
Refare performed byx.getandx.set(v), or more concisely byx()andx() = v.x.singlereturns aRef.Viewthat 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
Refinstances 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 createRefs 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 createRefinstances paired with a single STM-managed memory location.