mariadb-cli 0.1.1

One-shot agent-native command line client for MariaDB servers
Documentation
//! 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()
}