mame_parser/core/models/
callback_progress.rs

1use crate::core::models::mame_data_types::MameDataType;
2use std::sync::Arc;
3
4/// Represents the type of callback being invoked during an operation.
5///
6/// The `CallbackType` enum is used to categorize the nature of the callback, allowing the caller
7/// to differentiate between informational messages, progress updates, and errors. This is particularly
8/// useful in scenarios where different types of feedback need to be handled in distinct ways.
9///
10/// # Variants
11/// - `Info`: Indicates a general informational message, such as status updates or non-critical notifications.
12/// - `Progress`: Indicates that the callback is providing progress updates, typically involving downloaded bytes or percentages.
13/// - `Finish`: Indicates that an operation has completed successfully, providing a final status message.
14/// - `Error`: Indicates that an error has occurred and provides details related to the issue.
15///
16#[derive(Debug)]
17pub enum CallbackType {
18    /// Conveys a general informational message.
19    Info,
20    /// Indicates that progress information is being reported (e.g., download progress).
21    Progress,
22    /// Indicates that an operation has finished successfully.
23    Finish,
24    /// Signals that an error has occurred and provides error details.
25    Error,
26}
27
28/// Represents information about the progress of an ongoing operation.
29///
30/// This struct is used to convey the current state of progress, including the amount of work completed,
31/// the total amount of work, a message describing the current status, and the type of progress update
32/// being reported.
33///
34/// # Fields
35/// - `progress`: A `u64` representing the current progress value or the amount of work completed so far.
36/// - `total`: A `u64` representing the total progress value or the total amount of work expected.
37/// - `message`: A `String` containing a message associated with the progress update, typically used for
38///   providing additional information or context about the current operation.
39/// - `callback_type`: An enum of type `CallbackType` that indicates the nature of the progress update, such as
40///   `CallbackType::Progress`, `CallbackType::Info`, `CallbackType::Finish`, or `CallbackType::Error`.
41///
42/// # Usage
43/// `ProgressInfo` is typically used in callback functions to report the status of an operation in real-time,
44/// allowing the caller to monitor progress, handle errors, or perform additional actions based on the state
45/// of the ongoing process.
46pub struct ProgressInfo {
47    /// The current progress value.
48    pub progress: u64,
49    /// The total progress value.
50    pub total: u64,
51    /// The message associated with the progress update.
52    pub message: String,
53    /// The type of callback being invoked.
54    pub callback_type: CallbackType,
55}
56
57/// Type alias for a progress callback function used to report progress updates during long-running operations.
58///
59/// `ProgressCallback` is a boxed function trait object that accepts a `ProgressInfo` struct and is used to provide
60/// real-time updates on the status of an ongoing operation. It allows monitoring progress, handling errors, or
61/// executing additional actions based on the state of the process.
62///
63/// # Type
64/// `ProgressCallback` is defined as:
65/// ```text
66/// Box<dyn Fn(ProgressInfo) + Send + 'static>
67/// ```
68///
69/// - `ProgressInfo`: The struct containing details about the progress of the operation (current progress, total, message, callback type).
70/// - `Send`: Ensures that the callback can be safely transferred across thread boundaries.
71/// - `'static`: Indicates that the callback does not contain any non-static references, making it suitable for long-lived operations.
72///
73/// # Usage
74/// This type is typically used in functions that perform asynchronous or lengthy tasks (like downloading or unpacking files)
75/// and need to provide progress feedback to the caller. The callback function can be customized to handle different types of progress updates.
76pub type ProgressCallback = Box<dyn Fn(ProgressInfo) + Send + 'static>;
77
78/// Type alias for a shared progress callback function used to report progress updates across multiple threads.
79///
80/// `SharedProgressCallback` is a thread-safe, reference-counted function trait object that accepts a `MameDataType`
81/// and a `ProgressInfo` struct. It is designed to provide real-time updates on the status of an ongoing operation
82/// from multiple threads, allowing concurrent tasks to share a single callback for progress reporting.
83///
84/// # Type
85/// `SharedProgressCallback` is defined as:
86/// ```text
87/// Arc<dyn Fn(MameDataType, ProgressInfo) + Send + Sync + 'static>
88/// ```
89///
90/// - `MameDataType`: An enum indicating the type of MAME data being processed (e.g., ROMs, DAT files).
91/// - `ProgressInfo`: A struct containing details about the progress of the operation (current progress, total, message, callback type).
92/// - `Send`: Ensures that the callback can be safely transferred across thread boundaries.
93/// - `Sync`: Ensures that the callback can be safely shared and called from multiple threads simultaneously.
94/// - `'static`: Indicates that the callback does not contain any non-static references, making it suitable for long-lived and shared operations.
95///
96/// # Usage
97/// This type is typically used in scenarios where multiple threads perform concurrent tasks (like unpacking or downloading files),
98/// and a single, shared callback is needed to handle progress updates. The `Arc` wrapper allows multiple ownership of the callback,
99/// ensuring it remains valid and accessible across all threads involved in the operation.
100pub type SharedProgressCallback = Arc<dyn Fn(MameDataType, ProgressInfo) + Send + Sync + 'static>;
mame_parser/core/models/callback_progress.rs

mame_parser/core/models/
callback_progress.rs
