mariadb-cli 0.1.1

One-shot agent-native command line client for MariaDB servers
Documentation
//! The admission gate every fan-out passes through.
//!
//! Describing fifty tables is worth doing several at a time; doing all fifty at
//! once is not. An unbounded fan-out opens as many connections as the work has
//! parts, and the server, not this process, pays for that: it hits the server's
//! own connection ceiling and takes the caller's other sessions down with it.
//!
//! So every place that splits work holds a licence from this gate, and the
//! number of licences is bounded twice: by what the host can usefully run at
//! once, and by a ceiling this product declares and never exceeds.

use crate::error::{Failure, Result};
use std::sync::Arc;
use tokio::sync::{OwnedSemaphorePermit, Semaphore};
use tokio_util::sync::CancellationToken;

/// The most simultaneous parts this product runs when nobody has said otherwise.
///
/// Declared rather than derived, because the cost of exceeding it is paid on
/// the server, whose limits this process cannot see. It is the built-in behind
/// `limits.max_concurrency_ceiling` rather than the last word, which it used to
/// be; [`ceiling`] is the last word.
///
/// There used to be a second number saying the same thing: `settings` carried
/// a `32` of its own while this said `64`. One rule stated twice, differing by
/// a factor of two, and only the `32` ever reached a decision. The two are now
/// this one constant, and it keeps the value the product actually applied,
/// because resolving a contradiction is no licence to raise a ceiling nobody
/// asked to raise.
pub const MAX_PERMITS: usize = 32;

/// The ceiling in force for this invocation, once configuration has been read.
///
/// Zero means nothing has been settled and [`MAX_PERMITS`] stands. The shape is
/// borrowed from the packet ceiling, which had the same problem first: the
/// number is wanted deep in the call graph, where no configuration is in hand,
/// and threading one through every signature between here and there would put a
/// settings argument on functions that have nothing to do with settings.
///
/// # Why this became a setting
///
/// It was a number in this file and nothing else, so an operator with a server
/// that could take more simultaneous work had no way to say so. The argument
/// written above — that this process cannot see the server's own limits — is a
/// good argument for a conservative default and no argument at all for refusing
/// the operator who CAN see them.
static CEILING: std::sync::atomic::AtomicUsize = std::sync::atomic::AtomicUsize::new(0);

/// Puts the configured ceiling in force for the rest of the invocation.
pub fn declare_ceiling(permits: usize) {
    CEILING.store(permits, std::sync::atomic::Ordering::Relaxed);
}

/// The ceiling in force, which is the built-in until one has been settled.
#[must_use]
pub fn ceiling() -> usize {
    match CEILING.load(std::sync::atomic::Ordering::Relaxed) {
        0 => MAX_PERMITS,
        settled => settled,
    }
}

/// Answers with this many parts when it is a number this product admits.
///
/// The single place the domain of `--max-concurrency` and of
/// `limits.max_concurrency` is decided, so a number typed on the command line
/// and a number handed to a gate agree by construction rather than by two
/// authors remembering the same rule (FR-067).
///
/// # Errors
///
/// Returns a usage failure when no part at all was asked for, because a
/// ceiling that admits nothing would hang the invocation rather than limit it,
/// and when the number is above the declared ceiling.
pub fn admissible(permits: usize) -> Result<usize> {
    if permits == 0 {
        return Err(Failure::usage(
            "concurrency.none_admitted",
            "a ceiling of zero admits no work at all",
        )
        .with_hint("ask for at least one simultaneous part"));
    }
    let ceiling = ceiling();
    if permits > ceiling {
        return Err(
            Failure::usage("concurrency.above_ceiling", permits.to_string())
                .with_detail("detail", permits.to_string())
                .with_detail("ceiling", ceiling.to_string())
                .with_hint(format!("ask for at most {ceiling}")),
        );
    }
    Ok(permits)
}

/// How many parts run at once when nothing was configured.
///
/// A host that cannot report its own parallelism is served one part at a time,
/// which is slower and always correct.
#[must_use]
pub fn permits_for_host() -> usize {
    std::thread::available_parallelism()
        .map_or(1, std::num::NonZeroUsize::get)
        .min(ceiling())
}

