PoKeys Thread - Advanced Threading System

Advanced threading architecture for multi-device PoKeys applications. This library provides thread-safe multi-device management with per-device threads, state synchronization, and concurrent operations.

✨ Key Features

Multi-Device Threading

• Per-Device Threads: Each device operates in its own dedicated thread
• Thread Safety: Safe concurrent access to device resources
• State Synchronization: Automatic state management across threads
• Output State Tracking: Comprehensive tracking of device output states

Concurrent Operations

• Non-Blocking Operations: Device operations don't block other devices
• Parallel Processing: Multiple devices can be controlled simultaneously
• Event-Driven Architecture: Responsive to device state changes
• Resource Management: Automatic cleanup and resource management

Performance Benefits

• Scalability: Efficiently handles multiple devices
• Responsiveness: Real-time device interaction
• Isolation: Device failures don't affect other devices
• Load Distribution: Balanced workload across threads

🚀 Quick Start

Add this to your Cargo.toml:

[dependencies]
pokeys-thread = { git = "https://github.com/pokeys-toolkit/thread" }
pokeys-lib = { git = "https://github.com/pokeys-toolkit/core" }

📖 Usage Examples

Basic Multi-Device Threading

use pokeys_thread::*;

fn main() -> Result<()> {
    // Create thread controller
    let mut controller = ThreadControllerBuilder::new()
        .default_refresh_interval(100)
        .build();

    // Start device threads
    let devices = controller.discover_usb_devices()?;
    for device_id in devices {
        controller.start_usb_device_thread(device_id)?;
    }

    // Control devices concurrently
    // Each device operates in its own thread
    Ok(())
}

State Observer Pattern

use pokeys_thread::*;

fn main() -> Result<()> {
    let mut controller = ThreadControllerBuilder::new().build();
    
    // Start device thread
    controller.start_usb_device_thread(12345678)?;
    
    // Observe state changes
    let observer = controller.create_state_observer(12345678)?;
    
    loop {
        if let Some(state) = observer.get_latest_state() {
            println!("Device state updated: {:?}", state);
        }
        std::thread::sleep(std::time::Duration::from_millis(100));
    }
}

Device Operations

use pokeys_thread::*;

fn main() -> Result<()> {
    let mut controller = ThreadControllerBuilder::new().build();
    controller.start_usb_device_thread(12345678)?;
    
    // Non-blocking device operations
    controller.set_digital_output(12345678, 1, true)?;
    controller.set_pwm_duty_cycle(12345678, 0, 50.0)?;
    
    // Read device state
    let analog_value = controller.read_analog_input(12345678, 1)?;
    println!("Analog input 1: {}", analog_value);
    
    Ok(())
}

🏗️ Architecture

Thread Controller

The ThreadController is the main entry point for managing device threads:

• Device Discovery: Automatic USB and network device discovery
• Thread Management: Start, stop, and monitor device threads
• Operation Dispatch: Route operations to appropriate device threads
• State Management: Centralized state tracking and synchronization

Device Threads

Each device runs in its own dedicated thread:

• Isolated Execution: Device operations don't interfere with each other
• Automatic Refresh: Periodic device state updates
• Error Handling: Per-device error isolation and recovery
• Resource Cleanup: Automatic resource management on thread termination

State Synchronization

Thread-safe state management:

• Atomic Operations: Lock-free state updates where possible
• Consistent Views: Guaranteed consistent state snapshots
• Change Notifications: Event-driven state change notifications
• Output Tracking: Comprehensive output state tracking

🔧 Configuration

Thread Controller Builder

let controller = ThreadControllerBuilder::new()
    .default_refresh_interval(50)  // 50ms refresh rate
    .max_retry_attempts(3)         // Retry failed operations
    .timeout_duration(5000)        // 5 second timeout
    .enable_logging(true)          // Enable debug logging
    .build();

Per-Device Configuration

controller.configure_device_thread(device_id, |config| {
    config
        .refresh_interval(25)      // 25ms for high-speed device
        .priority_mode(true)       // High priority thread
        .buffer_size(1024)         // Larger communication buffer
});

📚 Examples

The examples/ directory contains comprehensive examples:

# Simple controller setup
cargo run --example simple_controller

# State observation patterns
cargo run --example state_observer

# Device operation examples
cargo run --example device_operations

# Logging and debugging
cargo run --example logging_example

# Comprehensive multi-device example
cargo run --example comprehensive_example

🛡️ Safety & Reliability

Thread Safety

• Lock-Free Operations: Minimal locking for maximum performance
• Deadlock Prevention: Careful lock ordering and timeout mechanisms
• Resource Protection: Protected access to shared device resources

Error Handling

• Isolated Failures: Device errors don't propagate to other devices
• Automatic Recovery: Built-in retry and recovery mechanisms
• Graceful Degradation: System continues operating with failed devices

Performance

• Minimal Overhead: Efficient thread management and communication
• Scalable Architecture: Handles dozens of devices efficiently
• Memory Efficient: Careful memory management and cleanup

🧪 Testing

Run the test suite:

# Unit tests
cargo test

# Integration tests (requires hardware)
cargo test --features hardware-tests

# Performance benchmarks
cargo test --release --features benchmarks

🤝 Contributing

We welcome contributions! Please ensure:

• All tests pass
• Code follows Rust conventions
• Thread safety is maintained
• Documentation is updated

📄 License

This project is licensed under the LGPL-2.1 License - see the LICENSE file for details.

🔗 Related Projects

• PoKeys Core - Core library
• PoKeys CLI - Command-line interface
• PoKeys Model Manager - Device model management

Perfect for: Industrial automation, multi-device control systems, responsive GUI applications, and any scenario requiring concurrent PoKeys device management.