rm_lisa/display/

mod.rs

//! [`SuperConsole`]; The Structure that renders everything.
//!
//! This directory contains the base implementation for [`SuperConsole`] the
//! main type that handles displaying all the information we get fed from
//! various sources. It also contains supporting types for the console such
//! as the throttler that ensures we don't eat up all your CPU time with
//! printing to the console too often.
//!
//! Chances are if you're looking to want to do anything with the actual
//! displaying of log lines. This is the place to be.
//!
//! ## Throttling
//!
//! When printing to standard-out, and standard-error we can cause severe
//! CPU contention when we print _too often_ to these channels. As such we
//! apply throttling (think like a buffered writer) to how often we update.
//!
//! There are a couple ways around this:
//!
//! 1. Manually create a super console with [`SuperConsole::new_with_outputs`],
//!    and set the parameter `should_throttle` to false. You can still specify
//!    standard-out/standard-error. ***this will fully disable throttling, and
//!    as a result CPU can go out of control.***
//! 2. Store a reference to [`SuperConsole`], and call [`SuperConsole::tick`]
//!    once the throttling limit has surpassed. You can call tick as many times
//!    as you want, and it will _always_ be safe.

pub mod render_state;
pub mod renderers;
pub mod tracing;

use crate::{
	app_name_to_prefix,
	display::{
		render_state::UnlockedRendererState,
		renderers::{
			ColorConsoleRenderer, ConsoleOutputFeatures, ConsoleRenderer, JSONConsoleRenderer,
			TextConsoleRenderer,
		},
		tracing::SuperConsoleLogMessage,
	},
	errors::LisaError,
	input::InputProvider,
	tasks::TaskEventLogProvider,
};
use parking_lot::{Mutex, RawMutex, lock_api::MutexGuard};
use std::{
	io::{Stderr, Stdout, Write as IoWrite, stderr as get_stderr, stdout as get_stdout},
	sync::Arc,
	time::Duration,
};
use tokio::{
	signal::ctrl_c,
	sync::{
		Mutex as AsyncMutex,
		mpsc::{Receiver as BoundedReceiver, Sender as BoundedSender, channel as bounded_channel},
	},
	task::Builder as TaskBuilder,
	time::sleep,
};

/// How many logs can be queued (this gets flushed every ~15ms, so doesn't need to be too large).
const LOG_CHANNEL_SIZE: usize = 64_usize;

/// Effectively the console "renderer".
///
/// [`SuperConsole`] is responsible for keeping track of the 'rendering'
/// state, and managing it effectively. This crucially does not handle any of
/// the input tracking or any of the other console related bits.
///
/// It is called [`SuperConsole`] as it's output is heavily inspired by the
/// Buck1 renderer also with the name [`SuperConsole`]. Buck2 also has a
/// concept of a [`SuperConsole`], but I don't like it's output at all. So
/// don't confuse it with the rust library 'superconsole', or it's buck2
/// counterpart.
pub struct SuperConsole<
	StdoutTy: ConsoleOutputFeatures + IoWrite + Send + 'static,
	StderrTy: ConsoleOutputFeatures + IoWrite + Send + 'static,
> {
	/// Queue a flush off the underlying messages.
	flush_sender: BoundedSender<()>,
	/// Used to signal that a flush _has_ occured.
	did_do_flush: AsyncMutex<BoundedReceiver<()>>,
	/// The messages to actually log to the screen.
	log_messages: BoundedSender<SuperConsoleLogMessage>,
	/// The underlying renderer that actually prints to stdout, and stderr.
	state: Arc<Mutex<UnlockedRendererState<StdoutTy, StderrTy>>>,
	/// A channel used to stop tick tasking.
	stop_tick_task: BoundedSender<()>,
}

