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.
Enum Constant and Description |
---|
EVENTUAL
Eventual consistency.
|
EVENTUAL_COMMITTED
Committed eventual consistency.
|
LINEARIZABLE
Linearizable consistency.
|
UNCOMMITTED
Uncommitted eventual consistency.
|
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.
|
public static final Consistency UNCOMMITTED
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
RetryTransactionException
s. 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.
public static final Consistency EVENTUAL_COMMITTED
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 RetryTransactionException
s; 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.
public static final Consistency EVENTUAL
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
RetryTransactionException
s due to read/write conflicts, however they can throw
RetryTransactionException
s 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.
public static final Consistency LINEARIZABLE
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.
public static Consistency[] values()
for (Consistency c : Consistency.values()) System.out.println(c);
public static Consistency valueOf(String name)
name
- the name of the enum constant to be returned.IllegalArgumentException
- if this enum type has no constant with the specified nameNullPointerException
- if the argument is nullpublic boolean isBasedOnCommittedLogEntry()
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.
public boolean isWaitsForLogEntryToBeCommitted()
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.
public boolean isGuaranteesUpToDateReads()
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").
public boolean isReadOnly()
This is true for all levels except LINEARIZABLE
.
Copyright © 2022. All rights reserved.