foxhunt/trading_engine/src/lib.rs

#![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 core::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,
    clippy::indexing_slicing
)]
#![allow(
    // Performance-critical allowances
    clippy::similar_names,
    clippy::module_name_repetitions,
    clippy::too_many_lines
)]

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

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

/// Core trading types with optimized memory layout and financial safety
// TEMPORARILY COMMENTED OUT: Testing for compilation hang - causes circular dependencies
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, SimdPriceOps, SimdRiskEngine,
    SimdMarketDataOps, SafeSimdDispatcher, CpuFeatures, SimdLevel
};

#[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
// TEMPORARILY COMMENTED OUT: Testing for compilation hang
pub mod events;

/// Configuration management system
// Configuration is provided by the config crate
/// Persistence layer with PostgreSQL, `InfluxDB`, Redis, and `ClickHouse`
// TEMPORARILY COMMENTED OUT: Testing for compilation hang
pub mod persistence;

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

/// Repository pattern abstractions for data access
// TEMPORARILY COMMENTED OUT: Testing for compilation hang
pub mod repositories;

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

// ELIMINATED DUPLICATES: These modules were dependent on deleted trading_operations_optimized.rs
// simd_order_processor and hft_performance_benchmark removed - broken dependencies
// Keep only working core trading_operations module

/// Core trading engine and business logic
// TEMPORARILY COMMENTED OUT: Testing for compilation hang
pub mod trading;

/// Broker connectivity and routing
// TEMPORARILY COMMENTED OUT: Testing for compilation hang
pub mod brokers;

/// Unified feature extraction system - prevents training/serving skew
// TEMPORARILY COMMENTED OUT: features module may have dependency issues
// pub mod features;
/// Comprehensive performance benchmarks for `HFT` system validation
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
pub mod advanced_memory_benchmarks;

/// Performance test runner for executing all benchmark suites
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 core::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 core::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 core::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