object Txn

The Txn object provides methods that operate on the current transaction context. These methods are only valid within an atomic block or a transaction life-cycle handler, which is checked at compile time by requiring that an implicit InTxn or InTxnEnd be available.

Linear Supertypes
AnyRef, Any
Ordering
  1. Alphabetic
  2. By Inheritance
Inherited
  1. Txn
  2. AnyRef
  3. Any
  1. Hide All
  2. Show All
Visibility
  1. Public
  2. All

Type Members

  1. case class ExplicitRetryCause (timeoutNanos: Option[Long]) extends TransientRollbackCause with Product with Serializable

    The RollbackCause for an atomic block execution attempt that ended with a call to retry or retryFor.

    The RollbackCause for an atomic block execution attempt that ended with a call to retry or retryFor. The atomic block will be retried after some memory location read in the previous attempt has changed.

  2. trait ExternalDecider extends AnyRef

    An ExternalDecider is given the final control over the decision of whether or not to commit a transaction, which allows two-phase commit to be integrated with a single non-transactional resource.

    An ExternalDecider is given the final control over the decision of whether or not to commit a transaction, which allows two-phase commit to be integrated with a single non-transactional resource. shouldCommit will only be called if a InTxn has successfully called all of its before-commit handlers, acquired all necessary write locks, validated all of its reads and called all of its while-preparing handlers. The decider may then attempt a non-transactional operation whose outcome is uncertain, and based on the outcome may directly cause the transaction to commit or roll back.

  3. case class OptimisticFailureCause (category: Symbol, trigger: Option[Any]) extends TransientRollbackCause with Product with Serializable

    The RollbackCause for a NestingLevel whose optimistic execution was invalid, and that should be retried.

    The RollbackCause for a NestingLevel whose optimistic execution was invalid, and that should be retried. The specific situations in which an optimistic failure can occur are specific to the STM algorithm, but may include:

    • the STM detected that the value returned by a previous read in this nesting level is no longer valid;
    • a cyclic dependency has occurred and this nesting level must be rolled back to avoid deadlock;
    • a transaction with a higher priority wanted to write to a Ref written by this transaction;
    • the STM decided to switch execution strategies for this atomic block; or
    • no apparent reason (*).

    (*) - Some STMs perform validation, conflict detection and deadlock cycle breaking using algorithms that are conservative approximations. This means that any particular attempt to execute an atomic block might fail spuriously.

    category

    an STM-specific label for the reason behind this optimistic failure. The set of possible categories is bounded.

    trigger

    the specific object that led to the optimistic failure, if it is available, otherwise None.

  4. sealed abstract class PermanentRollbackCause extends RollbackCause

    RollbackCauses for which the failure is permanent and no attempt should be made to retry the underlying atomic block.

  5. sealed abstract class RollbackCause extends AnyRef

    A record of the reason that a atomic block execution attempt was rolled back.

  6. case class RolledBack (cause: RollbackCause) extends Status with Product with Serializable

    The Status for an atomic block execution attempt that is being or that has been cancelled.

    The Status for an atomic block execution attempt that is being or that has been cancelled. None of the Ref writes made during this nesting level or in any child nesting level will ever be visible to other threads. The atomic block will be automatically retried if cause is a TransientRollbackCause, unless STM-specific retry thresholds are exceeded.

  7. sealed abstract class Status extends AnyRef

    The current state of an attempt to execute an atomic block.

  8. sealed abstract class TransientRollbackCause extends RollbackCause

    RollbackCauses for which the failure is transient and another attempt should be made to execute the underlying atomic block.

  9. case class UncaughtExceptionCause (x: Throwable) extends PermanentRollbackCause with Product with Serializable

    The RollbackCause for an atomic block that should not be restarted because it threw an exception.

    The RollbackCause for an atomic block that should not be restarted because it threw an exception. The exception might have been thrown from the body of the atomic block or from a handler invoked before the commit decision. Exceptions used for control flow are not included (see TxnExecutor.isControlFlow).

    Scala's STM discards Ref writes performed by atomic blocks that throw an exception. This is referred to as "failure atomicity". In a system that uses exceptions for error cleanup this design tends to preserve the invariants of shared data structures, which is a good thing. If a system uses exceptions for control flow, however, this design may lead to unexpected behavior. The TxnExecutor object's isControlFlow method is used to distinguish exceptions representing control flow transfers from those used to represent error conditions. See TxnExecutor.transformDefault to change the default rules.

  10. case class UnrecordedTxnCause [Z](z: Z) extends PermanentRollbackCause with Product with Serializable

    The RollbackCause of a successfully completed atomic.unrecorded block.

    The RollbackCause of a successfully completed atomic.unrecorded block. See TxnExecutor.unrecorded.

