jk-core 0.2.7

Core state and integration contracts for jk
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
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122

use std::collections::VecDeque;

use super::{CommandRecord, CommandRecordFinish, CommandRecordStart};

/// A stable command-history id for the current process.
#[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
pub struct CommandRecordId(u64);

impl CommandRecordId {
    /// Returns the numeric id assigned by the in-memory history.
    #[must_use]
    pub const fn get(self) -> u64 {
        self.0
    }
}

/// Recent command records retained in memory.
#[derive(Clone, Debug)]
pub struct CommandHistory {
    records: VecDeque<CommandRecord>,
    limit: usize,
    next_id: u64,
}

impl CommandHistory {
    /// Creates an empty command history with a maximum record count.
    #[must_use]
    pub const fn new(limit: usize) -> Self {
        Self {
            records: VecDeque::new(),
            limit,
            next_id: 1,
        }
    }

    /// Returns the maximum number of records retained in memory.
    #[must_use]
    pub const fn limit(&self) -> usize {
        self.limit
    }

    /// Starts a command record before execution.
    pub fn start(&mut self, input: CommandRecordStart) -> PendingCommandRecord {
        let id = self.allocate_id();
        let record = CommandRecord::started(id, input);
        self.push_record(record);
        PendingCommandRecord { id }
    }

    /// Finishes a pending command record.
    ///
    /// If the pending record has already been evicted by the history limit, this method does
    /// nothing.
    pub fn finish(&mut self, pending: &PendingCommandRecord, finish: CommandRecordFinish) -> bool {
        if let Some(record) = self
            .records
            .iter_mut()
            .find(|record| record.id == pending.id)
        {
            return record.finish(finish);
        }
        false
    }

    /// Appends an already-completed command record.
    ///
    /// This is useful for synchronous command paths where the caller already has all timing and
    /// result data at the recording boundary.
    pub fn append(
        &mut self,
        input: CommandRecordStart,
        finish: CommandRecordFinish,
    ) -> CommandRecordId {
        let pending = self.start(input);
        let id = pending.id;
        self.finish(&pending, finish);
        id
    }

    /// Returns retained records from oldest to newest.
    #[must_use]
    pub fn records(&self) -> impl DoubleEndedIterator<Item = &CommandRecord> {
        self.records.iter()
    }

    const fn allocate_id(&mut self) -> CommandRecordId {
        let id = CommandRecordId(self.next_id);
        self.next_id += 1;
        id
    }

    fn push_record(&mut self, record: CommandRecord) {
        if self.limit == 0 {
            return;
        }

        while self.records.len() >= self.limit {
            self.records.pop_front();
        }
        self.records.push_back(record);
    }
}

impl Default for CommandHistory {
    fn default() -> Self {
        Self::new(128)
    }
}

/// A pending command record handle returned by [`CommandHistory::start`].
#[derive(Debug, Eq, PartialEq)]
pub struct PendingCommandRecord {
    id: CommandRecordId,
}

impl PendingCommandRecord {
    /// Returns the id of the pending command record.
    #[must_use]
    pub const fn id(&self) -> CommandRecordId {
        self.id
    }
}