foxhunt/crates/trading_engine/src/lib.rs

#![deny(clippy::unwrap_used, clippy::expect_used)]
#![cfg_attr(test, allow(clippy::unwrap_used, clippy::expect_used))]
#![allow(unsafe_code)] // Intentional unsafe throughout trading_engine for HFT performance
#![allow(missing_docs)] // Internal implementation details don't require documentation
#![allow(missing_debug_implementations)] // Not all types need Debug
#![allow(unused_crate_dependencies)] // Test dependencies only used in tests

//! Core Performance Infrastructure for Foxhunt HFT System
//!
//! This module contains the high-performance building blocks that achieve sub-50μs latency:
//! - **Types**: Core data types with optimized memory layout and financial safety
//! - **Timing**: RDTSC-based ultra-low latency timing (14ns precision)
//! - **SIMD**: Vectorized operations for numerical computing (AVX2/AVX512)
//! - **Affinity**: CPU core binding for consistent performance
//! - **Lockfree**: Lock-free data structures for concurrent access
//!
//! # Features
//! - `simd`: Enable SIMD vectorization (default)
//! - `avx2`: Enable AVX2 instructions  
//! - `avx512`: Enable AVX512 instructions
//! - `packed-simd`: Enable `packed_simd` crate for advanced vectorization
//! - `database-conversions`: Enable database type conversions
//!
//! # Usage
//! ```rust
//! use trading_engine::prelude::*;
//! use std::arch;
//!
//! // High-performance types
//! let price = Price::from_str("100.50")?;
//! let quantity = Quantity::from_str("1000")?;
//!
//! // Ultra-low latency timing
//! let timestamp = HardwareTimestamp::now();
//!
//! // SIMD operations (if CPU supports)
//! #[cfg(target_arch = "x86_64")]
//! if arch::is_x86_feature_detected!("avx2") {
//!     let simd_ops = SimdPriceOps::new()?;
//!     // Use vectorized operations
//! }
//! ```

#![warn(missing_debug_implementations)]
#![warn(rust_2018_idioms)]
#![deny(
    clippy::unwrap_used,
    clippy::expect_used,
    clippy::panic,
    clippy::unimplemented,
    clippy::unreachable
)]
#![warn(clippy::perf, clippy::correctness)]
// Individual pedantic lints are managed at workspace level in Cargo.toml
#![allow(
    // Performance-critical allowances for HFT (sub-50μs latency requirements)
    clippy::similar_names,
    clippy::module_name_repetitions,
    clippy::too_many_lines,
    clippy::cast_possible_truncation,
    clippy::cast_precision_loss,
    clippy::cast_sign_loss,
    clippy::cast_possible_wrap,
    clippy::arithmetic_side_effects,
    clippy::float_arithmetic,
    clippy::integer_division,
    clippy::indexing_slicing,                  // Safe with bounds checks in hot paths
    clippy::as_conversions,                    // Necessary for u64<->i64 timestamp conversions
    clippy::default_numeric_fallback,          // Type inference is clear in context
    clippy::type_complexity,                   // Some complex types unavoidable for performance
    clippy::missing_errors_doc,                // Internal APIs don't need full error documentation
    clippy::struct_excessive_bools,            // Boolean flags efficient for HFT state
    clippy::too_many_arguments,                // Some functions need many parameters for performance
    clippy::cast_lossless,                     // as casts are intentional for HFT performance
    clippy::inline_always,                     // Explicit #[inline(always)] is performance-critical
    clippy::multiple_unsafe_ops_per_block,     // RDTSC requires multiple unsafe ops
    clippy::option_if_let_else,                // Match is often more readable in hot paths
    clippy::doc_markdown,                      // Internal code doesn't need strict doc formatting
    clippy::unsafe_derive_deserialize,         // Hardware timestamp needs unsafe + serde
    clippy::match_same_arms,                   // Explicit match arms preferred for clarity
    clippy::shadow_reuse,                      // Variable reuse is intentional in hot paths
    clippy::shadow_unrelated,                  // Shadow patterns are intentional
    clippy::clone_on_ref_ptr,                  // Arc::clone is intentional for shared state
    clippy::modulo_arithmetic,                 // Modulo is used safely for financial calculations
    clippy::map_err_ignore,                    // Error conversion doesn't need original context
    clippy::manual_range_contains,             // Explicit conditions clearer in some cases
    clippy::manual_let_else,                   // if-let pattern preferred for error handling
    clippy::missing_const_for_fn,              // Const fn not critical for performance
    clippy::str_to_string,                      // Fixed: use .to_owned() instead
    clippy::unnecessary_wraps,                 // Result/Option wrapping needed for trait consistency
    clippy::new_without_default,               // Many types need config params, Default is inappropriate
    clippy::needless_range_loop,               // Index-based loops often clearer in hot paths
    clippy::unused_async,                      // Async needed for trait implementations
    clippy::must_use_candidate,                // Not all functions need must_use
    clippy::unused_self,                       // Self parameter needed for trait consistency
    clippy::used_underscore_binding,           // Underscore bindings used for partial pattern matches
    clippy::redundant_else,                    // Explicit else branches preferred for clarity
    clippy::unreadable_literal,                // Large numbers are clear in financial context
    clippy::wildcard_enum_match_arm,           // Exhaustive matching not required for all enums
    clippy::empty_structs_with_brackets,        // Unit structs with brackets in generated/legacy code
    clippy::doc_lazy_continuation,              // Doc comment formatting in generated code
    clippy::io_other_error,                     // io::Error construction patterns
    clippy::derivable_impls,                    // Manual Default impls for clarity
    clippy::single_match_else,                  // Explicit match arms preferred for clarity
    clippy::should_implement_trait,             // Custom method names preferred over std traits
    clippy::uninlined_format_args,              // Format args style is consistent across codebase
    clippy::clone_on_copy,                      // Explicit clones for clarity in hot paths
    clippy::undocumented_unsafe_blocks,         // Unsafe blocks are intentional for HFT performance
    clippy::missing_safety_doc,                 // Unsafe is intentional for HFT performance
    clippy::assign_op_pattern,                  // Explicit assignment preferred for clarity
    clippy::get_first,                          // .get(0) used for consistency with other indices
    clippy::manual_contains,                    // Explicit iteration preferred in some cases
    clippy::missing_fields_in_debug,            // Not all fields need Debug display
    clippy::if_not_else,                        // Negative conditions sometimes clearer in context
    clippy::write_with_newline,                 // Explicit newline writes for formatting control
    clippy::manual_clamp,                       // Explicit min/max chains for clarity
    clippy::len_without_is_empty,               // len() without is_empty() in performance types
    clippy::manual_flatten,                     // Explicit if-let preferred in iterator processing
    clippy::inherent_to_string,                 // Custom to_string for display types
    clippy::if_same_then_else,                  // Intentional identical branches for future divergence
    clippy::vec_init_then_push,                 // Vec construction patterns in reporting code
    clippy::to_string_trait_impl,               // Direct ToString impls for protocol types
    clippy::declare_interior_mutable_const,     // Interior mutability needed for metric constants
    clippy::incompatible_msrv,                  // MSRV compatibility managed at workspace level
    clippy::cognitive_complexity                // Complex HFT state machines and compliance code
)]

