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
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
//! Advisory single-writer lock for a ForgeDB data directory.
//!
//! Enforces the v1 single-writer-per-process contract at the OS advisory-lock
//! level: the first process to call [`DirLock::acquire`] on a data directory
//! holds an exclusive lock; any subsequent attempt — from a different process —
//! returns `Err` with `ErrorKind::WouldBlock` so the caller can print a clear
//! diagnostic and exit cleanly.
//!
//! The lock is **not** a lease, a registry, or a distributed coordinator — it
//! only prevents two writers from accidentally opening the same directory.
//! Concurrent-writer serialization is explicitly out of scope for v1.
//!
//! The lock file is `<root>/.forgedb.lock`. It is created if absent and is
//! never deleted on drop — the OS reclaims the advisory lock automatically when
//! the file handle closes.
use FileExt;
use ;
use io;
use Path;
/// The single-writer lock filename under a data directory (`<root>/.forgedb.lock`).
///
/// **Cross-crate contract:** `forgedb-coordinator` advisory-locks this same file
/// (by a duplicated constant, since it must not depend on `forgedb-storage*` —
/// MVCC spec T3-8) so a coordinator and a standalone writer are mutually
/// exclusive (T3-5). Renaming it here without updating
/// `forgedb_coordinator::server::DIR_LOCK_FILENAME` breaks that exclusion; a
/// parity test in each crate pins the string.
pub const LOCK_FILENAME: &str = ".forgedb.lock";
/// An advisory exclusive lock on a ForgeDB data directory.
///
/// Holds an open `File` to `<root>/.forgedb.lock` with an OS-level exclusive
/// advisory lock (via [`fs2::FileExt::try_lock_exclusive`]). The lock is
/// released automatically when this value is dropped (the `File` closes, which
/// the OS uses to release the advisory lock).
///
/// # Acquiring
///
/// ```no_run
/// use forgedb_storage_native::DirLock;
/// use std::path::Path;
///
/// let lock = DirLock::acquire(Path::new("./data"))?;
/// // lock is held for the lifetime of the value
/// drop(lock); // released here
/// # Ok::<(), std::io::Error>(())
/// ```
///
/// # Conflicts
///
/// If another process already holds the lock, [`acquire`](DirLock::acquire)
/// returns `Err` with `kind() == io::ErrorKind::WouldBlock`. The caller
/// should print a human-readable message and exit:
///
/// ```no_run
/// use forgedb_storage_native::DirLock;
/// use std::path::Path;
///
/// match DirLock::acquire(Path::new("./data")) {
/// Ok(lock) => { /* proceed */ }
/// Err(e) if e.kind() == std::io::ErrorKind::WouldBlock => {
/// eprintln!("error: another ForgeDB writer already has this data directory open");
/// std::process::exit(1);
/// }
/// Err(e) => return Err(e),
/// }
/// # Ok::<(), std::io::Error>(())
/// ```
/// The platform EWOULDBLOCK code, used to normalise fs2 lock-conflict errors.
///
/// On most POSIX systems EWOULDBLOCK == EAGAIN (11 on Linux, 35 on macOS).
/// We only need this as a fallback for older fs2 versions that may not surface
/// the error as `WouldBlock` directly.