orange-guo created GUACAMOLE-2124:
-------------------------------------
Summary: Replace pthread_key_t with scalable thread-local storage
to overcome 1024 key limitation
Key: GUACAMOLE-2124
URL: https://issues.apache.org/jira/browse/GUACAMOLE-2124
Project: Guacamole
Issue Type: Improvement
Affects Versions: 1.6.0
Reporter: orange-guo
h2. Problem Statement
During production testing, we discovered that guacd fails when handling more
than approximately 60 concurrent SSH connections with the error message
indicating pthread key exhaustion (exceeding 1024 limit).
This is a critical scalability limitation that prevents Guacamole from
supporting high-concurrency deployments.
*Error observed:*
pthread_key_create failed: Resource temporarily unavailable
h2. *Root Cause Analysis*
The issue stems from the pthread implementation's hard limit of 1024
thread-specific storage keys per process (PTHREAD_KEYS_MAX).
Each connection appears to consume multiple pthread keys through:
1. Error handling system (src/libguac/error.c): Uses pthread_key_t for
thread-local error state
2. Reentrant rwlock implementation (src/libguac/rwlock.c): Uses pthread_key_t
to track per-thread lock ownership
With multiple connections, the cumulative pthread key usage quickly exceeds the
system limit.
h2. *Proposed Solution*
Replace pthread_key_t usage with a custom thread-local storage implementation
that:
1. Eliminates the 1024 key limit by using hash-table based storage
2. Maintains API compatibility with existing pthread_key_t usage patterns
3. Improves performance by using direct __thread storage where possible
4. Preserves thread safety and cleanup semantics
h2. Expected benefit:
This change should allow guacd to handle hundreds of concurrent connections
instead of being limited to ~60 SSH connections.
h2. Request
We would like to contribute this enhancement to improve Guacamole's scalability
for high-concurrency deployments. The implementation is ready for review and
testing.
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
