//! The guard around one atomic terminal repaint.

/// Brackets one render pass so the terminal paints it as a single update
/// instead of painting whatever has been written to it so far.
///
/// `begin` starts a synchronized update, `CSI ?2026h`. From that point the
/// terminal holds the last frame it painted and queues every write that
/// follows without showing any of them. `end` sends the matching
/// `CSI ?2026l`, and the terminal paints everything queued since `begin`
/// in one pass. A terminal that does not support the sequence ignores
/// both codes and paints as it always did, so the guard is safe to use
/// unconditionally.
///
/// The guard must close before the play loop polls for a key. A poll can
/// wait up to the loop's poll interval, and an open guard freezes the
/// display for as long as it stays open: leaving it open across the poll
/// would freeze the terminal between frames, not just during a repaint.
/// Terminals also carry their own safety timeout that ends an update on
/// its own a few seconds after `begin` with no matching `end`, but that
/// timeout exists to recover from a crash. It is not a substitute for
/// closing the guard on every pass.
pub trait SyncGuard {
    /// Starts a synchronized update.
    fn begin(&mut self);

    /// Ends a synchronized update, painting everything written since the
    /// matching `begin`.
    fn end(&mut self);
}