openraft 0.9.23

Advanced Raft consensus
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66

use openraft_macros::add_async_trait;

use crate::engine::Command;
use crate::RaftTypeConfig;
use crate::StorageError;

/// Defines behaviors of a runtime to support the protocol engine.
///
/// An Engine defines the consensus algorithm, i.e., what to do(`command`) when some `event`
/// happens:
///
/// It receives events such as `write-log-entry` from a client,
/// or `elect` from a timer, and outputs `command`, such as
/// `append-entry-to-storage`, or `commit-entry-at-index-5` to a runtime to execute.
///
/// A `RaftRuntime` talks to `RaftStorage` and `RaftNetwork` to get things done.
///
/// The workflow of writing something through raft protocol with engine and runtime would be like
/// this:
///
/// ```text
/// Client                    Engine                         Runtime      Storage      Netwoork
///   |                         |      write x=1                |            |            |
///   |-------------------------------------------------------->|            |            |
///   |        event:write      |                               |            |            |
///   |        .------------------------------------------------|            |            |
///   |        '--------------->|                               |            |            |
///   |                         |      cmd:append-log-1         |            |            |
///   |                         |--+--------------------------->|   append   |            |
///   |                         |  |                            |----------->|            |
///   |                         |  |                            |<-----------|            |
///   |                         |  |   cmd:replicate-log-1      |   ok       |            |
///   |                         |  '--------------------------->|            |            |
///   |                         |                               |            |   send     |
///   |                         |                               |------------------------>|
///   |                         |                               |            |   send     |
///   |                         |                               |------------------------>|
///   |                         |                               |            |            |
///   |                         |                               |<------------------------|
///   |         event:ok        |                               |   ok       |            |
///   |        .------------------------------------------------|            |            |
///   |        '--------------->|                               |            |            |
///   |                         |                               |<------------------------|
///   |         event:ok        |                               |   ok       |            |
///   |        .------------------------------------------------|            |            |
///   |        '--------------->|                               |            |            |
///   |                         |     cmd:commit-log-1          |            |            |
///   |                         |------------------------------>|            |            |
///   |                         |     cmd:apply-log-1           |            |            |
///   |                         |------------------------------>|            |            |
///   |                         |                               |   apply    |            |
///   |                         |                               |----------->|            |
///   |                         |                               |<-----------|            |
///   |                         |                               |   ok       |            |
///   |<--------------------------------------------------------|            |            |
///   |        response         |                               |            |            |
/// ```
///
/// TODO: add this diagram to guides/
#[add_async_trait]
pub(crate) trait RaftRuntime<C: RaftTypeConfig> {
    /// Run a command produced by the engine.
    ///
    /// If a command can not be run, i.e., waiting for some event, it will be returned
    async fn run_command(&mut self, cmd: Command<C>) -> Result<Option<Command<C>>, StorageError<C::NodeId>>;
}