szetszwo commented on PR #1338:
URL: https://github.com/apache/ratis/pull/1338#issuecomment-3822740055
> ... I struggled a bit with reworking the section on read consistency. If
you have any further thoughts on how to make that section clearer or improve
its flow, please let me know.
I have the following suggestion for the read section:
```md
#### Read Consistency Options
Ratis provides several read patterns with different consistency and
performance characteristics.
Read requests query the state machine of a server directly without going
through the Raft consensus protocol.
The `sendReadOnly()` API sends the request to the leader.
(When a non-leader server receives such request, it throws a
`NotLeaderException`
and then the client will retry other servers.)
In contrast, the `sendReadOnly(message, serverId)` API sends the request to
a particular server,
which may be a leader or a follower.
The server's `raft.server.read.option` configuration affects read behavior:
* **DEFAULT (default setting)**: `sendReadOnly()` performs leader reads for
efficiency.
It provides strong consistency under normal conditions.
* Split-brain Problem: In case that an old leader has been partitioned
from the majority
and a new leader has been elected, reading from the old leader can return
stale data
since the old leader does not have the new transactions committed by the
new leader.
* **LINEARIZABLE**: both `sendReadOnly()` and `sendReadOnly(message,
serverId)`
use the ReadIndex protocol to provide linearizable consistency, ensuring
you always read the most
up-to-date committed data and won't read stale data as described in the
"Split-brain Problem" above.
* Non-linearizable API: Clients may use `sendReadOnlyNonLinearizable()` to
read from leader's state machine
directly without a linearizable guarantee.
Other than the `sendReadOnly(..)` methods mentioned above,
we have the following read APIs:
**Stale reads with minimum index** let you specify a minimum log index that
the peer must have applied
before serving the read. Call `sendStaleRead()`: if the peer hasn't caught
up to your minimum index,
it will throw a `StaleReadException`.
**Asynchronous reads**:
Ratis supports both blocking reads and asynchronous reads.
All the blocking read methods are supported by asynchronous reads
-- the blocking reads return a reply directly while asynchronous reads
return a future of the reply.
Asynchronous reads additionally support the following APIs
* **Read-after-write consistency** ensures reads reflect the latest
successful write by the same client.
Since write requests go through the Raft consensus protocol but read
requests do not,
a read request $R$ may be completed before a write request $W$
even if $R$ is sent (asynchronously) after $W$.
Therefore, the reply returned by $R$ may not include the result updated by
$W$.
Use `sendReadAfterWrite()` when you need to read your own writes immediately.
* **Unorder reads** let the asynchronous read requests complete in any order.
The fastest reply is completed first.
Use `sendReadOnlyUnordered()` when you don't care about the ordering.
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
