carbon_core/
processor.rs

1//! Defines the `Processor` trait for processing data within the `carbon-core`
2//! pipeline.
3//!
4//! The `Processor` trait provides a standardized interface for handling various
5//! types of data within the processing pipeline. It includes asynchronous
6//! processing capabilities and supports metric tracking, enabling real-time
7//! insights into the performance of individual processing stages.
8//!
9//! ## Key Concepts
10//!
11//! - **Processor**: A trait that defines a single method, `process`, which
12//!   asynchronously handles data of a specified type. This allows different
13//!   stages of the pipeline to implement custom data handling logic.
14//! - **Metrics**: Metrics are collected during processing, offering visibility
15//!   into processing duration, success, failure rates, and other relevant
16//!   statistics.
17//!
18//! ## Usage
19//!
20//! Implement the `Processor` trait for any type that needs to handle specific
21//! data in the pipeline. The trait allows you to define how data of a given
22//! type is processed asynchronously, with the option to record metrics for
23//! performance monitoring.
24//!
25//! ## Trait Definition
26//!
27//! ### Required Methods
28//!
29//! - `process`: Handles processing of the specified data type. This method is
30//!   asynchronous and should be implemented to define how data should be
31//!   processed in your specific use case.
32//!
33//! ## Parameters
34//!
35//! - `data`: An instance of the type specified by `InputType`. This represents
36//!   the data to be processed.
37//! - `metrics`: A vector of `Metrics` objects, allowing you to update and track
38//!   various performance metrics.
39//!
40//! ## Returns
41//!
42//! The `process` method returns a `CarbonResult<()>`, which indicates either
43//! successful processing (`Ok(())`) or an error.
44//!
45//! ## Notes
46//!
47//! - This trait uses `async_trait` to enable asynchronous processing. Ensure
48//!   your runtime environment supports asynchronous execution, such as a Tokio
49//!   runtime, to fully utilize this trait.
50//! - When implementing the `process` method, consider which metrics are
51//!   relevant to your data processing, and update those metrics accordingly to
52//!   enable monitoring and alerting on key performance indicators.
53
54use {
55    crate::{error::CarbonResult, metrics::MetricsCollection},
56    async_trait::async_trait,
57    std::sync::Arc,
58};
59
60/// A trait for defining asynchronous data processing within the pipeline.
61///
62/// The `Processor` trait provides a single asynchronous method, `process`,
63/// which is responsible for handling data of a specific type (`InputType`).
64/// This trait is designed to be implemented by types that need to process data
65/// within the pipeline, allowing for customized handling of different data
66/// types.
67///
68/// # Type Parameters
69///
70/// - `InputType`: The type of data that this processor will handle. This can
71///   represent a variety of data structures depending on the application’s
72///   specific needs.
73///
74/// # Required Methods
75///
76/// - `process`: Processes the specified `InputType` data asynchronously,
77///   optionally updating associated metrics.
78///
79/// # Example
80///
81/// ```ignore
82/// use async_trait::async_trait;
83/// use carbon_core::error::CarbonResult;
84/// use carbon_core::metrics::MetricsCollection;
85/// use carbon_core::processor::Processor;
86/// use std::sync::Arc;
87///
88/// struct CustomProcessor;
89///
90/// #[async_trait]
91/// impl Processor for CustomProcessor {
92///     type InputType = DataType;
93///
94///     async fn process(
95///         &mut self,
96///         data: Self::InputType,
97///         metrics: Arc<MetricsCollection>,
98///     ) -> CarbonResult<()> {
99///         // Perform data processing logic
100///
101///         // Optionally, update metrics
102///         for metric in &metrics {
103///             metric.increment_counter("processed_items", 1).await?;
104///         }
105///
106///         Ok(())
107///     }
108/// }
109/// ```
110#[async_trait]
111pub trait Processor {
112    type InputType;
113
114    async fn process(
115        &mut self,
116        data: Self::InputType,
117        metrics: Arc<MetricsCollection>,
118    ) -> CarbonResult<()>;
119}
carbon_core/processor.rs

carbon_core/
processor.rs
