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
//! Thin entry point over the library.
//!
//! Everything of substance lives in the library, so the whole product is
//! testable without spawning a process.
//!
//! # Why the auxiliary channel is never locked here
//!
//! The two channels are handed over differently on purpose, and the difference
//! is a deadlock rather than a preference. It is written out at the line it
//! governs below.
use std::io::Write;
fn main() -> std::process::ExitCode {
let stdout = std::io::stdout();
// Buffering means the answer reaches the reader in as few writes as
// possible, and the explicit flush below is what makes a closed reader
// visible before the process ends. Locking it is safe because nothing else
// in this process ever writes to the primary channel.
let mut out = std::io::BufWriter::new(stdout.lock());
// The auxiliary channel is handed over UNLOCKED, and this is load-bearing
// rather than an optimisation somebody forgot to take.
//
// `stderr.lock()` here would hold the lock for the whole invocation,
// because the guard would live in this frame until `run` returned. That
// lock is reentrant per THREAD: this thread would keep writing happily,
// and any OTHER thread that wrote to the auxiliary channel would wait on
// it forever.
//
// This product HAS another thread, and the reason it has one is three
// decisions away from here. The SQL analyser runs without the crate's
// recursion protection, so as not to require a C toolchain at install
// time, and the depth of a statement is bounded instead by parsing it on a
// thread of its own with an enlarged stack. That thread is inside every
// invocation that carries a statement.
//
// The two meet at the deepest diagnostic level. From `debug` downwards the
// filter in `obs::tracing` admits every target rather than only this
// crate's, which is what that level exists for; the analyser crate reports
// through the log bridge, the bridge hands the event to the channel layer,
// and the layer writes to the auxiliary channel from the analyser's
// thread. Locked here, that write blocks; this thread is meanwhile waiting
// to join the analyser; and the invocation stops for good, having written
// nothing to either channel and having consumed no processor time at all.
// A defect that neither fails nor finishes is the worst shape available,
// and it was live under `--verbose --verbose --verbose`.
//
// The unlocked handle takes the lock per write and releases it, so another
// thread writes between this one's writes. Nothing is lost by that: the
// channel layer already writes through the unlocked handle, so writes here
// were never atomic with respect to the diagnostics beside them.
let mut err = std::io::stderr();
let number = mariadb_cli::run(std::env::args_os().collect(), &mut out, &mut err);
if out.flush().is_err() {
return mariadb_cli::error::ExitNumber::BrokenPipe.into();
}
number.into()
}