Chapter 1: Execution Model and Core Objects

This chapter describes the thread model, ownership, object lifetimes, send semantics, and the relationships between the main public objects.

1. What STTNet owns

STTNet wraps Linux epoll, non-blocking sockets, connection state, HTTP framing, WebSocket frames, TLS ownership, cross-thread response queues, backpressure, and graceful shutdown. Application code is centered on callbacks.

Object	Responsibility
HttpServer / WebSocketServer / TcpServer	Listening socket, one main Reactor, connection table, WorkerPool, and metrics.
Handler	Operations for the current connection. Its lifetime normally ends with the current processing flow.
Request / Information	Parsed request or message data, normally scoped to one flow.
WorkerPool	Database, filesystem, RPC, compression, or other blocking work.
ServerSetting	Process-level logging, signal blocking, and synchronous termination wait.

2. Reactor versus Worker

One Server instance is primarily driven by one Reactor thread. The second argument of startListen(port, threads) is the number of WorkerPool threads, not the number of Reactors.

Reactor callbacks are non-blocking execution points. Database queries, file I/O, sleep, external RPC, or unpredictable lock waits pause network progress for other connections on the same event loop.

3. What a successful send means

In a server callback, a successful sendText(), sendJson(), sendData(), or sendMessage() means the payload was accepted by a bounded STTNet write queue. It does not mean the peer has received it.

4. Lifetime rules

Handler references are scoped to the current callback.
headerValue() and bodyView() return non-owning views. Asynchronous or long-lived use requires an owning copy.
The information object's ctx stores small per-flow state shared by processing stages.
Service-level close() belongs to the main or control thread; synchronous Reactor callbacks handle the current connection or request.

5. maxFD is not an OS limit

HttpServer server(100000) only configures STTNet's connection capacity. Process, systemd, and container limits remain independent of the framework setting:

ulimit -n

6. Complete minimal program

#include <sttnet.h>
#include <iostream>

int main()
{
    using namespace stt::network;
    using stt::system::ServerSetting;

    // Block termination signals before framework threads are created.
    if(!ServerSetting::blockTerminationSignals())
        return 1;

    HttpServer server;

    server.setFunction("/ping",
        [](HttpServerFDHandler &client, HttpRequestInformation &) {
            // 1: stage succeeded; -2: send failed and close the connection.
            return client.sendText("pong") ? 1 : -2;
        });

    if(!server.startListen(8080))
        return 2;

    std::cout << "http://127.0.0.1:8080/ping\n";
    ServerSetting::waitForTerminationSignal();
    return server.close() ? 0 : 3;
}