impl SuperConsole<Stdout, Stderr> {
	/// Create a new super console that will print to the programs STDOUT/STDERR.
	///
	/// This will dynamically choose a renderer to use based off the default
	/// renderers that are present in lisa (color, json, and text).
	///
	/// ## Errors
	///
	/// If we could not identify a renderer to use, If we cannot spawn a
	/// background task to render inputs.
	pub fn new(app_name: &'static str) -> Result<Self, LisaError> {
		let stdout_sink = get_stdout();
		let stderr_sink = get_stderr();

		let environment_prefix = app_name_to_prefix(app_name);
		let stdout_renderer = Self::choose_default_renderer(&stdout_sink, &environment_prefix)
			.ok_or(LisaError::NoRendererFound)?;
		let stderr_renderer = Self::choose_default_renderer(&stderr_sink, &environment_prefix)
			.ok_or(LisaError::NoRendererFound)?;

		let (log_messages, log_receiver) = bounded_channel(LOG_CHANNEL_SIZE);
		let (flush_sender, flush_receiver) = bounded_channel(1);
		let (flush_completed_sender, flush_completed_receiver) = bounded_channel(1);
		let (stop_tick_sender, stop_tick_receiver) = bounded_channel(1);

		let state = Arc::new(Mutex::new(UnlockedRendererState::new(
			app_name,
			&environment_prefix,
			(stdout_sink, stderr_sink),
			(stdout_renderer, stderr_renderer),
			log_receiver,
		)));
		Self::spawn_tick_task(
			flush_completed_sender,
			flush_receiver,
			stop_tick_receiver,
			state.clone(),
		)?;

		Ok(Self {
			did_do_flush: AsyncMutex::new(flush_completed_receiver),
			flush_sender,
			log_messages,
			state,
			stop_tick_task: stop_tick_sender,
		})
	}

	/// Create a new super console that will print to the programs STDOUT/STDERR.
	///
	/// In this case the renderers are explicitly passed in allowing for fully
	/// custom rendering. It is the callers job to make sure that they have
	/// respected all and any user preferences for _which_ renderer they want to
	/// use.
	///
	/// ## Errors
	///
	/// If we cannot spawn a background task to render inputs.
	pub fn new_preselected_renderers(
		app_name: &'static str,
		stdout_renderer: Box<dyn ConsoleRenderer>,
		stderr_renderer: Box<dyn ConsoleRenderer>,
	) -> Result<Self, LisaError> {
		let stdout_sink = get_stdout();
		let stderr_sink = get_stderr();

		let environment_prefix = app_name_to_prefix(app_name);
		let (log_messages, log_receiver) = bounded_channel(LOG_CHANNEL_SIZE);
		let (flush_sender, flush_receiver) = bounded_channel(1);
		let (flush_completed_sender, flush_completed_receiver) = bounded_channel(1);
		let (stop_tick_sender, stop_tick_receiver) = bounded_channel(1);

		let state = Arc::new(Mutex::new(UnlockedRendererState::new(
			app_name,
			&environment_prefix,
			(stdout_sink, stderr_sink),
			(stdout_renderer, stderr_renderer),
			log_receiver,
		)));
		Self::spawn_tick_task(
			flush_completed_sender,
			flush_receiver,
			stop_tick_receiver,
			state.clone(),
		)?;

		Ok(Self {
			did_do_flush: AsyncMutex::new(flush_completed_receiver),
			flush_sender,
			log_messages,
			state,
			stop_tick_task: stop_tick_sender,
		})
	}
}

impl<
	StdoutTy: ConsoleOutputFeatures + IoWrite + Send + 'static,
	StderrTy: ConsoleOutputFeatures + IoWrite + Send + 'static,
