ytsaurus_client/
lock.rs

1//! Locks: what Cypress gives a transaction to coordinate with.
2//!
3//! A lock belongs to a transaction and is released when it ends. There is no
4//! way to take one without a transaction — the cluster answers `A valid master
5//! transaction is required` — so [`Client::lock`](crate::Client::lock) refuses
6//! before asking when the client is not in one.
7//!
8//! Writing to a node takes an exclusive lock on its own; taking one explicitly
9//! is for saying *now* rather than later, which is what makes it a coordination
10//! primitive rather than an implementation detail.
11
12/// What a lock leaves other transactions able to do.
13#[derive(Debug, Clone, Copy, PartialEq, Eq)]
14pub enum LockMode {
15    /// Nobody else may write to the node, and nobody else may take this lock.
16    ///
17    /// What a writer takes, and what the cluster takes on your behalf when you
18    /// write. Two transactions asking for it is the conflict worth designing
19    /// around: the loser is told which transaction won.
20    Exclusive,
21
22    /// Others may take this lock too; nobody may take an exclusive one.
23    ///
24    /// Several writers of *different* parts of a node — different children of a
25    /// map node, different attributes — rather than several writers of the same
26    /// thing.
27    Shared,
28
29    /// Pins the node as it is now, for this transaction to read.
30    ///
31    /// Compatible with somebody else's exclusive lock: they carry on writing,
32    /// and this transaction goes on seeing the version it pinned. What a long
33    /// read of a table that others keep replacing wants.
34    Snapshot,
35}
36
37impl LockMode {
38    /// The spelling the cluster expects.
39    #[must_use]
40    pub fn as_str(self) -> &'static str {
41        match self {
42            LockMode::Exclusive => "exclusive",
43            LockMode::Shared => "shared",
44            LockMode::Snapshot => "snapshot",
45        }
46    }
47}
48
49/// A lock held by a transaction.
50///
51/// Released when the transaction ends, whichever way it ends. There is no
52/// method to drop it here: the lock's lifetime is the transaction's, which is
53/// the only thing that makes it safe to hold one across a failure.
54///
55/// The cluster also answers with a revision, which is `0` for a lock that is
56/// still queued and therefore says less than it appears to. It is left out
57/// rather than exposed as a number that means two different things.
58#[derive(Debug, Clone, PartialEq, Eq)]
59pub struct Lock {
60    /// The lock's own ID. `#<id>/@state` is how the cluster reports its state.
61    pub id: String,
62    /// The node it is held on.
63    pub node_id: String,
64}
65
66#[cfg(test)]
67mod tests {
68    use super::*;
69
70    #[test]
71    fn modes_are_spelled_the_way_the_cluster_spells_them() {
72        assert_eq!(LockMode::Exclusive.as_str(), "exclusive");
73        assert_eq!(LockMode::Shared.as_str(), "shared");
74        assert_eq!(LockMode::Snapshot.as_str(), "snapshot");
75    }
76}
ytsaurus_client/lock.rs

ytsaurus_client/
lock.rs
