Package org.multiverse.api.exceptions

## Class ControlFlowError

- java.lang.Object
- - java.lang.Throwable
  - - java.lang.Error
    - - org.multiverse.api.exceptions.ControlFlowError

- All Implemented Interfaces:
    `Serializable`
  Direct Known Subclasses:
    `ReadWriteConflict`, `RetryError`, `SpeculativeConfigurationError`

      public abstract class ControlFlowError
      extends Error

  An `Error` thrown to regulate control flow inside multiverse `TxnExecutor`. Normally it would be a very bad thing to regulate control flow using an exception/error, but to make seamless integration in the Java language possible, there is no better alternative. So these exceptions should not catch unless you really know know what you are doing. So catching all Throwable instances (including Error) is a bad practice.

  There current are 3 different types of ControlFlowErrors:
  1. `ReadWriteConflict`: used to indicate read and write conflicts
  2. `RetryError`: used for blocking
  3. `SpeculativeConfigurationError`: used for guessing the most optimal configuration for transactions

  ### Why it is an Error

  It is an Error instead of a RuntimeException, to prevent users trying to catch the error inside a try/catch(RuntimeException) block and consuming important events like a ReadWriteConflict. In most cases these events can be solved by retrying the transaction.

  It is an Error instead of a Throwable, because a Throwable needs to be propagated, so making the code a lot more awkward to work with.

  ### Instance Caching

  Normally ControlFlowErrors are cached to be reused because they can be thrown very often to be caught by the TxnExecutor and discarded. Especially the stacktrace is very expensive to create. By default all ControlFlowErrors are reused but with the `TxnFactoryBuilder.setControlFlowErrorsReused(boolean)` this behavior can be changed. It also can be configured on the Stm level, depending on the Stm implementation. For the `GammaStm` you need to look at the `GammaStmConfig.controlFlowErrorsReused`.

  The constructors also expose configuration options to have the StackTrace filled. Especially for an Error that is reused, not filling the stacktrace is very important because else the developer is looking at code where the exception very likely didn't happen.

  See Also:
    Serialized Form

- - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `ControlFlowError​(boolean fillStackTrace)` | Creates a new ControlFlowError.
    `ControlFlowError​(boolean fillStackTrace, String message)` | Creates a new ControlFlowError with the provided message.
    `ControlFlowError​(boolean fillStackTrace, String message, Throwable cause)` | Creates a new ControlFlowError with the provided message and cause.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `StackTraceElement[]` | `getStackTrace()` |

    - ### Methods inherited from class java.lang.Throwable

      `addSuppressed, fillInStackTrace, getCause, getLocalizedMessage, getMessage, getSuppressed, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### ControlFlowError

          public ControlFlowError​(boolean fillStackTrace)

      Creates a new ControlFlowError.
      Parameters:
        `fillStackTrace` - true if the StackTrace should be filled, false otherwise.

    - #### ControlFlowError

          public ControlFlowError​(boolean fillStackTrace,
                                  String message)

      Creates a new ControlFlowError with the provided message.
      Parameters:
        `fillStackTrace` - true if the StackTrace should be filled, false otherwise.
        `message` - the message of the exception.

    - #### ControlFlowError

          public ControlFlowError​(boolean fillStackTrace,
                                  String message,
                                  Throwable cause)

      Creates a new ControlFlowError with the provided message and cause.
      Parameters:
        `fillStackTrace` - true if the StackTrace should be filled, false otherwise.
        `message` - the message of the exception.
        `cause` - the cause of the exception.

  - ### Method Detail

    - #### getStackTrace

          public StackTraceElement[] getStackTrace()

      Overrides:
        `getStackTrace` in class `Throwable`