Package org.multiverse.api

## Interface Stm

- All Known Implementing Classes:
    `GammaStm`

      public interface Stm

  The main interface for software transactional memory. The main tasks are done by the following structures:
  1. `TxnObject`: the structure where state and identity are separated and where state change is coordinated through a transaction. An example of the TxnObject is the `TxnRef`, but it could just as easily by a more complex transactional datastructure that is enhanced by instrumentation.
  2. `Txn`: responsible for making sure that all changes on transactionalobjects are atomic, isolated and consistent.
  3. `TxnExecutor`: responsible for starting/committing/aborting/retrying transactions. The TxnExecutor executes an `TxnCallable` (there are different tastes for return values). The TxnCallable contains the logic that needs to be executed atomic, isolated and consistent.

  ### Pluggability

  The Stm interface provides a mechanism to separate the contract from the implementation. So it is possible to change the Stm implementation without changing the code that uses it. The idea is that for example a TL2 (MVCC) based implementation can be replaced by a Sky-STM or a lock based STM. Of course every Stm implementation will have its strong and weak spots.

  All functionality like TxnExecutors, Refs, Txn etc can be customized by providing a custom implementation of the factory/builder interfaces:

  1. `TxnRefFactoryBuilder` a builder for creating `TxnRefFactory`
  2. `TxnFactoryBuilder` a builder for creating an `TxnExecutor`/`Txn`.
  3. `TxnCollectionsFactory` a factory for creating transactional collections

  ### Multiple Stm instances

  It is important that an TxnObject only is used within a single Stm. If it is 'shared' between different stm instances, isolation problems could happen. This can be caused by the fact that different stm instances probably use different clocks or completely different mechanisms for preventing isolation problems. It depends on the implementation if any checking is done (the GammaStm does check if there is a conflict).

  ### Thread safe

  All methods on the Stm are of course thread safe.

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `TxnRefFactory` | `getDefaultRefFactory()` | Returns the default `TxnRefFactory` that can be used for easy and cheap access to a reference factory instead of setting one up through the `TxnRefFactoryBuilder`.
    `TxnCollectionsFactory` | `getDefaultTxnCollectionFactory()` | Gets the default `TxnCollectionsFactory`.
    `TxnExecutor` | `getDefaultTxnExecutor()` | Returns the default `TxnExecutor` that is useful for testing/experimentation purposes.
    `TxnRefFactoryBuilder` | `getTxRefFactoryBuilder()` | Gets the `TxnRefFactoryBuilder`.
    `Txn` | `newDefaultTxn()` | Starts a default Txn that is useful for testing/experimentation purposes.
    `OrElseBlock` | `newOrElseBlock()` | Creates an OrElseBlock.
    `TxnFactoryBuilder` | `newTxnFactoryBuilder()` | Gets the `TxnFactoryBuilder` that needs to be used to execute a `Txn` created by this Stm.

- - ### Method Detail

    - #### newTxnFactoryBuilder

          TxnFactoryBuilder newTxnFactoryBuilder()

      Gets the `TxnFactoryBuilder` that needs to be used to execute a `Txn` created by this Stm. See the `TxnFactoryBuilder` for more info. The TxnFactoryBuilder also is responsible for creating the TxnExecutor since the Txn and TxnExecutor can be tightly coupled.
      Returns:
        the TxnFactoryBuilder that is used to execute transactions on this Stm.

    - #### newDefaultTxn

          Txn newDefaultTxn()

      Starts a default Txn that is useful for testing/experimentation purposes. This method is purely for easy to use access, but doesn't provide any configuration options. See the `newTxnFactoryBuilder()` for something more configurable. In mose cases this is not the method you want to use to manage transactions.

      Transactions returned by this method are not speculative.

      Returns:
        the new default Txn.

    - #### getDefaultTxnExecutor

          TxnExecutor getDefaultTxnExecutor()

      Returns the default `TxnExecutor` that is useful for testing/experimentation purposes. This method is purely for easy to use access, but it doesn't provide any configuration options. See the `newTxnFactoryBuilder()` for something more configurable.

      Transactions used in this Block are not speculative.

      Returns:
        the default TxnExecutor.

    - #### newOrElseBlock

          OrElseBlock newOrElseBlock()

      Creates an OrElseBlock.
      Returns:
        the created OrElseBlock.

    - #### getDefaultRefFactory

          TxnRefFactory getDefaultRefFactory()

      Returns the default `TxnRefFactory` that can be used for easy and cheap access to a reference factory instead of setting one up through the `TxnRefFactoryBuilder`.
      Returns:
        the default TxnRefFactory.

    - #### getTxRefFactoryBuilder

          TxnRefFactoryBuilder getTxRefFactoryBuilder()

      Gets the `TxnRefFactoryBuilder`.
      Returns:
        the TxnRefFactoryBuilder.

    - #### getDefaultTxnCollectionFactory

          TxnCollectionsFactory getDefaultTxnCollectionFactory()

      Gets the default `TxnCollectionsFactory`.
      Returns:
        the default `TxnCollectionsFactory`.