Current Issue
The architecture document describes a mutex strategy that differs from the actual implementation:
Architecture Doc (docs/ARCHITECTURE.md:97):
mutex only applied to RTU/RTU-over-TCP operations, TCP operations execute directly without locking
Actual Implementation (packages/transport/src/manager.ts):
- Both RTU and TCP transports are wrapped with
MutexTransport
- All operations are serialized using async-mutex
- Rationale documented in code comments
Why TCP Needs Mutex (From Implementation)
The code includes detailed rationale:
/**
* Why TCP needs mutex protection:
* - Many Modbus devices allow only one or a limited number of TCP connections
* - Even with multiple connections, devices often process requests sequentially
* - Concurrent requests can cause timeouts, dropped packets, or incorrect responses
* - Serialization ensures reliable communication regardless of device limitations
*/
Proposed Update
Update docs/ARCHITECTURE.md section "Mutex Strategy: Transport-Aware Locking" to reflect the actual implementation:
Current:
**Solution**: Transport-aware locking - mutex only applied to RTU/RTU-over-TCP operations, TCP operations execute directly without locking.
**Rationale**: Maximizes throughput for TCP devices while ensuring RTU safety.
Proposed:
**Solution**: Mutex-based serialization applied to all transports (both RTU and TCP) that share the same physical connection.
**Rationale**:
- **RTU**: Prevents bus collisions on half-duplex serial protocol
- **TCP**: Many Modbus devices support only one connection or process requests sequentially
- Serialization ensures reliable communication regardless of device limitations
- Separate connections maintain concurrency (different RTU ports, different TCP hosts)
Files to Update
docs/ARCHITECTURE.md - Section "Mutex Strategy: Transport-Aware Locking"
Context
Related
Priority
Medium - Documentation accuracy is important for maintainers
Identified during PR #125 review follow-up
Current Issue
The architecture document describes a mutex strategy that differs from the actual implementation:
Architecture Doc (
docs/ARCHITECTURE.md:97):Actual Implementation (
packages/transport/src/manager.ts):MutexTransportWhy TCP Needs Mutex (From Implementation)
The code includes detailed rationale:
Proposed Update
Update
docs/ARCHITECTURE.mdsection "Mutex Strategy: Transport-Aware Locking" to reflect the actual implementation:Current:
Proposed:
Files to Update
docs/ARCHITECTURE.md- Section "Mutex Strategy: Transport-Aware Locking"Context
Related
Priority
Medium - Documentation accuracy is important for maintainers
Identified during PR #125 review follow-up