µWebSockets

For the high-performance applications µWebSockets is designed for, "hello world" benchmarks (such as message echoing of 512 bytes to 16 kB) are the most accurate way to gauge performance. These tests measure the efficiency of the core server plumbing:

1. Receive
2. Timeout clear
3. Emit to app
4. Timeout set
5. Send

This type of benchmarking is highly relevant for latency-sensitive or high-concurrency use cases like:

• IO-gaming (latency)
• Signalling (memory overhead)
• Trading/Finance (latency)
• Chatting/Notifications (memory overhead)

Sending data on a WebSocket can build up backpressure.

1. Check return values: ws.send() returns an enum: SUCCESS, BACKPRESSURE, or DROPPED.
2. Handle BACKPRESSURE: If send returns BACKPRESSURE, stop sending data until the .drain event fires.
3. Handle DROPPED: If you configured maxBackpressure in your context, an attempt to send that exceeds the limit will return DROPPED, meaning the message was canceled and not queued.
4. Monitor buffer: Use ws.getBufferedAmount() inside the .drain handler to check if the buffer has cleared.

µWebSockets is designed with minimalism and performance in mind. Key architectural concepts include:

• Async-only & Single-threaded: The implementation is asynchronous and runs locally to a single thread. It is not thread-safe.
• Scaling: To scale, you should run multiple individual threads, similar to how Node.js scales using individual processes.
• Protocol Handling: The library handles boilerplate logic such as heartbeat timeouts, backpressure, and ping/pong automatically, allowing you to focus on business logic.
• Interface: It follows an ExpressJS-like interface where you attach callbacks to specific URL routes.

Avoid calling res.end(huge_buffer) as it can cause massive backpressure spikes. Instead, stream data part-by-part using res.tryEnd() in combination with res.onWritable and res.onAborted callbacks.

Using Corking for Performance

Corking is critical for efficient data packing and sending. While simple cases are corked by default, you should manually wrap multiple send calls in res->cork() to ensure they are sent in a single syscall/SSL block.

res->cork([res]() {
    res->end("This Http response will be properly corked and efficient in all cases");
});

µWebSockets allows you to control the compiled composition of the networking stack using build flags. This is useful for choosing between different cryptography libraries (like OpenSSL or WolfSSL) and event-loop integrations (like libuv).

Common build commands:

• To build examples using WolfSSL and libuv: WITH_WOLFSSL=1 WITH_LIBUV=1 make examples
• To build examples using OpenSSL and the native kernel: WITH_OPENSSL=1 make examples

To start a µWebSockets server, construct an App (for regular TCP) or an SSLApp (for TLS/SSL). The uWS::SSLApp constructor requires a struct containing SSL options like cert and key. Both app types share the same interface and follow the builder pattern, allowing you to chain method calls.

Note: The library is single-threaded. A socket created on one thread cannot be used on another. The only thread-safe function is Loop::defer, which schedules a function to run on the loop's specific thread.

uWS::App().get("/hello", [](auto *res, auto *req) {
    res->end("Hello World!");
});

µWebSockets is a header-only C++17 library that depends on uSockets (a platform-specific C project for Linux, macOS, and Windows).

On Linux and macOS, you can use the provided Makefile to build the library and its examples. To build all examples with SSL enabled, use the WITH_OPENSSL=1 flag. Note that SSL examples require valid certificate and key paths to listen successfully.

WITH_OPENSSL=1 make

To start a server, instantiate uWS::App for non-SSL connections or uWS::SSLApp for SSL connections. The App class uses a builder pattern to configure routes, WebSocket behaviors, and listening parameters. The application operates on an implicit thread-local Loop.

Basic usage involves configuring routes and then calling .run() to start the event loop.

#include "App.h"

int main() {
    uWS::App()
        .get("/hello", [](auto *res, auto *req) {
            res->end("Hello World!");
        })
        .listen(3000, [](auto *listen_socket) {
            if (listen_socket)
                std::cout << "Listening on port 3000" << std::endl;
        })
        .run();
}

When benchmarking µWebSockets, avoid using scripted Node.js clients like autocannon or ws. Because µWebSockets is significantly faster than Node.js (up to 12x), a standard Node.js client will likely become the bottleneck before µWebSockets reaches its limit.

To ensure an accurate benchmark, you must verify that µWebSockets is being stressed to 100% CPU-time. If the CPU usage of the µWebSockets process is not at 100%, you are benchmarking the performance of your client rather than the server.