Package org.multiverse.api.references

## Interface TxnRef<E>

- All Superinterfaces:
    `TxnObject`
  All Known Implementing Classes:
    `GammaTxnRef`

      public interface TxnRef<E>
      extends TxnObject

  A Transactional Reference comparable to the Clojure Ref. If a method is prefixed with atomic, the call will always run under its own txn, no matter if there already is a txn available (so the propagation level is `PropagationLevel.RequiresNew`). For the other methods, always an txn needs to be available, else you will get the `TxnMandatoryException`.

  ### ControlFlowError

  All non atomic methods are able to throw a (subclass) of the `ControlFlowError`. This error should not be caught, it is task of the `TxnExecutor` to deal with.

  ### TransactionExecutionException

  Most of the methods can throw a `TxnExecutionException`. This exception can be caught, but in most cases you want to figure out what the cause is (e.g. because there are too many retries) and solve that problem.

  ### Threadsafe

  All methods are threadsafe.

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `E` | `alterAndGet​(Function<E> function)` | Alters the value stored in this Ref using the provided function and returns the result.
    `E` | `alterAndGet​(Txn txn, Function<E> function)` | Alters the value stored in this Ref using the provided function and lifting on the provided txn.
    `E` | `atomicAlterAndGet​(Function<E> function)` | Atomically applies the function to the current value in this ref and returns the new value.
    `boolean` | `atomicCompareAndSet​(E expectedValue, E newValue)` | Executes a compare and set atomically.
    `E` | `atomicGet()` | Atomically gets the value.
    `E` | `atomicGetAndAlter​(Function<E> function)` | Atomically applies the function to alter the value stored in this ref and returns the old value.
    `E` | `atomicGetAndSet​(E newValue)` | Atomically sets the value and returns the previous value.
    `boolean` | `atomicIsNull()` | Atomically check if the current value is null.
    `E` | `atomicSet​(E newValue)` | Atomically sets the value and returns the new value.
    `E` | `atomicWeakGet()` | Atomically gets the value without providing any ordering guarantees.
    `void` | `await​(E value)` | Awaits for the value to become the given value.
    `void` | `await​(Predicate<E> predicate)` | Awaits until the predicate holds.
    `void` | `await​(Txn txn, E value)` | Awaits for the reference to become the given value.
    `void` | `await​(Txn txn, Predicate<E> predicate)` | Awaits until the predicate holds using the provided txn.
    `E` | `awaitNotNullAndGet()` | Awaits for the value to become not null.
    `E` | `awaitNotNullAndGet​(Txn txn)` | Awaits for the value to become not null using the provided txn.
    `void` | `awaitNull()` | Awaits for the value to become null.
    `void` | `awaitNull​(Txn txn)` | Awaits for the value to become not null using the provided txn.
    `void` | `commute​(Function<E> function)` | Applies the function on the ref in a commuting manner.
    `void` | `commute​(Txn txn, Function<E> function)` | Applies the function on the ref in a commuting manner.
    `E` | `get()` | Gets the value using the provided txn.
    `E` | `get​(Txn txn)` | Gets the value using the provided txn.
    `E` | `getAndAlter​(Function<E> function)` | Alters the value stored in this Ref using the provided function amd returns the old value.
    `E` | `getAndAlter​(Txn txn, Function<E> function)` | Alters the value stored in this Ref using the function and returns the old value, using the provided txn.
    `E` | `getAndLock​(LockMode lockMode)` | Gets the value and applies the lock.
    `E` | `getAndLock​(Txn txn, LockMode lockMode)` | Gets the value using the provided txn and acquired the lock with the specified LockMode.
    `E` | `getAndSet​(E value)` | Sets the value the value and returns the new value.
    `E` | `getAndSet​(Txn txn, E value)` | Sets the value using the provided txn.
    `E` | `getAndSetAndLock​(E value, LockMode lockMode)` | Sets the value, acquired the Lock with the specified Lockmode and returns the previous value.
    `E` | `getAndSetAndLock​(Txn txn, E value, LockMode lockMode)` | Sets the value and acquired the Lock with the provided LockMode.
    `boolean` | `isNull()` | Checks if the current value is null.
    `boolean` | `isNull​(Txn txn)` | Checks if the current value is null using the provided txn.
    `E` | `set​(E value)` | Sets the new value.
    `E` | `set​(Txn txn, E value)` | Sets the new value using the provided txn.
    `E` | `setAndLock​(E value, LockMode lockMode)` | Sets the new value and applies the lock.
    `E` | `setAndLock​(Txn txn, E value, LockMode lockMode)` | Sets the new value using the provided txn.

    - ### Methods inherited from interface org.multiverse.api.TxnObject

      `atomicToString, ensure, ensure, getLock, getStm, getVersion, toDebugString, toString, toString`

