diff --git a/tooling/pipeline/includes/biergarten_data_generator.h b/tooling/pipeline/includes/biergarten_data_generator.h index 34d7ac3..573df8a 100644 --- a/tooling/pipeline/includes/biergarten_data_generator.h +++ b/tooling/pipeline/includes/biergarten_data_generator.h @@ -2,8 +2,11 @@ #define BIERGARTEN_PIPELINE_INCLUDES_BIERGARTEN_DATA_GENERATOR_H_ /** - * @file biergarten_pipeline_orchestrator.h - * @brief Core orchestration class for pipeline data generation. + * @file biergarten_data_generator.h + * @brief Orchestration for end-to-end brewery data generation pipeline. + * + * Intent: Coordinates location loading, enrichment, and generation phases + * to produce a complete dataset. Coordinates dependencies via composition root. */ #include @@ -23,13 +26,14 @@ */ class BiergartenPipelineOrchestrator { public: - /** - * @brief Construct a BiergartenDataGenerator with injected dependencies. - * - * @param context_service Context provider for sampled locations. - * @param generator Brewery and user data generator. - * @param exporter Storage backend for generated brewery data. - */ +/** + * @brief Constructs the orchestrator with injected pipeline dependencies. + * + * @param context_service Provides regional context for locations. + * @param generator Implementation (Llama or Mock) for brewery/user generation. + * @param exporter Database backend for persisting generated records. + * @param application_options CLI configuration and paths. + */ BiergartenPipelineOrchestrator( std::unique_ptr context_service, std::unique_ptr generator, @@ -55,10 +59,11 @@ class BiergartenPipelineOrchestrator { /// @brief Generator dependency selected in the composition root. std::unique_ptr generator_; - /// @brief Storage backend for generated brewery records. - std::unique_ptr exporter_; + /// @brief Storage backend for generated brewery records. + std::unique_ptr exporter_; - ApplicationOptions application_options_; + /// @brief CLI configuration: paths, model settings, generation parameters. + ApplicationOptions application_options_; /** * @brief Load locations from JSON and sample cities. diff --git a/tooling/pipeline/includes/concurrency/bounded_channel.h b/tooling/pipeline/includes/concurrency/bounded_channel.h index 8e31031..ff4fdc2 100644 --- a/tooling/pipeline/includes/concurrency/bounded_channel.h +++ b/tooling/pipeline/includes/concurrency/bounded_channel.h @@ -1,7 +1,3 @@ -// -// Created by aaronpo on 29/04/2026. -// - #ifndef BIERGARTEN_PIPELINE_INCLUDES_CONCURRENCY_BOUNDED_CHANNEL_H_ #define BIERGARTEN_PIPELINE_INCLUDES_CONCURRENCY_BOUNDED_CHANNEL_H_ @@ -13,17 +9,19 @@ /** * @file bounded_channel.h - * @brief A thread-safe, bounded multi-producer/multi-consumer channel. + * @brief Thread-safe, bounded multi-producer/multi-consumer synchronous channel. + * + * Intent: Enables asynchronous inter-thread communication with backpressure. + * Models a synchronous channel where producers/consumers block on capacity limits. */ -// --------------------------------------------------------------------------- -// BoundedChannel -// -// Models a synchronous channel with a fixed-capacity internal buffer. -// Producers block when the buffer is full (backpressure). -// Consumers block when the buffer be empty. -// Calling close() unblocks all waiting threads and signals exhaustion. -// --------------------------------------------------------------------------- +/** + * @class BoundedChannel + * @brief MPMC channel with fixed capacity and blocking semantics. + * + * Producers block when buffer is full; consumers block when empty. + * Close() unblocks all waiters and signals channel exhaustion. + */ template class BoundedChannel { // ------------------------------------------------------------------------- diff --git a/tooling/pipeline/includes/services/logging/channel_logger.h b/tooling/pipeline/includes/services/logging/channel_logger.h index 8968904..d2b5bfa 100644 --- a/tooling/pipeline/includes/services/logging/channel_logger.h +++ b/tooling/pipeline/includes/services/logging/channel_logger.h @@ -1,10 +1,9 @@ /** * @file services/logging/channel_logger.h - * @brief Channel-backed implementation of the Logger interface. + * @brief Channel-backed producer for asynchronous pipeline logging. * - * ChannelLogger constructs LogEntry values and forwards them to a - * BoundedChannel for asynchronous consumption by LogConsumer. - * The channel is injected by reference; ChannelLogger does not own it. + * Intent: Decouple logging from synchronous I/O by forwarding entries to a + * bounded channel. LogConsumer drains the channel on a dedicated thread. */ #ifndef BIERGARTEN_PIPELINE_INCLUDES_SERVICES_LOGGING_CHANNEL_LOGGER_H_ @@ -16,22 +15,40 @@ #include "services/logging/log_entry.h" #include "services/logging/logger.h" +/** + * @class ChannelLogger + * @brief ILogger implementation that sends entries to a BoundedChannel. + * + * Non-copyable, non-movable. Holds a non-owning reference to the channel. + */ class ChannelLogger final : public ILogger { public: - explicit ChannelLogger(BoundedChannel& channel); + /** + * @brief Construct a channel-backed logger. + * + * @param channel Reference to bounded channel for log entry transfer. + * Channel must outlive this logger instance. + */ + explicit ChannelLogger(BoundedChannel& channel); - ChannelLogger(const ChannelLogger&) = delete; - ChannelLogger& operator=(const ChannelLogger&) = delete; - ChannelLogger(ChannelLogger&&) = delete; - ChannelLogger& operator=(ChannelLogger&&) = delete; + ChannelLogger(const ChannelLogger&) = delete; + ChannelLogger& operator=(const ChannelLogger&) = delete; + ChannelLogger(ChannelLogger&&) = delete; + ChannelLogger& operator=(ChannelLogger&&) = delete; - ~ChannelLogger() override = default; + ~ChannelLogger() override = default; - void Log(LogLevel level, PipelinePhase phase, - std::string_view message) override; + /** + * @brief Queue a log entry for asynchronous processing. + * + * Blocks if the channel is full (backpressure). Returns immediately + * if the channel is closed. + */ + void Log(LogLevel level, PipelinePhase phase, + std::string_view message) override; private: - BoundedChannel& channel_; + BoundedChannel& channel_; }; #endif // BIERGARTEN_PIPELINE_INCLUDES_SERVICES_LOGGING_CHANNEL_LOGGER_H_ diff --git a/tooling/pipeline/includes/services/logging/log_consumer.h b/tooling/pipeline/includes/services/logging/log_consumer.h index 20c26b6..1865e1e 100644 --- a/tooling/pipeline/includes/services/logging/log_consumer.h +++ b/tooling/pipeline/includes/services/logging/log_consumer.h @@ -1,10 +1,10 @@ /** * @file services/logging/log_consumer.h - * @brief Dedicated log drain worker for the pipeline logging channel. + * @brief Dedicated log consumer/drain for asynchronous pipeline logging. * - * LogConsumer runs on its own thread, draining LogEntry items from a - * BoundedChannel and forwarding them to spdlog. Exits cleanly - * when the channel is closed. + * Intent: Dequeue LogEntry values from a BoundedChannel on a dedicated thread + * and forward them to spdlog for I/O and formatting. Decouples application + * logic from logging latency. */ #ifndef BIERGARTEN_PIPELINE_INCLUDES_SERVICES_LOGGING_LOG_CONSUMER_H_ @@ -17,28 +17,43 @@ #include "concurrency/bounded_channel.h" #include "services/logging/log_entry.h" +/** + * @class LogConsumer + * @brief Consumes log entries from channel and forwards to spdlog. + * + * Non-copyable, non-movable. Designed to run on its own dedicated std::thread. + * Drains the channel until closure, then exits cleanly. + */ class LogConsumer { public: - explicit LogConsumer(BoundedChannel& channel); + /** + * @brief Construct a log consumer. + * + * @param channel Reference to bounded channel for log entry retrieval. + * Channel must outlive this consumer instance. + */ + explicit LogConsumer(BoundedChannel& channel); - LogConsumer(const LogConsumer&) = delete; - LogConsumer& operator=(const LogConsumer&) = delete; - LogConsumer(LogConsumer&&) = delete; - LogConsumer& operator=(LogConsumer&&) = delete; + LogConsumer(const LogConsumer&) = delete; + LogConsumer& operator=(const LogConsumer&) = delete; + LogConsumer(LogConsumer&&) = delete; + LogConsumer& operator=(LogConsumer&&) = delete; - /** - * @brief Drains the channel until it is closed. - * - * Intended to be run on a dedicated std::thread. Exits when: - * - The channel is closed and the queue is fully drained. - */ - void Run(); + /** + * @brief Main loop: drain channel and forward entries to spdlog. + * + * Intended to be called once on a dedicated thread. Returns when: + * - Channel is closed AND all queued entries are drained. + * + * Thread-safe for use from multiple ChannelLogger instances on other threads. + */ + void Run(); private: - BoundedChannel& channel_; + BoundedChannel& channel_; - static spdlog::level::level_enum ToSpdlogLevel(LogLevel level); - static std::string ToString(PipelinePhase phase); + static spdlog::level::level_enum ToSpdlogLevel(LogLevel level); + static std::string ToString(PipelinePhase phase); }; #endif // BIERGARTEN_PIPELINE_INCLUDES_SERVICES_LOGGING_LOG_CONSUMER_H_ diff --git a/tooling/pipeline/includes/services/logging/log_entry.h b/tooling/pipeline/includes/services/logging/log_entry.h index 38416ac..5b47677 100644 --- a/tooling/pipeline/includes/services/logging/log_entry.h +++ b/tooling/pipeline/includes/services/logging/log_entry.h @@ -1,10 +1,9 @@ /** * @file services/logging/log_entry.h - * @brief POD struct representing a single log event in the pipeline. + * @brief POD log entry structure for asynchronous pipeline logging. * - * LogEntry is produced by PipelineLogger and consumed by LogWorker via - * BoundedChannel. All fields are value types so entries are - * safely movable across the channel without shared ownership. + * Intent: Lightweight, move-safe data transfer between logging producer + * (ChannelLogger) and consumer (LogConsumer) via BoundedChannel. */ #ifndef BIERGARTEN_PIPELINE_INCLUDES_SERVICES_LOGGING_LOG_ENTRY_H_ @@ -13,29 +12,54 @@ #include #include +/** + * @enum LogLevel + * @brief Severity levels for log entries. + */ enum class LogLevel { - Debug, - Info, - Warn, - Error, + Debug, ///< Development/debugging information. + Info, ///< General informational messages. + Warn, ///< Warning conditions. + Error, ///< Error conditions. }; +/** + * @enum PipelinePhase + * @brief Execution phases for contextual logging. + * + * Used to tag log entries by their processing stage, enabling phase-specific + * analysis and filtering of the execution timeline. + */ enum class PipelinePhase { - Startup, - UserGeneration, - BreweryAndBeerGeneration, - CheckinGeneration, - RatingGeneration, - FollowGeneration, - Teardown, + Startup, ///< Initialization and validation. + UserGeneration, ///< User profile generation. + BreweryAndBeerGeneration, ///< Brewery and beer data generation. + CheckinGeneration, ///< Checkin (visit) record generation. + RatingGeneration, ///< Rating and review generation. + FollowGeneration, ///< Follow relationship generation. + Teardown, ///< Finalization and cleanup. }; +/** + * @struct LogEntry + * @brief Single log event for asynchronous processing. + * + * All fields are value types, allowing safe move semantics across + * BoundedChannel without shared ownership or synchronization overhead. + */ struct LogEntry { - std::chrono::system_clock::time_point timestamp = - std::chrono::system_clock::now(); - LogLevel level; - PipelinePhase phase; - std::string message; + /// @brief Timestamp when entry was created. + std::chrono::system_clock::time_point timestamp = + std::chrono::system_clock::now(); + + /// @brief Severity level of this entry. + LogLevel level; + + /// @brief Pipeline phase when entry was logged. + PipelinePhase phase; + + /// @brief Log message text. + std::string message; }; #endif // BIERGARTEN_PIPELINE_INCLUDES_SERVICES_LOGGING_LOG_ENTRY_H_ \ No newline at end of file diff --git a/tooling/pipeline/includes/services/logging/logger.h b/tooling/pipeline/includes/services/logging/logger.h index 6e54ae2..71a61e8 100644 --- a/tooling/pipeline/includes/services/logging/logger.h +++ b/tooling/pipeline/includes/services/logging/logger.h @@ -1,9 +1,9 @@ /** * @file services/logging/logger.h - * @brief Abstract interface for pipeline logging. + * @brief Abstract logging interface for pipeline components. * - * Kept intentionally narrow. Components that need to log depend on Logger, - * not on PipelineLogger or any channel type. + * Intent: Decouple logging from channel/worker implementation details. + * All pipeline components depend on ILogger, enabling swappable backends. */ #ifndef BIERGARTEN_PIPELINE_INCLUDES_SERVICES_LOGGING_LOGGER_H_ @@ -15,17 +15,31 @@ #include "services/logging/log_entry.h" +/** + * @class ILogger + * @brief Minimal interface for submitting log entries. + * + * Non-copyable and non-movable. Implementations are typically short-lived, + * created and owned by the composition root. + */ class ILogger { public: - ILogger() = default; - ILogger(const ILogger&) = delete; - ILogger& operator=(const ILogger&) = delete; - ILogger(ILogger&&) = delete; - ILogger& operator=(ILogger&&) = delete; - virtual ~ILogger() = default; + ILogger() = default; + ILogger(const ILogger&) = delete; + ILogger& operator=(const ILogger&) = delete; + ILogger(ILogger&&) = delete; + ILogger& operator=(ILogger&&) = delete; + virtual ~ILogger() = default; - virtual void Log(LogLevel level, PipelinePhase phase, - std::string_view message) = 0; + /** + * @brief Submit a log entry to the logging subsystem. + * + * @param level Log level (Debug, Info, Warn, Error). + * @param phase Pipeline execution phase (Startup, Generation, Teardown, etc.). + * @param message Log message text. + */ + virtual void Log(LogLevel level, PipelinePhase phase, + std::string_view message) = 0; }; #endif // BIERGARTEN_PIPELINE_INCLUDES_SERVICES_LOGGING_LOGGER_H_