Returns a new transaction-local that holds values of type A.
Returns a new transaction-local that holds values of type A. One
TxnLocal instance holds a separate value for each transaction in which
it has been accessed. The value associated with a particular atomic
block is created on demand, and discarded at the same time that the
atomic block's after-completion handlers are invoked. TxnLocal has a
similar relationship to transactions as ThreadLocal has to threads.
There are two ways to specify the initial value that will be used if the
first access inside a transaction is not a set. If no InTxn context
is needed to compute the initial value then the by-name parameter init
is the most convenient. Because this is the first parameter, you can
omit the parameter name. To construct a TxnLocal with a default value
of aValue, simply
val tl = TxnLocal(aValue)
If computing the initial value requires access to Refs, then it is
better to use the initialValue parameter, which lets you write
val tl = TxnLocal(initialValue = { implicit txn =>
// Ref reads or writes, or handler registration
})
Unlike Refs, TxnLocals can be read or written from inside
while-preparing or while-committing callbacks, with two conditions: if
the first access is from one of these callbacks then no beforeCommit
parameter can be present; and if the first access is from one of these
callbacks and it is not a write then you must use the init
initialization method.
This factory method also accepts parameters that correspond to Txn's
transaction life-cycle handlers. These handlers will be registered in any
transaction that reads or writes the returned TxnLocal. They are
roughly
beforeCommit - the last time that Refs can be read or written;whilePreparing - the last time that the transaction can be rolled
back;whileCommitting - actions that should be atomic with respect to the
transaction (keep them fast to avoid scalability issues);afterCommit - called at some time after commit;afterRollback - called at some time after rollback of the nesting
level in which the TxnLocal was first accessed; andafterCompletion - called either after commit or after rollback. The value stored in a TxnLocal is subject to partial rollback: initial
value computations and writes from a nested atomic block will be
discarded if the block is rolled back.