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