Package io.permazen.kv.raft

Enum Class Consistency

java.lang.Object
java.lang.Enum<Consistency>
io.permazen.kv.raft.Consistency
All Implemented Interfaces:
Serializable, Comparable<Consistency>, Constable
public enum Consistency extends Enum<Consistency>
RaftKVTransaction supported consistency levels.

Read-write transactions (i.e., transactions containing any mutations or cluster configuration changes) are always LINEARIZABLE. Read-only transactions may also have one of the weaker consistency levels. Specifying a weaker consistency levels implicitly sets the transaction to be read-only. The default is LINEARIZABLE.

A transaction's Consistency is configured when created. To configure a non-LINEARIZABLE consistency, supply the desired Consistency under the RaftKVDatabase.OPTION_CONSISTENCY key in the options provided to RaftKVDatabase.createTransaction(java.util.Map).

Raft key watches are compatible with all Consistency levels, in that if a key watch fires due to a mutation to some key, then a subsequent transaction will see that mutation, no matter what Consistency level is configured for that transaction.

See Also:

  • Enum Constant Details

    • UNCOMMITTED

      public static final Consistency UNCOMMITTED
      Uncommitted eventual consistency.

      This level is only for read-only transactions; read-write transactions are always LINEARIZABLE.

      Transactions see a consistent view of the database that is either already committed or likely to be committed soon. This is the same as EVENTUAL_COMMITTED, but with the additional (unlikely) possibility that the view that the transaction sees may never actually get committed; this can only happen if there is a Raft leadership change during the transaction.

      Transactions at this level require no network communication, commit immediately, and never result in RetryKVTransactionExceptions. Committing a transaction at this level is actually equivalent to invoking rollback() instead of commit().

      In Raft terms, transactions are based on the latest uncommitted log entry, the commit operation does not wait for that log entry to be committed, and up-to-date reads are not guaranteed.

    • EVENTUAL_COMMITTED

      public static final Consistency EVENTUAL_COMMITTED
      Committed eventual consistency.

      This level is only for read-only transactions; read-write transactions are always LINEARIZABLE.

      Transactions see a consistent, committed view of the database as it existed at some point in the "recent past". The view is not guaranteed to be up-to-date; it's only guaranteed to be as up-to-date as what was known to this node when the transaction was opened. In general (for example, if stuck in a network partition minority), the view could be from arbitrarily far in the past.

      Unlike EVENTUAL, transactions at this level require no network communication, commit immediately, and never result in RetryKVTransactionExceptions; however, they see a potentially older view. Compared to UNCOMMITTED, transactions at this level see a view that is potentially older, in exchange for the guarantee that it has definitely been committed.

      This consistency level is useful when it's important to allow reading the database in any situation, e.g., even when the local node is in a minority partition of the cluster. Of course, the data will only be as up-to-date as is known locally.

      In Raft terms, transactions are based on the latest committed log entry, and up-to-date reads are not guaranteed.

    • EVENTUAL

      public static final Consistency EVENTUAL
      Eventual consistency.

      This level is only for read-only transactions; read-write transactions are always LINEARIZABLE.

      Transactions see a consistent, committed view of the database as it existed at some point in the "recent past". The view is not guaranteed to be up-to-date; it's only guaranteed to be as up-to-date as what was known to this node when the transaction was opened. In general (for example, if stuck in a network partition minority), the view could be from arbitrarily far in the past.

      No network traffic is generated by commit(), and transactions can never throw RetryKVTransactionExceptions due to read/write conflicts, however they can throw RetryKVTransactionExceptions in other situations, e.g., if a leader changes occurs and the base log entry is never committed.

      A commit() blocks until the log entry on which the transaction is based is committed; if no concurrent write transactions are occurring, this will happen immediately.

      In Raft terms, transactions are based on the latest uncommitted log entry, the commit operation waits for that log entry to be committed, and up-to-date reads are not guaranteed.

    • LINEARIZABLE

      public static final Consistency LINEARIZABLE
      Linearizable consistency.

      Transactions see a database that evolves step-wise through a global, linear sequence of atomic changes, where each change appears to have occurred instantaneously at some point in time between the start and end of the corresponding transaction.

      This is the default consistency level.

      In Raft terms, transactions are based on the latest uncommitted log entry, the commit operation waits for that log entry to be committed, and up-to-date reads are guaranteed.

  • Method Details

    • values

      public static Consistency[] values()
      Returns an array containing the constants of this enum class, in the order they are declared.
      Returns:
      an array containing the constants of this enum class, in the order they are declared

    • valueOf

      public static Consistency valueOf(String name)
      Returns the enum constant of this class with the specified name. The string must match exactly an identifier used to declare an enum constant in this class. (Extraneous whitespace characters are not permitted.)
      Parameters:
      name - the name of the enum constant to be returned.
      Returns:
      the enum constant with the specified name
      Throws:
      IllegalArgumentException - if this enum class has no constant with the specified name
      NullPointerException - if the argument is null

    • isBasedOnCommittedLogEntry

      public boolean isBasedOnCommittedLogEntry()
      Determines the log entry on which transactions at this level are based.

      When false, transactions are based on this node's most recent log entry, whether committed or not. When true, transactions are based on this node's most recent committed log entry. The former provides a more up-to-date view, but commit() can block (and could possibly fail with a RetryKVTransactionException) when isWaitsForLogEntryToBeCommitted() is true. The latter, when combined with isGuaranteesUpToDateReads() being false, allows read-only transactions to commit immediately with no network traffic, even when in a minority partition.

      Returns:
      true if transactions at this level are always based on committed log entries

    • isWaitsForLogEntryToBeCommitted

      public boolean isWaitsForLogEntryToBeCommitted()
      Determines whether transactions at this level block in commit() until the log entry on which they are based is committed.

      This setting has no effect if isBasedOnCommittedLogEntry() returns true (i.e., EVENTUAL_COMMITTED), because in that case the log entry on which the transaction is based is already committed when transaction starts.

      Returns:
      true if transactions at this level wait for their base log entry to be committed

    • isGuaranteesUpToDateReads

      public boolean isGuaranteesUpToDateReads()
      Determines whether transactions at this level guarantee reading the most up-to-date information.

      This setting has no effect on transactions that contain mutations; they always read the most up-to-date information.

      If this returns false, read-only transactions may read out-of-date information ("eventual consistency").

      Returns:
      true if transactions at this level guarantee up-to-date reads

    • isReadOnly

      public boolean isReadOnly()
      Determines whether transactions at this level are always read-only.

      This is true for all levels except LINEARIZABLE.

      Returns:
      true if transactions at this level are always read-only