io.permazen.kv.raft

Enum Consistency

java.lang.Object

java.lang.Enum<Consistency>

io.permazen.kv.raft.Consistency

All Implemented Interfaces:

Serializable, Comparable<Consistency>

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:

RaftKVTransaction.getConsistency(), Strong consistency models

Enum Constant Summary

Enum Constants

Enum Constant and Description
EVENTUAL Eventual consistency.
EVENTUAL_COMMITTED Committed eventual consistency.
LINEARIZABLE Linearizable consistency.
UNCOMMITTED Uncommitted eventual consistency.

Method Summary

Modifier and Type	Method and Description
boolean	isBasedOnCommittedLogEntry() Determines the log entry on which transactions at this level are based.
boolean	isGuaranteesUpToDateReads() Determines whether transactions at this level guarantee reading the most up-to-date information.
boolean	isReadOnly() Determines whether transactions at this level are always read-only.
boolean	isWaitsForLogEntryToBeCommitted() Determines whether transactions at this level block in commit() until the log entry on which they are based is committed.
static Consistency	valueOf(String name) Returns the enum constant of this type with the specified name.
static Consistency[]	values() Returns an array containing the constants of this enum type, in the order they are declared.

Methods inherited from class java.lang.Enum

clone, compareTo, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Enum Constant Detail

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 RetryTransactionExceptions. 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 RetryTransactionExceptions; 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 RetryTransactionExceptions due to read/write conflicts, however they can throw RetryTransactionExceptions 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 Detail

values

public static Consistency[] values()

Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows:

for (Consistency c : Consistency.values())
    System.out.println(c);

Returns:

an array containing the constants of this enum type, in the order they are declared

valueOf

public static Consistency valueOf(String name)

Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (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 type 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 RetryTransactionException) 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