From 5b92ad659e5c31401f90d2ef16d3763c1c0bb903 Mon Sep 17 00:00:00 2001 From: Benjamin Sergeant Date: Tue, 17 Nov 2026 09:55:05 -0800 Subject: [PATCH 1/2] Limit Darwin TSan instrumentation around native thread-local errno access --- ixwebsocket/IXSocket.cpp | 8 ++++++++ test/IXSocketTest.cpp | 24 ++++++++++++++++++++++++ 2 files changed, 32 insertions(+) diff --git a/ixwebsocket/IXSocket.cpp b/ixwebsocket/IXSocket.cpp index d60f1657..8a484c82 100644 --- a/ixwebsocket/IXSocket.cpp +++ b/ixwebsocket/IXSocket.cpp @@ -306,6 +306,11 @@ namespace ix #endif } + // Darwin TSan can confuse reused per-thread errno storage with shared memory. + // These accessors touch only OS thread-local error state; keep callers instrumented. +#if defined(__APPLE__) && defined(__clang__) + __attribute__((no_sanitize("thread"))) +#endif int Socket::getErrno() { int err; @@ -319,6 +324,9 @@ namespace ix return err; } +#if defined(__APPLE__) && defined(__clang__) + __attribute__((no_sanitize("thread"))) +#endif void Socket::setErrno(int err) { #ifdef _WIN32 diff --git a/test/IXSocketTest.cpp b/test/IXSocketTest.cpp index 740090c1..fdc22d98 100644 --- a/test/IXSocketTest.cpp +++ b/test/IXSocketTest.cpp @@ -13,6 +13,7 @@ #include #include #include +#include using namespace ix; @@ -107,6 +108,29 @@ TEST_CASE("Empty and cancelled socket reads do not receive data", "[socket][read CHECK(socket.reads == 0); } +TEST_CASE("Socket error state remains local when threads are reused", "[socket][errno]") +{ + std::atomic isolated {true}; + auto churn = [&](int error) + { + for (int i = 0; i < 16; ++i) + { + std::thread worker( + [&, error] + { + Socket::setErrno(error); + if (Socket::getErrno() != error) isolated = false; + }); + worker.join(); + } + }; + std::thread a(churn, EWOULDBLOCK); + std::thread b(churn, EINVAL); + a.join(); + b.join(); + CHECK(isolated.load()); +} + namespace ix { void testSocket(const std::string& host, From 2c94878a14d64c103edb2a21455116b9197f1fca Mon Sep 17 00:00:00 2001 From: Benjamin Sergeant Date: Tue, 17 Nov 2026 10:42:02 -0800 Subject: [PATCH 2/2] Clarify connection ownership, asynchronous starts and TLS listener setup --- docs/usage.md | 65 +++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 47 insertions(+), 18 deletions(-) diff --git a/docs/usage.md b/docs/usage.md index 592cf682..04112cc1 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -170,6 +170,11 @@ webSocket.setOnMessageCallback([](const ix::WebSocketMessagePtr& msg) 1. `websocket.start()` starts a background thread that connects to the remote server and processes incoming events. 2. `websocket.stop()` requests closure and waits for that background thread to exit. +For parallel connections, configure a separate `ix::WebSocket` for each URL and +call `start()` on each instance. Each connection attempt runs on its own background +thread, so starting another client does not wait for the first handshake. +`connect()` is the synchronous connection API. + ### Threading and callbacks `setOnMessageCallback()` handles Open, Message, Close, Error, Ping, Pong, and Fragment @@ -359,9 +364,21 @@ setHandshakeTimeout(handshakeTimeoutSecs); TLS handshakes run in individual connection workers, so an idle peer does not block other clients from connecting. Server TLS handshakes have a 10-second timeout and are cancelled when the server stops. The maximum connection limit includes clients whose TLS handshake is still pending. -### Legacy api +### Connection setup callback + +`setOnConnectionCallback()` provides a `std::weak_ptr` and a +`ConnectionState` for each accepted connection. Use this API when the application +needs to retain a handle for later asynchronous sends. Register that connection's +message callback inside the setup callback, as shown below. -This api was actually changed to take a weak_ptr as the first argument to setOnConnectionCallback ; previously it would take a shared_ptr which was creating cycles and then memory leaks problems. +Use `connectionState->getId()` as the key in an application registry of weak +pointers. Protect a registry shared by connection callbacks and application threads +with a mutex. To send later, copy the weak pointer while holding the registry lock, +release that lock, then call `lock()` on the weak pointer and send if it succeeds. +An expired weak pointer cannot refer to a later connection, even if its allocation +reuses the same address. Check the send result because the connection can close +after `lock()` succeeds. Capturing a weak pointer also avoids a cycle between the +WebSocket and its own callback. ```cpp #include @@ -375,16 +392,16 @@ std::string host("127.0.0.1"); // If you need this server to be accessible on a ix::WebSocketServer server(port, host); server.setOnConnectionCallback( - [&server](std::weak_ptr webSocket, - std::shared_ptr connectionState) + [&server](std::weak_ptr webSocket, + std::shared_ptr connectionState) { - std::cout << "Remote ip: " << connectionState->remoteIp << std::endl; + std::cout << "Remote ip: " << connectionState->getRemoteIp() << std::endl; auto ws = webSocket.lock(); if (ws) { ws->setOnMessageCallback( - [webSocket, connectionState, &server](const ix::WebSocketMessagePtr msg) + [webSocket, connectionState, &server](const ix::WebSocketMessagePtr& msg) { if (msg->type == ix::WebSocketMessageType::Open) { @@ -418,8 +435,8 @@ server.setOnConnectionCallback( } } } - } - ); + ); + } } ); @@ -442,11 +459,11 @@ server.wait(); ``` -### New api - -The new API does not require to use 2 nested callbacks, which is a bit annoying. The real fix is that there was a memory leak due to a shared_ptr cycle, due to passing down a shared_ptr down to the callbacks. +### Client message callback -The webSocket reference is guaranteed to be always valid ; by design the callback will never be invoked with a null webSocket object. +`setOnClientMessageCallback()` installs one handler for all connections. Its +WebSocket reference is valid for the duration of the callback. Use the connection +setup callback above when a weak handle must outlive an individual callback. ```cpp #include @@ -713,13 +730,25 @@ Then, secure sockets are automatically used when connecting to a `wss://*` url. Additional TLS options can be configured by passing a `ix::SocketTLSOptions` instance to the `setTLSOptions` on `ix::WebSocket` (or `ix::WebSocketServer` or `ix::HttpServer`) +A TLS-enabled build still creates a plain server listener by default. Enable TLS +on the listener before calling `listen()`: + ```cpp -webSocket.setTLSOptions({ - .certFile = "path/to/cert/file.pem", - .keyFile = "path/to/key/file.pem", - .caFile = "path/to/trust/bundle/file.pem", // as a file, or in memory buffer in PEM format - .tls = true // required in server mode -}); +ix::SocketTLSOptions serverTLS; +serverTLS.tls = true; +serverTLS.certFile = "path/to/server-cert.pem"; +serverTLS.keyFile = "path/to/server-key.pem"; +server.setTLSOptions(serverTLS); +``` + +Clients select TLS with a `wss://` URL. For a local server signed by a private CA, +configure the matching trust bundle before starting the client: + +```cpp +ix::SocketTLSOptions clientTLS; +clientTLS.caFile = "path/to/ca.pem"; +webSocket.setTLSOptions(clientTLS); +webSocket.setUrl("wss://localhost:8008"); ``` Specifying `certFile` and `keyFile` configures the certificate that will be used to communicate with TLS peers.