- - ### Method Detail

    - #### get

          E get()

      Gets the value using the provided txn.
      Returns:
        the current value.
      Throws:
        `TxnExecutionException` - if something failed while using the txn. The txn is guaranteed to have been aborted.
        `ControlFlowError` - if the Stm needs to control the flow in a different way than normal returns of exceptions. The txn is guaranteed to have been aborted.
      See Also:
        `atomicGet()`

    - #### getAndLock

          E getAndLock​(LockMode lockMode)

      Gets the value and applies the lock. If the current lockMode already is higher than the provided lockMode the Lock is not upgraded to a higher value.

      This call lifts on the `Txn` stored in the `TxnThreadLocal`.

      Parameters:
        `lockMode` - the LockMode applied.
      Returns:
        the current value.
      Throws:
        `TxnExecutionException` - if something failed while using the txn. The txn is guaranteed to have been aborted.
        `ControlFlowError` - if the Stm needs to control the flow in a different way than normal returns of exceptions. The txn is guaranteed to have been aborted.
      See Also:
        `atomicGet()`

    - #### get

          E get​(Txn txn)

      Gets the value using the provided txn.
      Parameters:
        `txn` - the `Txn` used for this operation.
      Returns:
        the value stored in the ref.
      Throws:
        `NullPointerException` - if txn is null.
        `TxnExecutionException` - if something failed while using the txn. The txn is guaranteed to have been aborted.
        `ControlFlowError` - if the Stm needs to control the flow in a different way than normal returns of exceptions. The txn is guaranteed to have been aborted.

    - #### getAndLock

          E getAndLock​(Txn txn,
                       LockMode lockMode)

      Gets the value using the provided txn and acquired the lock with the specified LockMode.
      Parameters:
        `txn` - the `Txn` used for this operation.
        `lockMode` - the LockMode used
      Returns:
        the value stored in the ref.
      Throws:
        `NullPointerException` - if txn is null or if lockMode is null. If LockMode is null and a running txn is available it will be aborted.
        `TxnExecutionException` - if something failed while using the txn. The txn is guaranteed to have been aborted.
        `ControlFlowError` - if the Stm needs to control the flow in a different way than normal returns of exceptions. The txn is guaranteed to have been aborted.

    - #### set

          E set​(E value)

      Sets the new value.

      This call lifts on the `Txn` stored in the `TxnThreadLocal`.

      Parameters:
        `value` - the new value.
      Returns:
        the new value.
      Throws:
        `TxnExecutionException` - if something failed while using the txn. The txn is guaranteed to have been aborted.
        `ControlFlowError` - if the Stm needs to control the flow in a different way than normal returns of exceptions. The txn is guaranteed to have been aborted.

    - #### setAndLock

          E setAndLock​(E value,
                       LockMode lockMode)

      Sets the new value and applies the lock.

      This call lifts on the `Txn` stored in the `TxnThreadLocal`.

      Parameters:
        `value` - the new value.
        `lockMode` - the used LockMode.
      Returns:
        the new value.
      Throws:
        `NullPointerException` - if lockMode is null (if the txn is alive, it will also be aborted.
        `TxnExecutionException` - if something failed while using the txn. The txn is guaranteed to have been aborted.
        `ControlFlowError` - if the Stm needs to control the flow in a different way than normal returns of exceptions. The txn is guaranteed to have been aborted.

    - #### set

          E set​(Txn txn,
                E value)

      Sets the new value using the provided txn.
      Parameters:
        `txn` - the `Txn` used for this operation.
        `value` - the new value
      Returns:
        the old value
      Throws:
        `NullPointerException` - if txn is null.
        `TxnExecutionException` - if something failed while using the txn. The txn is guaranteed to have been aborted.
        `ControlFlowError` - if the Stm needs to control the flow in a different way than normal returns of exceptions. The txn is guaranteed to have been aborted.

    - #### setAndLock

          E setAndLock​(Txn txn,
                       E value,
                       LockMode lockMode)

      Sets the new value using the provided txn.
      Parameters:
        `txn` - the `Txn` used for this operation.
        `value` - the new value
        `lockMode` - the lockMode used.
      Returns:
        the old value
      Throws:
        `NullPointerException` - if txn is null or lockMode is null. If the lockMode is null and the txn is alive, it will be aborted.
        `TxnExecutionException` - if something failed while using the txn. The txn is guaranteed to have been aborted.
        `ControlFlowError` - if the Stm needs to control the flow in a different way than normal returns of exceptions. The txn is guaranteed to have been aborted.

    - #### getAndSet

          E getAndSet​(E value)

      Sets the value the value and returns the new value.

      This call lifts on the `Txn` stored in the `TxnThreadLocal`.

      Parameters:
        `value` - the new value.
      Returns:
        the old value.
      Throws:
        `TxnExecutionException` - if something failed while using the txn. The txn is guaranteed to have been aborted.
        `ControlFlowError` - if the Stm needs to control the flow in a different way than normal returns of exceptions. The txn is guaranteed to have been aborted.

    - #### getAndSetAndLock

          E getAndSetAndLock​(E value,
                             LockMode lockMode)

      Sets the value, acquired the Lock with the specified Lockmode and returns the previous value.

      This call lifts on the `Txn` stored in the `TxnThreadLocal`.

      Parameters:
        `value` - the new value.
        `lockMode` - the LockMode used.
      Returns:
        the old value.
      Throws:
        `NullPointerException` - if LockMode is null. If a running txn is available, it will be aborted.
        `TxnExecutionException` - if something failed while using the txn. The txn is guaranteed to have been aborted.
        `ControlFlowError` - if the Stm needs to control the flow in a different way than normal returns of exceptions. The txn is guaranteed to have been aborted.

    - #### getAndSet

          E getAndSet​(Txn txn,
                      E value)

      Sets the value using the provided txn.
      Parameters:
        `value` - the new value.
        `txn` - the `Txn` used for this operation.
      Returns:
        the old value.
      Throws:
        `NullPointerException` - if txn is null.
        `TxnExecutionException` - if something failed while using the txn. The txn is guaranteed to have been aborted.
        `ControlFlowError` - if the Stm needs to control the flow in a different way than normal returns of exceptions. The txn is guaranteed to have been aborted.

    - #### getAndSetAndLock

          E getAndSetAndLock​(Txn txn,
                             E value,
                             LockMode lockMode)

      Sets the value and acquired the Lock with the provided LockMode.

      This call lifts on the `Txn` stored in the `TxnThreadLocal`.

      Parameters:
        `value` - the new value.
        `txn` - the `Txn` used for this operation.
        `lockMode` - the LockMode used.
      Returns:
        the old value.
      Throws:
        `NullPointerException` - if txn or LockMode is null. If the txn is running, and the LockMode is null, it will be aborted.
        `TxnExecutionException` - if something failed while using the txn. The txn is guaranteed to have been aborted.
        `ControlFlowError` - if the Stm needs to control the flow in a different way than normal returns of exceptions. The txn is guaranteed to have been aborted.

    - #### atomicGet

          E atomicGet()

      Atomically gets the value. The value could be stale as soon as it is returned. This method doesn't care about any running txns. It could be that this call fails e.g. when a ref is locked. If you don't care about correct orderings, see the `atomicWeakGet()`.
      Returns:
        the current value.
      Throws:
        `TxnExecutionException`

    - #### atomicWeakGet

          E atomicWeakGet()

      Atomically gets the value without providing any ordering guarantees. This method is extremely cheap and will never fail. So even if the ref is privatized, this call will still complete.

      It is the best method to call if you just want to get the current value stored.

      Returns:
        the value.

    - #### atomicSet

          E atomicSet​(E newValue)

      Atomically sets the value and returns the new value. This method doesn't care about any running txns.
      Parameters:
        `newValue` - the new value.
      Returns:
        the new value.
      Throws:
        `TxnExecutionException`

    - #### atomicGetAndSet

          E atomicGetAndSet​(E newValue)

      Atomically sets the value and returns the previous value. This method doesn't care about any running txns.
      Parameters:
        `newValue` - the new value.
      Returns:
        the old value.
      Throws:
        `TxnExecutionException`

    - #### commute

          void commute​(Function<E> function)

      Applies the function on the ref in a commuting manner. So if there are no dependencies, the function will commute. If somehow there already is a dependency or a dependency is formed on the result of the commuting function, the function will not commute and will be exactly the same as an alter.

      This is different than the behavior in Clojure where the commute will be re-applied at the end of the txn, even though some dependency is introduced, which can lead to inconsistencies.

      This call lifts on the `Txn` stored in the `TxnThreadLocal`.

      Parameters:
        `function` - the function to apply to this reference.
      Throws:
        `NullPointerException` - if function is null.
        `TxnExecutionException` - if something failed while using the txn. The txn is guaranteed to have been aborted.
        `ControlFlowError` - if the Stm needs to control the flow in a different way than normal returns of exceptions. The txn is guaranteed to have been aborted.

    - #### commute

          void commute​(Txn txn,
                       Function<E> function)

      Applies the function on the ref in a commuting manner. So if there are no dependencies, the function will commute. If somehow there already is a dependency or a dependency is formed on the result of the commuting function, the function will not commute and will be exactly the same as an alter.

      This is different than the behavior in Clojure where the commute will be re-applied at the end of the txn, even though some dependency is introduced, which can lead to inconsistencies.

      This call lifts on the `Txn` stored in the `TxnThreadLocal`.

      Parameters:
        `txn` - the `Txn` used for this operation.
        `function` - the function to apply to this reference.
      Throws:
        `NullPointerException` - if function is null. If there is an active txn, it will be aborted.
        `TxnExecutionException` - if something failed while using the txn. The txn is guaranteed to have been aborted.
        `ControlFlowError` - if the Stm needs to control the flow in a different way than normal returns of exceptions. The txn is guaranteed to have been aborted.

    - #### atomicAlterAndGet

          E atomicAlterAndGet​(Function<E> function)

      Atomically applies the function to the current value in this ref and returns the new value. This method doesn't care about any running txns.
      Parameters:
        `function` - the Function used
      Returns:
        the new value.
      Throws:
        `NullPointerException` - if function is null.

    - #### alterAndGet

          E alterAndGet​(Function<E> function)

      Alters the value stored in this Ref using the provided function and returns the result.

      This call lifts on the `Txn` stored in the `TxnThreadLocal`.

      Parameters:
        `function` - the function that alters the value stored in this Ref.
      Returns:
        the new value.
      Throws:
        `NullPointerException` - if function is null. The Txn will also be aborted.
        `TxnExecutionException` - if something failed while using the txn. The txn is guaranteed to have been aborted.
        `ControlFlowError` - if the Stm needs to control the flow in a different way than normal returns of exceptions. The txn is guaranteed to have been aborted.

    - #### alterAndGet

          E alterAndGet​(Txn txn,
                        Function<E> function)

      Alters the value stored in this Ref using the provided function and lifting on the provided txn.
      Parameters:
        `function` - the function that alters the value stored in this Ref.
        `txn` - the `Txn` used for this operation.
      Returns:
        the new value.
      Throws:
        `NullPointerException` - if function or txn is null.
        `TxnExecutionException` - if something failed while using the txn. The txn is guaranteed to have been aborted.
        `ControlFlowError` - if the Stm needs to control the flow in a different way than normal returns of exceptions. The txn is guaranteed to have been aborted.

    - #### atomicGetAndAlter

          E atomicGetAndAlter​(Function<E> function)

      Atomically applies the function to alter the value stored in this ref and returns the old value. This method doesn't care about any running txns.
      Parameters:
        `function` - the Function used
      Returns:
        the old value.
      Throws:
        `NullPointerException` - if function is null.
        `TxnExecutionException`

    - #### getAndAlter

          E getAndAlter​(Function<E> function)

      Alters the value stored in this Ref using the provided function amd returns the old value.

      This call lifts on the `Txn` stored in the `TxnThreadLocal`.

      Parameters:
        `function` - the function that alters the value stored in this Ref.
      Returns:
        the old value.
      Throws:
        `NullPointerException` - if function is null. The txn will be aborted as well.
        `TxnExecutionException` - if something failed while using the txn. The txn is guaranteed to have been aborted.
        `ControlFlowError` - if the Stm needs to control the flow in a different way than normal returns of exceptions. The txn is guaranteed to have been aborted.

    - #### getAndAlter

          E getAndAlter​(Txn txn,
                        Function<E> function)

      Alters the value stored in this Ref using the function and returns the old value, using the provided txn.
      Parameters:
        `function` - the function that alters the value stored in this Ref.
        `txn` - the `Txn` used for this operation.
      Returns:
        the old value
      Throws:
        `NullPointerException` - if function or txn is null. The txn will be aborted as well.
        `TxnExecutionException` - if something failed while using the txn. The txn is guaranteed to have been aborted.
        `ControlFlowError` - if the Stm needs to control the flow in a different way than normal returns of exceptions. The txn is guaranteed to have been aborted.

    - #### atomicCompareAndSet

          boolean atomicCompareAndSet​(E expectedValue,
                                      E newValue)

      Executes a compare and set atomically. This method doesn't care about any running txns.
      Parameters:
        `expectedValue` - the expected value.
        `newValue` - the new value.
      Returns:
        true if the compareAndSwap was a success, false otherwise.
      Throws:
        `TxnExecutionException`

    - #### isNull

          boolean isNull()

      Checks if the current value is null.

      This call lifts on the `Txn` stored in the `TxnThreadLocal`.

      Returns:
        true if null, false otherwise.
      Throws:
        `TxnExecutionException` - if something failed while using the txn. The txn is guaranteed to have been aborted.
        `ControlFlowError` - if the Stm needs to control the flow in a different way than normal returns of exceptions. The txn is guaranteed to have been aborted.

    - #### isNull

          boolean isNull​(Txn txn)

      Checks if the current value is null using the provided txn.
      Parameters:
        `txn` - the `Txn` used for this operation.
      Returns:
        true if the value is null, false otherwise.
      Throws:
        `NullPointerException` - if txn is null.
        `TxnExecutionException` - if something failed while using the txn. The txn is guaranteed to have been aborted.
        `ControlFlowError` - if the Stm needs to control the flow in a different way than normal returns of exceptions. The txn is guaranteed to have been aborted.

    - #### atomicIsNull

          boolean atomicIsNull()

      Atomically check if the current value is null. This method doesn't care about any running txns.
      Returns:
        true if null, false otherwise.
      Throws:
        `TxnExecutionException`

    - #### awaitNotNullAndGet

          E awaitNotNullAndGet()

      Awaits for the value to become not null. If the value already is not null, this call returns the stored value. If the value is null, a retry is done.

      This call lifts on the `Txn` stored in the `TxnThreadLocal`.

      Returns:
        the stored value.
      Throws:
        `TxnExecutionException` - if something failed while using the txn. The txn is guaranteed to have been aborted.
        `ControlFlowError` - if the Stm needs to control the flow in a different way than normal returns of exceptions. The txn is guaranteed to have been aborted.

    - #### awaitNotNullAndGet

          E awaitNotNullAndGet​(Txn txn)

      Awaits for the value to become not null using the provided txn. If the value already is not null, this call returns the stored value. If the value is null, a retry is done.
      Parameters:
        `txn` - the `Txn` used for this operation.
      Returns:
        the stored value.
      Throws:
        `NullPointerException` - if txn is null.
        `TxnExecutionException` - if something failed while using the txn. The txn is guaranteed to have been aborted.
        `ControlFlowError` - if the Stm needs to control the flow in a different way than normal returns of exceptions. The txn is guaranteed to have been aborted.

    - #### awaitNull

          void awaitNull()

      Awaits for the value to become null. If the value already is null, this call continues. If the reference is not null, a retry is done.

      This call lifts on the `Txn` stored in the `TxnThreadLocal`.

      Throws:
        `TxnExecutionException` - if something failed while using the txn. The txn is guaranteed to have been aborted.
        `ControlFlowError` - if the Stm needs to control the flow in a different way than normal returns of exceptions. The txn is guaranteed to have been aborted.

    - #### awaitNull

          void awaitNull​(Txn txn)

      Awaits for the value to become not null using the provided txn. If the value already is null, this call continues. If the value is not null, a retry is done.
      Parameters:
        `txn` - the `Txn` used for this operation.
      Throws:
        `NullPointerException` - if txn is null.
        `TxnExecutionException` - if something failed while using the txn. The txn is guaranteed to have been aborted.
        `ControlFlowError` - if the Stm needs to control the flow in a different way than normal returns of exceptions. The txn is guaranteed to have been aborted.

    - #### await

          void await​(E value)

      Awaits for the value to become the given value. If the value already has the the specified value, the call continues, else a retry is done.

      This call lifts on the `Txn` stored in the `TxnThreadLocal`.

      Parameters:
        `value` - the value to wait for.
      Throws:
        `TxnExecutionException` - if something failed while using the txn. The txn is guaranteed to have been aborted.
        `ControlFlowError` - if the Stm needs to control the flow in a different way than normal returns of exceptions. The txn is guaranteed to have been aborted.

    - #### await

          void await​(Txn txn,
                     E value)

      Awaits for the reference to become the given value. If the value already has the the specified value, the call continues, else a retry is done.
      Parameters:
        `txn` - the `Txn` used for this operation.
        `value` - the value to wait for.
      Throws:
        `NullPointerException` - if txn is null.
        `TxnExecutionException` - if something failed while using the txn. The txn is guaranteed to have been aborted.
        `ControlFlowError` - if the Stm needs to control the flow in a different way than normal returns of exceptions. The txn is guaranteed to have been aborted.

    - #### await

          void await​(Predicate<E> predicate)

      Awaits until the predicate holds. If the value already evaluates to true, the call continues else a retry is done. If the predicate throws an exception, the txn is aborted and the throwable is propagated.

      This call lifts on the `Txn` stored in the `TxnThreadLocal`.

      Parameters:
        `predicate` - the predicate to evaluate.
      Throws:
        `NullPointerException` - if predicate is null. When there is a non dead txn, it will be aborted.
        `TxnExecutionException` - if something failed while using the txn. The txn is guaranteed to have been aborted.
        `ControlFlowError` - if the Stm needs to control the flow in a different way than normal returns of exceptions. The txn is guaranteed to have been aborted.

    - #### await

          void await​(Txn txn,
                     Predicate<E> predicate)

      Awaits until the predicate holds using the provided txn. If the value already evaluates to true, the call continues else a retry is done. If the predicate throws an exception, the txn is aborted and the throwable is propagated.
      Parameters:
        `txn` - the `Txn` used for this operation.
        `predicate` - the predicate to evaluate.
      Throws:
        `NullPointerException` - if predicate is null or txn is null. When there is a non dead txn, it will be aborted.
        `TxnExecutionException` - if something failed while using the txn. The txn is guaranteed to have been aborted.
        `ControlFlowError` - if the Stm needs to control the flow in a different way than normal returns of exceptions. The txn is guaranteed to have been aborted.