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

//! 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
//! }
//! ```

#![allow(missing_docs)] // Internal implementation details
#![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 _;

/// 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;

#[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;

/// 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 {
    //! Performance-related constants and utilities

    /// 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 {
    //! Core error types and utilities

    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