> SuperConsole<StdoutTy, StderrTy>
{
	/// Create a new super console where outputs go somewhere specific (may not be
	/// stdout/stderr).
	///
	/// ## Errors
	///
	/// If we cannot find a renderer for your given stdout/stderr types, or cannot
	/// spawn a background task to progress the input.
	pub fn new_with_outputs(
		app_name: &'static str,
		stdout: StdoutTy,
		stderr: StderrTy,
	) -> Result<Self, LisaError> {
		let environment_prefix = app_name_to_prefix(app_name);
		let stdout_renderer = Self::choose_default_renderer(&stdout, &environment_prefix)
			.ok_or(LisaError::NoRendererFound)?;
		let stderr_renderer = Self::choose_default_renderer(&stderr, &environment_prefix)
			.ok_or(LisaError::NoRendererFound)?;

		let (log_messages, log_receiver) = bounded_channel(LOG_CHANNEL_SIZE);
		let (flush_sender, flush_receiver) = bounded_channel(1);
		let (flush_completed_sender, flush_completed_receiver) = bounded_channel(1);
		let (stop_tick_sender, stop_tick_receiver) = bounded_channel(1);

		let state = Arc::new(Mutex::new(UnlockedRendererState::new(
			app_name,
			&environment_prefix,
			(stdout, stderr),
			(stdout_renderer, stderr_renderer),
			log_receiver,
		)));
		Self::spawn_tick_task(
			flush_completed_sender,
			flush_receiver,
			stop_tick_receiver,
			state.clone(),
		)?;

		Ok(Self {
			did_do_flush: AsyncMutex::new(flush_completed_receiver),
			flush_sender,
			log_messages,
			state,
			stop_tick_task: stop_tick_sender,
		})
	}

	/// Create a new console outputting to specific places, with specific
	/// renderers.
	///
	/// It is up to the caller to inherit all user preferences for the renderers.
	///
	/// ## Errors
	///
	/// If we cannot spawn a task to tick along the console.
	pub fn new_with_outputs_and_preselected_renderers(
		app_name: &'static str,
		stdout: StdoutTy,
		stderr: StderrTy,
		stdout_renderer: Box<dyn ConsoleRenderer>,
		stderr_renderer: Box<dyn ConsoleRenderer>,
	) -> Result<Self, LisaError> {
		let environment_prefix = app_name_to_prefix(app_name);
		let (log_messages, log_receiver) = bounded_channel(LOG_CHANNEL_SIZE);
		let (flush_sender, flush_receiver) = bounded_channel(1);
		let (flush_completed_sender, flush_completed_receiver) = bounded_channel(1);
		let (stop_tick_sender, stop_tick_receiver) = bounded_channel(1);

		let state = Arc::new(Mutex::new(UnlockedRendererState::new(
			app_name,
			&environment_prefix,
			(stdout, stderr),
			(stdout_renderer, stderr_renderer),
			log_receiver,
		)));
		Self::spawn_tick_task(
			flush_completed_sender,
			flush_receiver,
			stop_tick_receiver,
			state.clone(),
		)?;

		Ok(Self {
			did_do_flush: AsyncMutex::new(flush_completed_receiver),
			flush_sender,
			log_messages,
			state,
			stop_tick_task: stop_tick_sender,
		})
	}

	/// Request this console immediately working on flushing it's contents.
	///
	/// THIS WILL NOT RETURN UNTIL THE FLUSH HAS BEEN COMPLETED.
	pub async fn flush(&self) {
		let mut did_do_flush_lock = self.did_do_flush.lock().await;
		_ = self.flush_sender.send(()).await;
		_ = did_do_flush_lock.recv().await;
	}

	/// Get the current render state.
	///
	/// *NOTE: WHILE HOLDING TO THIS YOU WILL BE LOCKING LOGS FROM RENDERING*.
	pub fn get_render_state(
		&self,
	) -> MutexGuard<'_, RawMutex, UnlockedRendererState<StdoutTy, StderrTy>> {
		self.state.lock()
	}

	/// Set the current input provider.
	pub fn set_input_provider<Ty: InputProvider + Sized + 'static>(&self, provider: Ty) {
		self.state.lock().set_input_provider(Box::new(provider));
	}

	/// Set the current event log task provider.
	pub fn set_task_provider<Ty: TaskEventLogProvider + Sized + 'static>(&self, provider: Ty) {
		self.state.lock().set_task_provider(Box::new(provider));
	}

	/// Set a channel to receive inputs on rather than needing to call
	/// [`Self::get_unprocessed_inputs`].
	pub fn set_input_channel(&self, channel: BoundedSender<String>) {
		self.state.lock().set_completed_input_channel(channel);
	}

	/// Mark the current input as active.
	///
	/// ## Errors
	///
	/// If the input provider errors trying to be marked as active.
	pub fn set_input_active(&self, active: bool) -> Result<(), LisaError> {
		self.state.lock().set_input_active(active)
	}

	/// Get a series of unprocessed inputs from the input provider.
	///
	/// In general prefer using [`Self::set_input_channel`] which gives you a
	/// channel you can poll for inputs with locking this like with poll for
	/// inputs, and rendering.
	pub fn get_unprocessed_inputs(&self) -> Vec<String> {
		self.state.lock().get_unprocessed_inputs()
	}

	/// Look at all the default renderers, and return whichever one is
	/// compatible if any are.
	#[must_use]
	pub fn choose_default_renderer(
		features: &dyn ConsoleOutputFeatures,
		environment_prefix: &str,
	) -> Option<Box<dyn ConsoleRenderer>> {
		let color = ColorConsoleRenderer::new();
		if color.should_use_renderer(features, environment_prefix) {
			return Some(Box::new(color));
		}
		std::mem::drop(color);

		let json = JSONConsoleRenderer::new();
		if json.should_use_renderer(features, environment_prefix) {
			return Some(Box::new(json));
		}
		std::mem::drop(json);

		let text = TextConsoleRenderer::new();
		if text.should_use_renderer(features, environment_prefix) {
			return Some(Box::new(text));
		}
		std::mem::drop(text);

		None
	}

	/// Cross OS wrapper for getting the current terminal height & width.
	///
	/// This backs off of `termios` on many non-windows OS, and then
	/// `GetConsoleScreenBufferInfo` on windows. This will look at standard
	/// in file descriptor (as standard out/standard error can be individually
	/// redirected).
	#[allow(
		// Dependent on OS...
		unreachable_code,
	)]
	#[must_use]
	pub fn terminal_height_and_width() -> Option<(u16, u16)> {
		#[cfg(any(
			target_os = "aix",
			target_os = "linux",
			target_os = "android",
			target_os = "macos",
			target_os = "ios",
			target_os = "freebsd",
			target_os = "openbsd",
			target_os = "netbsd",
			target_os = "dragonfly",
			target_os = "solaris",
			target_os = "illumos",
			target_os = "haiku",
		))]
		{
			use crate::termios::tcgetwinsize;
			let winsize = tcgetwinsize(0).ok()?;
			return Some((winsize.ws_row, winsize.ws_col));
		}

		#[cfg(target_os = "windows")]
		{
			use windows::Win32::System::Console::{
				CONSOLE_SCREEN_BUFFER_INFO, GetConsoleScreenBufferInfo, GetStdHandle,
				STD_INPUT_HANDLE,
			};

			let mut buffer_info = CONSOLE_SCREEN_BUFFER_INFO::default();
			let handle = unsafe { GetStdHandle(STD_INPUT_HANDLE) }.ok()?;
			unsafe { GetConsoleScreenBufferInfo(handle, &raw mut buffer_info).ok()? };
			return Some((
				u16::try_from(buffer_info.dwSize.Y).unwrap_or(u16::MIN),
				u16::try_from(buffer_info.dwSize.X).unwrap_or(u16::MIN),
			));
		}

		None
	}

	/// Cross OS wrapper for getting the current terminal height.
	///
	/// This backs off of `termios` on many non-windows OS, and then
	/// `GetConsoleScreenBufferInfo` on windows. This will look at standard
	/// in file descriptor (as standard out/standard error can be individually
	/// redirected).
	#[must_use]
	pub fn terminal_height() -> Option<u16> {
		Self::terminal_height_and_width().map(|tuple| tuple.0)
	}

	/// Cross OS wrapper for getting the current terminal width.
	///
	/// This backs off of `termios` on many non-windows OS, and then
	/// `GetConsoleScreenBufferInfo` on windows. This will look at standard
	/// in file descriptor (as standard out/standard error can be individually
	/// redirected).
	#[must_use]
	pub fn terminal_width() -> Option<u16> {
		Self::terminal_height_and_width().map(|tuple| tuple.1)
	}

	/// The function that is used to actually queue a log message.
	///
	/// This is what gets called by tracing and queues a message to be
	/// rendered. Called when a tokio runtime _does_ exist on the thread.
	pub(crate) async fn log(&self, log_message: SuperConsoleLogMessage) {
		_ = self.log_messages.send(log_message).await;
	}

	/// The function that is used to actually queue a log message.
	///
	/// This is what gets called by tracing and queues a message to be rendered,
	/// when a tokio runtime is not present on the thread.
	pub(crate) async fn log_sync(&self, log_message: SuperConsoleLogMessage) {
		_ = self.log_messages.send(log_message).await;
	}

	fn spawn_tick_task(
		flush_completed_sender: BoundedSender<()>,
		mut flush_recveiver: BoundedReceiver<()>,
		mut receiver: BoundedReceiver<()>,
		state: Arc<Mutex<UnlockedRendererState<StdoutTy, StderrTy>>>,
	) -> Result<(), LisaError> {
		TaskBuilder::new()
			.name("lisa::display::SuperConsole::tick")
			.spawn(async move {
				loop {
					let mut flush_queued = false;

					tokio::select! {
						() = sleep(Duration::from_millis(12)) => {}
						_ = flush_recveiver.recv() => {
							flush_queued = true;
						}
						_ = receiver.recv() => {
							break;
						}
						_ = ctrl_c() => {
							break;
						}
					}

					_ = state.lock().render_if_needed();
					if flush_queued {
						_ = flush_completed_sender.send(()).await;
					}
				}
			})?;

		Ok(())
	}
}