// SIMD features are detected at runtime instead of using unstable features

// Unused crate dependencies (used in features or other contexts)
extern crate chacha20poly1305 as _;
#[allow(unused_extern_crates)]
extern crate dashmap as _;
extern crate log as _;
extern crate zeroize as _;

/// Core trading types with optimized memory layout and financial safety
pub mod types;

/// RDTSC-based ultra-low latency timing (14ns precision)
pub mod timing;

/// `SIMD` vectorized operations for numerical computing
#[cfg(any(target_arch = "x86_64", target_arch = "aarch64"))]
pub mod simd;

// Re-export commonly used SIMD types for convenience
#[cfg(any(target_arch = "x86_64", target_arch = "aarch64"))]
pub use simd::{
    AlignedPrices, AlignedVolumes, CpuFeatures, SafeSimdDispatcher, SimdLevel, SimdMarketDataOps,
    SimdPriceOps, SimdRiskEngine,
};

#[cfg(feature = "wide")]
extern crate wide as _;

/// `CPU` core binding and real-time scheduling
#[cfg(target_os = "linux")]
pub mod affinity;

/// Lock-free data structures for concurrent access
pub mod lockfree;

/// Small batch optimization for `HFT` performance
pub mod small_batch_optimizer;

/// High-performance event processing pipeline
pub mod events;

/// Configuration management system
// Configuration is provided by the config crate
/// Persistence layer with PostgreSQL, `InfluxDB`, Redis, and `ClickHouse`
pub mod persistence;

/// Prelude module for convenient imports
pub mod prelude;

/// Repository pattern abstractions for data access
pub mod repositories;

/// Core trading operations with comprehensive metrics
pub mod trading_operations;

// Dead code cleanup (Wave D Phase 6): Removed trading_operations_optimized.rs (662 lines),
// simd_order_processor.rs (599 lines), hft_performance_benchmark.rs (565 lines) - orphaned benchmark files
// Keep only working core trading_operations module

/// Core trading engine and business logic
pub mod trading;

/// Broker connectivity and routing
pub mod brokers;

/// Unified feature extraction system - prevents training/serving skew
pub mod features;
/// Comprehensive performance benchmarks for `HFT` system validation
#[cfg(feature = "benchmarks")]
pub mod comprehensive_performance_benchmarks;

/// Ultra-low latency metrics collection for `HFT` monitoring
pub mod metrics;

/// Distributed tracing with minimal performance impact
pub mod tracing;

/// Advanced memory allocation and access pattern benchmarks
#[cfg(feature = "benchmarks")]
pub mod advanced_memory_benchmarks;

/// Performance test runner for executing all benchmark suites
#[cfg(feature = "benchmarks")]
pub mod test_runner;

