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

    Author:
    Peter Veentjer
    See Also:
    Serialized Form
    • 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.