impl<
	StdoutTy: ConsoleOutputFeatures + IoWrite + Send,
	StderrTy: ConsoleOutputFeatures + IoWrite + Send,
> Drop for SuperConsole<StdoutTy, StderrTy>
{
	fn drop(&mut self) {
		let cloned_flush_sender = self.flush_sender.clone();
		let cloned_stop_tick_task = self.stop_tick_task.clone();

		_ = TaskBuilder::new()
			.name("lisa::display::SuperConsole::flush_drop")
			.spawn(async move {
				_ = cloned_flush_sender.send(()).await;
				_ = cloned_stop_tick_task.send(()).await;
			});
	}
}

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

	#[test]
	pub fn is_send_sync() {
		fn accepts_send_sync<Ty: Send + Sync>() {}

		accepts_send_sync::<SuperConsole<Stdout, Stderr>>();
	}

	#[test]
	pub fn term_size_matches_terminal_size_crate() {
		assert_eq!(
			SuperConsole::<Stdout, Stderr>::terminal_width(),
			terminal_size::terminal_size().map(|item| item.0.0),
			"{:?} != {:?}, (us == term_size) [WIDTH]",
			SuperConsole::<Stdout, Stderr>::terminal_width()
				.expect("Failed to query terminal width"),
			terminal_size::terminal_size().map(|item| item.0.0)
		);

		assert_eq!(
			SuperConsole::<Stdout, Stderr>::terminal_height(),
			terminal_size::terminal_size().map(|item| item.1.0),
			"{:?} != {:?}, (us == term_size) [HEIGHT]",
			SuperConsole::<Stdout, Stderr>::terminal_width()
				.expect("Failed to query terminal height"),
			terminal_size::terminal_size().map(|item| item.1.0)
		);
	}
}