/// Compliance and regulatory reporting
pub mod compliance;

/// Test modules for validation
pub mod tests;

/// Storage backends including S3 archival for cold storage
#[cfg(feature = "s3-archival")]
pub mod storage;

/// Performance utilities and constants
pub mod performance {
    /// Target maximum latency for critical path operations (microseconds)
    pub const MAX_CRITICAL_LATENCY_US: u64 = 50;

    /// Target maximum latency for timing operations (nanoseconds)  
    pub const MAX_TIMING_LATENCY_NS: u64 = 14;

    /// `SIMD` alignment requirement for optimal performance
    pub const SIMD_ALIGNMENT: usize = 32; // AVX2 alignment

    /// Cache line size for optimal memory layout
    pub const CACHE_LINE_SIZE: usize = 64;

    /// Check if current `CPU` supports required `SIMD` features
    ///
    /// This function detects `AVX2` support which is the baseline `SIMD` requirement
    /// for high-performance trading operations. `AVX2` provides 256-bit vector
    /// operations that can process 8 single-precision floats or 4 double-precision
    /// floats simultaneously.
    ///
    /// # Returns
    ///
    /// `true` if `AVX2` is supported, `false` otherwise
    ///
    /// # Examples
    ///
    /// ```rust
    /// use trading_engine::performance::check_simd_support;
    ///
    /// if check_simd_support() {
    ///     println!("AVX2 vectorization available");
    /// } else {
    ///     println!("Falling back to scalar operations");
    /// }
    /// ```
    ///
    /// # Performance
    ///
    /// This function has O(1) time complexity and minimal overhead as it's
    /// a simple `CPU` feature detection.
    #[cfg(target_arch = "x86_64")]
    pub fn check_simd_support() -> bool {
        use std::arch;
        arch::is_x86_feature_detected!("avx2")
    }

    /// Check if current `CPU` supports AVX-512
    ///
    /// AVX-512 provides 512-bit vector operations that can process 16 single-precision
    /// floats or 8 double-precision floats simultaneously. This is available on
    /// high-end Intel processors (Skylake-X and later) and some Xeon processors.
    ///
    /// # Returns
    ///
    /// `true` if AVX-512F (foundation) is supported, `false` otherwise
    ///
    /// # Examples
    ///
    /// ```rust
    /// use trading_engine::performance::check_avx512_support;
    ///
    /// if check_avx512_support() {
    ///     println!("AVX-512 ultra-wide vectorization available");
    /// } else {
    ///     println!("Using AVX2 or scalar operations");
    /// }
    /// ```
    ///
    /// # Performance
    ///
    /// This function has O(1) time complexity. Note that AVX-512 operations
    /// may cause `CPU` frequency scaling on some processors.
    #[cfg(target_arch = "x86_64")]
    pub fn check_avx512_support() -> bool {
        use std::arch;
        arch::is_x86_feature_detected!("avx512f")
    }

    /// Get optimal number of worker threads for current `CPU`
    ///
    /// Calculates the optimal number of worker threads for `HFT` operations by
    /// reserving 2 `CPU` cores for the main trading thread and system processes.
    /// This helps avoid `CPU` contention and ensures consistent latency.
    ///
    /// # Returns
    ///
    /// Number of optimal worker threads (minimum 1, typically `CPU` cores - 2)
    ///
    /// # Examples
    ///
    /// ```rust
    /// use trading_engine::performance::optimal_worker_threads;
    ///
    /// let workers = optimal_worker_threads();
    /// println!("Using {} worker threads for parallel processing", workers);
    /// ```
    ///
    /// # Architecture Considerations
    ///
    /// - On 8-core systems: returns 6 worker threads
    /// - On 4-core systems: returns 2 worker threads  
    /// - On 2-core systems: returns 1 worker thread (minimum)
    ///
    /// # Performance
    ///
    /// This function has O(1) time complexity and is safe to call frequently.
    pub fn optimal_worker_threads() -> usize {
        num_cpus::get().saturating_sub(2).max(1)
    }
}

/// Error types for core operations
pub mod error {
    use thiserror::Error;

    /// Core operation errors
    #[derive(Debug, Error)]
    pub enum CoreError {
        /// `SIMD` feature not supported
        #[error("SIMD feature not supported: {feature}")]
        SimdNotSupported { feature: String },

        /// `CPU` affinity operation failed
        #[error("CPU affinity error: {reason}")]
        AffinityError { reason: String },

        /// Lock-free operation failed
        #[error("Lock-free operation failed: {operation}")]
        LockFreeError { operation: String },

        /// Timing operation failed
        #[error("Timing error: {reason}")]
        TimingError { reason: String },

        /// Memory alignment error
        #[error("Memory alignment error: required {required}, got {actual}")]
        AlignmentError { required: usize, actual: usize },
    }

    /// `Result` type for core operations
    pub type CoreResult<T> = Result<T, CoreError>;
}

// Re-export error types at crate level
// REMOVED: All re-exports eliminated from trading_engine