Value Members

  1. final def !=(arg0: Any): Boolean
    Definition Classes
    AnyRef → Any
  2. final def ##(): Int
    Definition Classes
    AnyRef → Any
  3. final def ==(arg0: Any): Boolean
    Definition Classes
    AnyRef → Any
  4. def afterCommit(handler: (Status) ⇒ Unit)(implicit txn: InTxnEnd): Unit

    Arranges for handler to be executed as soon as possible after the current transaction is committed, if this nesting level is part of the overall transaction commit.

    Arranges for handler to be executed as soon as possible after the current transaction is committed, if this nesting level is part of the overall transaction commit. Details:

    • no transaction will be active while the handler is run, but it may access Refs using a new top-level atomic block or .single;
    • the handler runs after all internal locks have been released, so any values read or written in the transaction might already have been changed by another thread before the handler is executed;
    • handlers will be executed in their registration order; and
    • handlers may be registered so long as the current transaction status is not RolledBack or Committed.
  5. def afterCompletion(handler: (Status) ⇒ Unit)(implicit txn: InTxnEnd): Unit

    Arranges for handler to be called as both an after-commit and after-rollback handler.

    Arranges for handler to be called as both an after-commit and after-rollback handler.

    Equivalent to: 

    afterRollback(handler)
afterCommit(handler)
  6. def afterRollback(handler: (Status) ⇒ Unit)(implicit txn: InTxnEnd): Unit

    Arranges for handler to be executed as soon as possible after the current nesting level is rolled back, or runs the handler immediately if the current nesting level's status is already RolledBack.

    Arranges for handler to be executed as soon as possible after the current nesting level is rolled back, or runs the handler immediately if the current nesting level's status is already RolledBack. Details:

    • the handler will be executed during any partial rollback that includes the current nesting level;
    • the handler will be run before any additional attempts to execute the atomic block;
    • handlers will be run in the reverse of their registration order; and
    • handlers may be registered so long as the current transaction status is not Committed.
  7. final def asInstanceOf[T0]: T0
    Definition Classes
    Any
  8. def beforeCommit(handler: (InTxn) ⇒ Unit)(implicit txn: InTxn): Unit

    Arranges for handler to be executed as late as possible while the root nesting level of the current transaction is still Active, unless the current nesting level is rolled back.

    Arranges for handler to be executed as late as possible while the root nesting level of the current transaction is still Active, unless the current nesting level is rolled back. Reads, writes and additional nested transactions may be performed inside the handler. Details:

    • it is possible that after handler is run the transaction might still be rolled back;
    • it is okay to call beforeCommit from inside handler, the reentrantly added handler will be included in this before-commit phase; and
    • before-commit handlers will be executed in their registration order.
  9. def clone(): AnyRef
    Attributes
    protected[java.lang]
    Definition Classes
    AnyRef
    Annotations
    @throws( ... )
  10. final def eq(arg0: AnyRef): Boolean
    Definition Classes
    AnyRef
  11. def equals(arg0: Any): Boolean
    Definition Classes
    AnyRef → Any
  12. def finalize(): Unit
    Attributes
    protected[java.lang]
    Definition Classes
    AnyRef
    Annotations
    @throws( classOf[java.lang.Throwable] )
  13. def findCurrent(implicit mt: MaybeTxn): Option[InTxn]

    Returns Some(t) if called from inside the static or dynamic scope of the transaction context t, None otherwise.

    Returns Some(t) if called from inside the static or dynamic scope of the transaction context t, None otherwise. If an implicit InTxn is available it may be used.

  14. final def getClass(): Class[_]
    Definition Classes
    AnyRef → Any
  15. def hashCode(): Int
    Definition Classes
    AnyRef → Any
  16. final def isInstanceOf[T0]: Boolean
    Definition Classes
    Any
  17. final def ne(arg0: AnyRef): Boolean
    Definition Classes
    AnyRef
  18. final def notify(): Unit
    Definition Classes
    AnyRef
  19. final def notifyAll(): Unit
    Definition Classes
    AnyRef
  20. def retry(implicit txn: InTxn): Nothing

    Rolls back the current nesting level for modular blocking.

    Rolls back the current nesting level for modular blocking. It will be retried, but only after some memory location observed by this transaction has been changed. If any alternatives to this atomic block were provided via orAtomic or atomic.oneOf, then the alternative will be tried before blocking.

    Exceptions thrown

    IllegalStateException if the transaction is not active.

  21. def retryFor(timeout: Long, unit: TimeUnit = TimeUnit.MILLISECONDS)(implicit txn: InTxn): Unit

    Causes the transaction to roll back and retry using modular blocking with a timeout, or returns immediately if the timeout has already expired.

    Causes the transaction to roll back and retry using modular blocking with a timeout, or returns immediately if the timeout has already expired. The STM keeps track of the total amount of blocking that has occurred during modular blocking; this time is apportioned among the calls to View.tryAwait and retryFor that are part of the current attempt. retryFor(0) is a no-op.

    Returns only if the timeout has expired.

    timeout

    the maximum amount of time that this retryFor should block, in units of unit.

    unit

    the units in which to measure timeout, by default milliseconds.

  22. def rollback(cause: RollbackCause)(implicit txn: InTxnEnd): Nothing

    Causes the current nesting level to be rolled back due to the specified cause.

    Causes the current nesting level to be rolled back due to the specified cause. This method may only be called by the thread executing the transaction; obtain a NestingLevel instance n and call n.requestRollback(cause) if you wish to doom a transaction from another thread.

    Exceptions thrown

    IllegalStateException if the current transaction has already decided to commit.

  23. def setExternalDecider(decider: ExternalDecider)(implicit txn: InTxnEnd): Unit

    (rare) Delegates final decision of the outcome of the transaction to decider if the current nesting level participates in the top-level commit.

    (rare) Delegates final decision of the outcome of the transaction to decider if the current nesting level participates in the top-level commit. This method can succeed with at most one value per top-level transaction.

    Exceptions thrown

    IllegalArgumentException if setExternalDecider(d) was previously called in this transaction, d != decider, and the nesting level from which setExternalDecider(d) was called has not rolled back.

    IllegalStateException if the current transaction's status is not Active or Preparing

  24. def status(implicit txn: InTxnEnd): Status

    Returns the status of the current nesting level of the current transaction, equivalent to NestingLevel.current.status.

  25. final def synchronized[T0](arg0: ⇒ T0): T0
    Definition Classes
    AnyRef
  26. def toString(): String
    Definition Classes
    AnyRef → Any
  27. final def wait(): Unit
    Definition Classes
    AnyRef
    Annotations
    @throws( ... )
  28. final def wait(arg0: Long, arg1: Int): Unit
    Definition Classes
    AnyRef
    Annotations
    @throws( ... )
  29. final def wait(arg0: Long): Unit
    Definition Classes
    AnyRef
    Annotations
    @throws( ... )
  30. def whileCommitting(handler: (InTxnEnd) ⇒ Unit)(implicit txn: InTxnEnd): Unit

    (rare) Arranges for handler to be called after (if) it has been decided that the current transaction will commit, but before the writes made by the transaction have become available to other threads.

    (rare) Arranges for handler to be called after (if) it has been decided that the current transaction will commit, but before the writes made by the transaction have become available to other threads. While-committing handlers can lead to scalability problems, because while this transaction is in the Committing state it might obstruct other transactions. Details:

    • the handler must not access any Refs, even using Ref.single;
    • handlers will be executed in their registration order; and
    • handlers may be registered so long as the current transaction status is not RolledBack or Committed.
  31. def whilePreparing(handler: (InTxnEnd) ⇒ Unit)(implicit txn: InTxnEnd): Unit

    (rare) Arranges for handler to be called after the Ref reads and writes have been checked for serializability, but before the decision has been made to commit or roll back.

    (rare) Arranges for handler to be called after the Ref reads and writes have been checked for serializability, but before the decision has been made to commit or roll back. While-preparing handlers can lead to scalability problems, because while this transaction is in the Preparing state it might obstruct other transactions. Details:

    • the handler must not access any Refs, even using Ref.single;
    • handlers will be executed in their registration order; and
    • handlers may be registered while the transaction is active, or from a while-preparing callback during the Preparing phase.
  32. object Active extends Status with Product with Serializable

    The Status for a transaction nesting level that may perform Ref reads and writes, that is waiting for a child nesting level to complete, or that has been merged into an Active parent nesting level.

  33. object Committed extends Status with Product with Serializable

    The Status for the nesting levels of a transaction that has been committed.

    The Status for the nesting levels of a transaction that has been committed. After-commit callbacks may still be running.

  34. object Committing extends Status with Product with Serializable

    The Status for the nesting levels of a transaction that has decided to commit, but whose Ref writes are not yet visible to other threads.

  35. object Prepared extends Status with Product with Serializable

    The Status for the nesting levels of a transaction that has successfully acquired all write permissions necessary to succeed, and that has delegated the final commit decision to an external decider.

  36. object Preparing extends Status with Product with Serializable

    The Status for the nesting levels of a transaction that are attempting to commit, but for which the outcome is uncertain.

Inherited from AnyRef

Inherited from Any

Ungrouped