Fix AsyncFuzzExecutor docs to match implementation and fix blocking s… (#116)

* Fix AsyncFuzzExecutor docs to match implementation and fix blocking stdio reads

Author: Agent-Hellboy

docs/architecture/architecture.md

@@ -665,22 +665,20 @@ The `AsyncFuzzExecutor` provides controlled concurrency and robust error handlin
 
 **Error Handling:**
 
-- **Timeout Management**: Configurable timeouts for individual operations
-- **Retry Logic**: Exponential backoff retry mechanism for failed operations
-- **Exception Collection**: Collects and categorizes errors from batch operations
+- **Automatic Error Collection**: Automatically collects and categorizes errors from batch operations
+- **Thread Pool Support**: Handles both async and sync operations via thread pool
+- **Hypothesis Integration**: Wraps Hypothesis strategies to prevent asyncio deadlocks
+- **Graceful Failure**: Operations can fail without stopping the entire batch
 
 **Configuration Options:**
 
 - `max_concurrency`: Maximum number of concurrent operations (default: 5)
-- `timeout`: Default timeout for operations (default: 30.0 seconds)
-- `retry_count`: Number of retries for failed operations (default: 1)
-- `retry_delay`: Delay between retries (default: 1.0 seconds)
 
 **Usage Patterns:**
 
-- **Single Operations**: Execute individual operations with timeout and error handling
-- **Retry Operations**: Execute operations with automatic retry on failure
-- **Batch Operations**: Execute multiple operations concurrently with bounded concurrency
+- **Batch Operations**: Execute multiple operations concurrently with bounded concurrency and automatic error collection
+- **Mixed Operations**: Handle both async and sync operations in the same batch
+- **Hypothesis Strategies**: Run Hypothesis strategies safely in thread pool
 
 ## Execution Flow
 

docs/architecture/async-executor.md

@@ -1,6 +1,6 @@
 # Async Executor
 
-The AsyncFuzzExecutor is a core component that bridges the strategy components (test case generators) and the fuzzing engine. It provides a robust asynchronous execution framework with concurrency control, error handling, and retry mechanisms.
+The AsyncFuzzExecutor is a core component that bridges the strategy components (test case generators) and the fuzzing engine. It provides a robust asynchronous execution framework with semaphore-based concurrency control and error handling.
 
 ## Architecture
 
@@ -12,75 +12,101 @@ graph TD
     B -->|Execute with Concurrency Control| C[Fuzzing Engine]
     C -->|Results| D[Result Collection]
     B -->|Error Handling| E[Error Processing]
-    B -->|Retry Logic| F[Retry Mechanism]
+    B -->|Thread Pool| F[Sync Operations]
 ```
 
 ## Features
 
-- **Concurrency Control**: Limits the number of concurrent operations to prevent resource exhaustion
-- **Timeout Handling**: Enforces timeouts on operations to prevent hanging
-- **Error Handling**: Captures and processes exceptions from operations
-- **Retry Mechanism**: Automatically retries failed operations with exponential backoff
+- **Concurrency Control**: Uses semaphore to limit the number of concurrent operations
+- **Error Handling**: Captures and collects exceptions from operations automatically
 - **Batch Execution**: Executes multiple operations concurrently with result aggregation
-- **Resource Management**: Proper cleanup of resources during shutdown
+- **Mixed Execution**: Handles both async and sync operations via thread pool
+- **Hypothesis Integration**: Wraps Hypothesis strategies to prevent asyncio deadlocks
+- **Resource Management**: Proper cleanup of thread pool resources during shutdown
 
 ## Usage
 
-### Basic Execution
+### Batch Execution
 
 ```python
 from mcp_fuzzer.fuzz_engine.executor import AsyncFuzzExecutor
 
 # Create an executor with max concurrency of 5
 executor = AsyncFuzzExecutor(max_concurrency=5)
 
-# Execute an async operation
-async def my_operation(value):
-    # Some async operation
-    return value * 2
-
-result = await executor.execute(my_operation, 10)
+try:
+    # Define an async operation
+    async def my_operation(value):
+        # Some async operation
+        return value * 2
+
+    # Prepare operations as (function, args, kwargs) tuples
+    operations = [
+        (my_operation, [5], {}),
+        (my_operation, [10], {}),
+        (my_operation, [15], {})
+    ]
+
+    # Execute all operations concurrently
+    results = await executor.execute_batch(operations)
+
+    # Process successful results
+    for result in results["results"]:
+        print(f"Success: {result}")
+
+    # Process errors
+    for error in results["errors"]:
+        print(f"Error: {error}")
+
+finally:
+    # Shutdown the executor and clean up resources
+    await executor.shutdown()
 ```
 
-### Retry Mechanism
+### Error Handling
 
 ```python
-# Execute with retry
-result = await executor.execute_with_retry(
-    my_operation,
-    10,
-    retry_count=3,
-    retry_delay=1.0
-)
+async def operation_with_errors(value):
+    if value % 2 == 0:
+        raise ValueError(f"Even value not allowed: {value}")
+    return value * 2
+
+# Errors are automatically collected
+operations = [(operation_with_errors, [i], {}) for i in range(10)]
+results = await executor.execute_batch(operations)
+
+print(f"Successful: {len(results['results'])}")
+print(f"Failed: {len(results['errors'])}")
 ```
 
-### Batch Execution
+### Mixed Async and Sync Operations
 
 ```python
-# Define multiple operations
+# Async operation
+async def async_op():
+    await asyncio.sleep(0.1)
+    return "async"
+
+# Sync operation (runs in thread pool)
+def sync_op():
+    return sum(range(1000))
+
 operations = [
-    (my_operation, [5], {}),
-    (my_operation, [10], {}),
-    (my_operation, [15], {})
+    (async_op, [], {}),
+    (sync_op, [], {})
 ]
 
-# Execute all operations concurrently
 results = await executor.execute_batch(operations)
-
-# Process successful results
-for result in results["results"]:
-    print(f"Success: {result}")
-
-# Process errors
-for error in results["errors"]:
-    print(f"Error: {error}")
 ```
 
-### Cleanup
+### Hypothesis Strategy Integration
 
 ```python
-# Shutdown the executor and clean up resources
-await executor.shutdown()
+from hypothesis import strategies as st
+
+# Run Hypothesis strategy without asyncio deadlocks
+int_strategy = st.integers(min_value=0, max_value=100)
+value = await executor.run_hypothesis_strategy(int_strategy)
 ```
 
 ## Integration with Fuzzing Components
@@ -96,6 +122,13 @@ This separation of concerns allows for better maintainability and scalability of
 ## Configuration Options
 
 - **max_concurrency**: Maximum number of concurrent operations (default: 5)
-- **timeout**: Default timeout for operations in seconds (default: 30.0)
-- **retry_count**: Number of retries for failed operations (default: 1)
-- **retry_delay**: Delay between retries in seconds (default: 1.0)
+
+## API Methods
+
+- `async execute_batch(operations) -> Dict[str, List]`: Execute a batch of operations
+  - Operations format: `[(function, args, kwargs), ...]`
+  - Returns: `{"results": [...], "errors": [...]}`
+
+- `async run_hypothesis_strategy(strategy) -> Any`: Run Hypothesis strategy in thread pool
+
+- `async shutdown() -> None`: Shutdown executor and clean up thread pool

docs/components/process-management-guide.md

@@ -248,9 +248,7 @@ import os
 
 # Use CPU count for CPU-bound operations
 cpu_executor = AsyncFuzzExecutor(
-    max_concurrency=os.cpu_count(),
-    timeout=60.0,
-    retry_count=1
+    max_concurrency=os.cpu_count()
 )
 ```
 
@@ -259,9 +257,7 @@ cpu_executor = AsyncFuzzExecutor(
 ```python
 # Use higher concurrency for I/O-bound operations
 io_executor = AsyncFuzzExecutor(
-    max_concurrency=os.cpu_count() * 2,
-    timeout=30.0,
-    retry_count=2
+    max_concurrency=os.cpu_count() * 2
 )
 ```
 
@@ -270,37 +266,13 @@ io_executor = AsyncFuzzExecutor(
 ```python
 # Conservative concurrency for network operations
 network_executor = AsyncFuzzExecutor(
-    max_concurrency=10,
-    timeout=15.0,
-    retry_count=3,
-    retry_delay=0.5
+    max_concurrency=10
 )
 ```
 
 ### Error Handling Patterns
 
-#### Retry with Exponential Backoff
-
-```python
-async def robust_operation():
-    executor = AsyncFuzzExecutor(
-        retry_count=3,
-        retry_delay=1.0  # Base delay, will be doubled each retry
-    )
-
-    async def unreliable_operation():
-        # Operation that might fail
-        pass
-
-    try:
-        result = await executor.execute_with_retry(unreliable_operation)
-        return result
-    except Exception as e:
-        logger.error(f"Operation failed after retries: {e}")
-        raise
-```
-
-#### Batch Processing with Error Collection
+#### Batch Processing with Automatic Error Collection
 
 ```python
 async def batch_processing_example():
@@ -473,9 +445,7 @@ debug_config = WatchdogConfig(
 
 ```python
 debug_executor = AsyncFuzzExecutor(
-    max_concurrency=1,       # Single operation for debugging
-    timeout=5.0,             # Shorter timeout
-    retry_count=0            # No retries for debugging
+    max_concurrency=1        # Single operation for debugging
 )
 ```
 

docs/components/process-management.md

@@ -56,37 +56,28 @@ import asyncio
 async def main():
     # Create executor with concurrency control
     executor = AsyncFuzzExecutor(
-        max_concurrency=5,  # Maximum concurrent operations
-        timeout=30.0,      # Default timeout in seconds
-        retry_count=2,     # Number of retries for failed operations
-        retry_delay=1.0    # Delay between retries in seconds
+        max_concurrency=5  # Maximum concurrent operations
     )
 
-    # Define an async operation
-    async def my_operation(value):
-        await asyncio.sleep(0.1)  # Simulate work
-        return value * 2
-
-    # Execute a single operation
-    result = await executor.execute(my_operation, 5)
-    print(f"Single operation result: {result}")
-
-    # Execute with retry mechanism
-    result = await executor.execute_with_retry(my_operation, 10)
-    print(f"Operation with retry: {result}")
+    try:
+        # Define an async operation
+        async def my_operation(value):
+            await asyncio.sleep(0.1)  # Simulate work
+            return value * 2
 
-    # Execute batch operations concurrently
-    operations = [
-        (my_operation, [5], {}),
-        (my_operation, [10], {}),
-        (my_operation, [15], {})
-    ]
+        # Execute batch operations concurrently
+        operations = [
+            (my_operation, [5], {}),
+            (my_operation, [10], {}),
+            (my_operation, [15], {})
+        ]
 
-    batch_results = await executor.execute_batch(operations)
-    print(f"Batch results: {batch_results['results']}")
+        batch_results = await executor.execute_batch(operations)
+        print(f"Batch results: {batch_results['results']}")
 
-    # Shutdown the executor
-    await executor.shutdown()
+    finally:
+        # Shutdown the executor
+        await executor.shutdown()
 
 asyncio.run(main())
 ```