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
// Licensed under the Apache License, Version 2.0 or the MIT License.
// SPDX-License-Identifier: Apache-2.0 OR MIT
// Copyright Tock Contributors 2022.
//! Tools for displaying process state.
use crate::process::Process;
use crate::utilities::binary_write::BinaryWrite;
/// A context token that the caller must pass back to us. This allows us to
/// track where we are in the print operation.
#[derive(PartialEq, Eq, Copy, Clone)]
pub struct ProcessPrinterContext {
/// The overall print message is broken in to chunks so that it can be fit
/// in a small buffer that is called multiple times. This tracks which byte
/// we are at so we can ignore the text before and print the next bytes.
pub offset: usize,
}
/// Trait for creating a custom "process printer" that formats process state in
/// some sort of presentable format.
///
/// Typically, implementations will display process state in a text UI over some
/// sort of terminal.
///
/// This trait also allows for experimenting with different process display
/// formats. For example, some use cases might want more or less detail, or to
/// encode the process state in some sort of binary format that can be expanded
/// into a human readable format later. Other cases might want to log process
/// state to nonvolatile storage rather than display it immediately.
pub trait ProcessPrinter {
/// Print a process overview to the `writer`. As `print_overview()` uses a
/// `&dyn` [`Process`] to access the process, only state which can be
/// accessed via the [`Process`] trait can be printed.
///
/// This is a synchronous function which also supports asynchronous
/// operation. This function does not issue a callback, but the return value
/// indicates whether the caller should call `print_overview()` again (after
/// the underlying write operation finishes). This allows asynchronous
/// implementations to still use `print_overview()`, while still supporting
/// the panic handler which runs synchronously.
///
/// When `print_overview()` is called the first time `None` should be passed
/// in for `context`.
///
/// ### Return Value
///
/// The return indicates whether `print_overview()` has more printing to do
/// and should be called again. If `print_overview()` returns `Some()` then
/// the caller should call `print_overview()` again (providing the returned
/// [`ProcessPrinterContext`] as the `context` argument) once the `writer`
/// is ready to accept more data. If `print_overview()` returns `None`, the
/// `writer` indicated it accepted all output and the caller does not need
/// to call `print_overview()` again to finish the printing.
fn print_overview(
&self,
process: &dyn Process,
writer: &mut dyn BinaryWrite,
context: Option<ProcessPrinterContext>,
) -> Option<ProcessPrinterContext>;
}