/// A licence to run one part of the work.
///
/// Holding it is what keeps the fan-out bounded; dropping it lets the next part
/// in. It is deliberately opaque: there is nothing to read from it.
#[derive(Debug)]
pub struct Licence(#[allow(dead_code)] OwnedSemaphorePermit);

/// The bound on simultaneous work within one invocation.
#[derive(Debug, Clone)]
pub struct Gate {
    semaphore: Arc<Semaphore>,
    permits: usize,
}

impl Gate {
    /// Builds a gate handing out exactly this many licences.
    ///
    /// # Errors
    ///
    /// Returns a usage failure when no licence at all was asked for, because a
    /// gate that admits nothing would hang the invocation rather than limit
    /// it, and when the number is above the declared ceiling.
    pub fn new(permits: usize) -> Result<Self> {
        let permits = admissible(permits)?;

        Ok(Self {
            semaphore: Arc::new(Semaphore::new(permits)),
            permits,
        })
    }

    /// Builds the gate this host and this configuration describe.
    ///
    /// # Errors
    ///
    /// Returns a usage failure when a ceiling was configured and it is zero or
    /// above the declared ceiling.
    pub fn for_host(configured: Option<usize>) -> Result<Self> {
        Self::new(configured.unwrap_or_else(permits_for_host))
    }

    /// How many parts may run at once.
    #[must_use]
    pub const fn permits(&self) -> usize {
        self.permits
    }

    /// How many licences are free right now.
    #[must_use]
    pub fn available(&self) -> usize {
        self.semaphore.available_permits()
    }

    /// Waits for a licence, or for the invocation to be told to stop.
    ///
    /// Waiting is what makes the gate a gate, so this really does wait. It
    /// watches the stop signal at the same time, because a caller who
    /// interrupted the work must not be made to wait for a licence that is
    /// only needed to do work nobody wants any more.
    ///
    /// # Errors
    ///
    /// Returns an interrupted failure when the invocation was told to stop
    /// while waiting, and a limit failure when the gate was closed, which
    /// cannot happen while the gate is alive.
    pub async fn acquire(&self, token: &CancellationToken) -> Result<Licence> {
        let semaphore = Arc::clone(&self.semaphore);
        tokio::select! {
            () = token.cancelled() => Err(Failure::interrupted(
                "interrupted.waiting_for_admission",
                "the invocation was stopped while waiting to start a part of the work",
            )),
            permit = semaphore.acquire_owned() => permit.map(Licence).map_err(|error| {
                Failure::limit(
                    "concurrency.gate_closed",
                    "the admission gate was closed before the work started",
                )
                .with_cause(error.to_string())
            }),
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    /// FR-067. The domain of the ceiling is settled once, so the gate and the
    /// number read off the command line cannot disagree about it.
    #[test]
    fn the_admitted_domain_is_decided_in_one_place() {
        assert_eq!(admissible(1).expect("legal"), 1);
        assert_eq!(admissible(MAX_PERMITS).expect("legal"), MAX_PERMITS);

        let none = admissible(0).expect_err("zero admits no work");
        assert_eq!(none.code(), "concurrency.none_admitted");
        assert_eq!(none.exit_number().code(), 2);

        let above = admissible(MAX_PERMITS + 1).expect_err("above the ceiling");
        assert_eq!(above.code(), "concurrency.above_ceiling");
        assert_eq!(above.exit_number().code(), 2);
    }

    #[test]
    fn a_gate_that_admits_nothing_is_refused_rather_than_built() {
        let failure = Gate::new(0).expect_err("must refuse");
        assert_eq!(failure.code(), "concurrency.none_admitted");
        assert_eq!(failure.exit_number().code(), 2);
    }

    #[test]
    fn a_ceiling_above_the_declared_one_is_refused() {
        let failure = Gate::new(MAX_PERMITS + 1).expect_err("must refuse");
        assert_eq!(failure.code(), "concurrency.above_ceiling");
    }

    #[test]
    fn the_host_ceiling_never_exceeds_the_declared_one() {
        assert!(permits_for_host() >= 1);
        assert!(permits_for_host() <= MAX_PERMITS);
        assert!(Gate::for_host(None).is_ok());
    }

    #[test]
    fn a_configured_ceiling_outranks_the_host() {
        let gate = Gate::for_host(Some(3)).expect("legal");
        assert_eq!(gate.permits(), 3);
    }

    #[tokio::test]
    async fn the_gate_never_admits_more_than_its_licences() {
        let gate = Gate::new(2).expect("legal");
        let token = CancellationToken::new();

        let first = gate.acquire(&token).await.expect("free");
        let second = gate.acquire(&token).await.expect("free");
        assert_eq!(gate.available(), 0);

        // A third part must wait, so asking for it with no time to spare finds
        // nothing rather than starting a third piece of work.
        let waited =
            tokio::time::timeout(std::time::Duration::from_millis(50), gate.acquire(&token)).await;
        assert!(waited.is_err(), "the third part must be made to wait");

        drop(first);
        drop(second);
        assert_eq!(gate.available(), 2);
    }

    #[tokio::test]
    async fn a_licence_returns_to_the_gate_when_the_part_finishes() {
        let gate = Gate::new(1).expect("legal");
        let token = CancellationToken::new();

        {
            let _licence = gate.acquire(&token).await.expect("free");
            assert_eq!(gate.available(), 0);
        }
        assert_eq!(gate.available(), 1);
        gate.acquire(&token).await.expect("free again");
    }

    #[tokio::test]
    async fn a_stopped_invocation_never_waits_for_a_licence() {
        let gate = Gate::new(1).expect("legal");
        let token = CancellationToken::new();
        let _held = gate.acquire(&token).await.expect("free");

        token.cancel();
        let failure = gate.acquire(&token).await.expect_err("must not wait");
        assert_eq!(failure.category(), crate::error::Category::Interrupted);
        assert_eq!(failure.exit_number().code(), 130);
    }
}