Skip to content

docs(architecture): update mutex strategy to reflect TCP serialization #134

Description

@groupsky

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions